CR.instrument

__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

• jQuery Selectors
• jQuery text values
• JavaScript Functions
• __CR.ready
• Tracking Queue