Difference between revisions of "CR.instrument"

From Market Ruler Help
Jump to: navigation, search
(Created page with "<code>__CR.instrument</code> is a function available in the ConversionRuler JavaScript Global, and is of type <code>function</code>. The method signature for this is:...")
 
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
<code>__CR.instrument</code> is a function available in the [[ConversionRuler JavaScript Global]], and is of type <code>function</code>.  
 
<code>__CR.instrument</code> is a function available in the [[ConversionRuler JavaScript Global]], and is of type <code>function</code>.  
 +
 +
== __CR.instrument method ==
  
 
The method signature for this is:
 
The method signature for this is:
Line 7: Line 9:
 
Where:
 
Where:
  
* '''specification''' - is an object which contains keys which map to [https://api.jquery.com/category/selectors/ jQuery Selectors] for elements on the page and values which represent how data is to be stored in the [[__CR.data|CR.data]] structure
+
* '''specification''' - is an object which contains keys which map to [https://api.jquery.com/category/selectors/ jQuery Selectors] for elements on the page and values which represent how data is to be stored in the [[__CR.data|__CR.data]] structure
 
* '''timeout''' - Is an integer specified in seconds, and if not specified defaults to 10 seconds. This represents the amount of time ConversionRuler will actively search for elements to instrument on the page.
 
* '''timeout''' - Is an integer specified in seconds, and if not specified defaults to 10 seconds. This represents the amount of time ConversionRuler will actively search for elements to instrument on the page.
 +
 +
== Example ==
  
 
Example usage:
 
Example usage:
Line 15: Line 19:
 
  __CR.instrument({
 
  __CR.instrument({
 
     "input[type=email]": "email",
 
     "input[type=email]": "email",
 +
    "input[name=email]": "email",
 
     "input[autocomplete=email]": "email",
 
     "input[autocomplete=email]": "email",
 +
    ".email input": "email",
 +
    ".realed-field-usr input": "email",
 
     "input[name*=company]": "company",
 
     "input[name*=company]": "company",
 
  }, -1);
 
  }, -1);
Line 22: Line 29:
 
The instrumentation code operates as follows:
 
The instrumentation code operates as follows:
  
# The selectors you specified are "searched for" on the page, if they are found they are "connected" such that changes to the values in the inputs will be reflected immediately in the same value stored in <code>__CR.data("...")</code>
+
# The selectors you specified are "searched for" on the page, if they are found they are connected using event handlers such that changes to the values in the inputs will be reflected immediately in the same value stored in <code>__CR.data("...")</code>
 
# The "connecting" process is what the <code>timeout</code> values refer to - this depends on whether you are instrumenting a site where the page changes (like a web application) then you would want to have this continuously running and instrumenting inputs as the page changes.  
 
# The "connecting" process is what the <code>timeout</code> values refer to - this depends on whether you are instrumenting a site where the page changes (like a web application) then you would want to have this continuously running and instrumenting inputs as the page changes.  
  
 
The type of target you specify using the [https://api.jquery.com/category/selectors/ jQuery Selector] changes how the item value is saved:
 
The type of target you specify using the [https://api.jquery.com/category/selectors/ jQuery Selector] changes how the item value is saved:
  
- If your target is an <code>:input</code> then the value is updated whenever the control changes.  
+
* If your target is an <code>:input</code> then the value is updated whenever the control changes.  
- If it is <code>&lt;input type=&quot;hidden&quot; ...&gt;</code> then the value is updated if the value changes. This allows support of 3rd-party widgets which manipulate hidden fields on a form, for example
+
* If it is <code>&lt;input type=&quot;hidden&quot; ...&gt;</code> then the value is updated if the value changes. This allows support of 3rd-party widgets which manipulate hidden fields on a form, for example
- For targets which are static page content such as text or static values, the values will reflect the most recent value of the jQuery [https://api.jquery.com/text/ text] call for that selector and stored in the <code>__CR.data("...")</code>
+
* For targets which are static page content such as text or static values, the values will reflect the most recent value of the jQuery [https://api.jquery.com/text/ text] call for that selector and stored in the <code>__CR.data("...")</code>
  
 
A few other properties of this tools:
 
A few other properties of this tools:
  
- Values stored in the data values are stored as strings, are always trimmed of whitespace, - The system will '''never''' store empty values - this avoids pages which load blank forms to not override existing values
+
* Values stored in the data values are stored as strings, are always trimmed of whitespace, * The system will '''never''' store empty values - this avoids pages which load blank forms to not override existing values
 +
 
 +
== Considerations ==
 +
 
 +
* Test your code and identify which selectors match which elements on which pages first.
 +
* Do not specify selectors which are too broad (such as <code>*</code> or <code>div</code> for example) as this will likely kill the performance of your site.
 +
* Do not store large amounts of data - this information ''may be'' stored as browser cookies and as such will not support data more than ~1000 characters. Generally speaking, data collection should be reserved for small data values for efficiency.
  
 +
== In operation ==
  
 +
This function is best used to silently collect and save information on your site as users navigate through the site's forms. When you are ready to record your actions, fetch the data you wish to record simply using [[__CR.data]] calls with [[__CR.track]].
  
 
This function is only available as of ''May 1, 2020''.
 
This function is only available as of ''May 1, 2020''.

Latest revision as of 19:32, 11 May 2020

__CR.instrument is a function available in the ConversionRuler JavaScript Global, and is of type function.

__CR.instrument method

The method signature for this is:

   __CR.instrument(specification, timeout);

Where:

  • specification - is an object which contains keys which map to jQuery Selectors for elements on the page and values which represent how data is to be stored in the __CR.data structure
  • timeout - Is an integer specified in seconds, and if not specified defaults to 10 seconds. This represents the amount of time ConversionRuler will actively search for elements to instrument on the page.

Example

Example usage:

<script>
__CR.instrument({
   "input[type=email]": "email",
   "input[name=email]": "email",
   "input[autocomplete=email]": "email",
   ".email input": "email",
   ".realed-field-usr input": "email",
   "input[name*=company]": "company",
}, -1);
</script>

The instrumentation code operates as follows:

  1. The selectors you specified are "searched for" on the page, if they are found they are connected using event handlers such that changes to the values in the inputs will be reflected immediately in the same value stored in __CR.data("...")
  2. The "connecting" process is what the timeout values refer to - this depends on whether you are instrumenting a site where the page changes (like a web application) then you would want to have this continuously running and instrumenting inputs as the page changes.

The type of target you specify using the jQuery Selector changes how the item value is saved:

  • If your target is an :input then the value is updated whenever the control changes.
  • If it is <input type="hidden" ...> then the value is updated if the value changes. This allows support of 3rd-party widgets which manipulate hidden fields on a form, for example
  • For targets which are static page content such as text or static values, the values will reflect the most recent value of the jQuery text call for that selector and stored in the __CR.data("...")

A few other properties of this tools:

  • Values stored in the data values are stored as strings, are always trimmed of whitespace, * The system will never store empty values - this avoids pages which load blank forms to not override existing values

Considerations

  • Test your code and identify which selectors match which elements on which pages first.
  • Do not specify selectors which are too broad (such as * or div for example) as this will likely kill the performance of your site.
  • Do not store large amounts of data - this information may be stored as browser cookies and as such will not support data more than ~1000 characters. Generally speaking, data collection should be reserved for small data values for efficiency.

In operation

This function is best used to silently collect and save information on your site as users navigate through the site's forms. When you are ready to record your actions, fetch the data you wish to record simply using __CR.data calls with __CR.track.

This function is only available as of May 1, 2020.

See also