Jump to Table of Contents

Infinity JavaScript API Reference

This Article provides details of the public methods in our JavaScript Library, and some attributes that can be added to individual elements to modify behaviour. Useful for complex code scenarios.

JavaScript API Methods are documented here for your reference, you can refer to other articles in this Knowledge Base for information on specific use-cases.

The code examples here use examples in place of all the parameters that you will need to define in each method call.
Do not copy any of the code examples that contain parameters into your site without modifying and understanding what they do.

Method: _setIgrp

Sets the Installation ID to use for tracking and number allocation requests

/**
 * _setIgrp
 *
 * @param Integer igrp The Installation (IGRP) ID
 */

// example usage
_ictt.push(['_setIgrp', 1]);

Method: _enableGAIntegration

Enables Integration with GUA (Universal Analytics) and/or GA (classic)

/**
 * _enableGAIntegration
 *
 * @param Object (Properties described below by object param key)
 * @param Object.gua Boolean gua (Default: false)              Should JavaScript integration be enabled with Universal Analytics
 * @param Object.ga Boolean ga (Default: true)                 Should JavaScript integration be enabled with GA Classic
 * @param Object.guaVar String guaVar (Optional, Default: 'ga') The name of the variable that the Google Universal Analytics library is exposed as
 */

// example usage (most common)
_ictt.push(['_enableGAIntegration', {'gua':true,'ga':false}]);

// example usage (legacy/ga classic only)
_ictt.push(['_enableGAIntegration', {'gua':false,'ga':true}]);

Method: _enableAutoDiscovery

Enables auto discovery mode

/**
 * _enableAutoDiscovery
 */

// example usage
_ictt.push(['_enableAutoDiscovery']);

Method: _setAutoDiscoveryClasses

Sets a list of classes to be used when looking for elements in auto discovery mode.

/**
 * _setAutoDiscoveryClasses
 *
 * @param Array classes The list of classes
 */

// example usage
_ictt.push(['_setAutoDiscoveryClasses', ['tel-number', 'MyCustomPhoneClass']]);

Method: _getCookies

Retrieves cookies that include the name provided. Whitespace is trimmed from the beginning and end of 'name'

So; ' some ' becomes 'some'

and would match cookies named something, isometric and awesome

/**
 * _getCookies
 *
 * @param String name The string to match cookie names on
 * @return Boolean|Array false if no matches are found, or an array of key=>value pairs if at leats 1 match is found.
 */

// example usage
_ictt.push(['_getCookies', 'some']);

Method: _setPageTag

Adds a page tag name and value, to be sent with the tracking request.

/**
 * _setPageTag
 *
 * @param Array (Properties described below by index position
 * @param Array:0 String Key   The key to use when sending this tag
 * @param Array:1 String Value The value you want to store against the supplied key
 */

// example usage
_ictt.push(['_setPageTag', ['clients_key', 'clients_custom_value']]);

Method: _setCustomVar

Adds a custom var name and value, to be sent with tracking and number allocation requests

/**
 * _setCustomVar
 *
 * @param Array (Properties described below by index position
 * @param Array:0 String Key   The key to use when sending this var
 * @param Array:1 String Value The value you want to store against the supplied key
 */

// example usage
_ictt.push(['_setCustomVar', ['clients_key', 'clients_custom_value']]);

Method: _setSegment

Sets the segment to use for subsequent tracking and number allocation requests

/**
 * _setSegment
 *
 * @param Integer segment The Segment ID
 */

// example usage
_ictt.push(['_setSegment', 123]);

Method: _setTrackingDomain

Sets the domain to use when sending tracking requests

/**
 * _setTrackingDomain
 *
 * @param String domain The domain to send the relevant network requests to
 */

// example usage
_ictt.push(['_setTrackingDomain', 'example.com']);

Method: _setAllocationDomain

Sets the domain to use when sending allocation requests

/**
 * _setAllocationDomain
 *
 * @param String domain The domain to send the relevant network requests to
 */

// example usage
_ictt.push(['_setAllocationDomain', 'example.com']);

Method: _disableNumberReplacement

Disables any further number replacement.

/**
 * _disableNumberReplacement
 */

// example usage
_ictt.push(['_disableNumberReplacement']);

Method: _enableNumberReplacement

Enables further number replacement.

/**
 * _enableNumberReplacement
 */

// example usage
_ictt.push(['_enableNumberReplacement']);

Method: _setReferrer

Sets the referrer to use for tracking and number allocation requests.

/**
 * _setReferrer
 *
 * @param String referrer The referrer to use, which replaces the 'actual' referrer
 */

// example usage
_ictt.push(['_setReferrer', 'http://www.example.com/page?foo=bar']);

Method: _setDomain

Sets the domain to use for site landing comparison checks.

This is primarily useful if you have a single domain, broken down into sections using paths, and want to track each one as a separate installation.
You would only call this method on the landing page of a section, when a user has browsed from a different section.

As long as the domain you set is different to the actual domain being tracked, then it will be seen as a land.

/**
 * _setDomain
 *
 * @param String domain The domain to use, which replaces the 'actual' domain of the href, but only for the landing comparison (not for recorded tracking data)
 */

// example usage
_ictt.push(['_setDomain', 'example.com.section1']);

Method: _includeExternal

Includes externally defined globally accessible vars/functions as page tag or custom vars (or by calling a globally available callback)

This method has been designed to work with variables/functions/cookies that may not immediately be available, it will keep trying to find the variables/functions that you defined in 'from' (or cookie using fromCookie), and execute the 'to' call as soon as it's available (or the maximum loop time of 1 second has passed).
This can be useful if you want to use a global variable into _setCustomVar etc, but the variable is only set by another library soon after the page has loaded.

/**
 * _includeExternal
 *
 * @param Array [Object, Object2] (Properties described below by object param key)
 * At least one of from, or fromCookie must be defined, in addition to 'to'
 * @param Object.from String from              The global variable, or function to fetch the value from that you want to send 
 * @param Object.fromCookie String fromCookie  The cookie name to fetch the value from that you want to send 
 * @param Object.to String to                  The method name that you want to call to handle the resulting 'from' value
 * @param Object.as String as                  (Optional, defaults to value of 'from' property) The name that the value should be sent in as to the 'to' method
 */

Example usage

_ictt.push(['_includeExternal', [{'from':'globallyAvailableParamName','to':'_setCustomVar'}]]);

Example usage from cookie

_ictt.push(['_includeExternal', [{'fromCookie':'cookieNameContainingValue','to':'_setCustomVar'}]]);

Example usage with global function instead of simple variable

var fromFunction = function() {
    // fetch the value you are after
    var value = someLib.get('value');
    if typeof value[0] !== 'undefined' && value[0].length > 3 {
        // return it so it can be passed into the 'to' method.
        return value[0];
    }
}
_ictt.push(['_includeExternal', [{'from':'fromFunction','to':'_setCustomVar'}]]);

// if you are just pushing a value straight into _setCustomVar without any checks or modifications to the values, then you are better using with a variable

Example with defined 'as' field

_ictt.push(['_includeExternal', [{'from':'globallyAvailableParamName','to':'_setCustomVar','as':'otherFieldNameToSendValueInAs'}]]);

You can also read 'from' a global variable, into a custom function which can be useful if you want to modify the value once it's available, before sending into page tag or custom var method calls.

Method: _disableLand

Disables land detection from running on the subsequently tracked page views.

Equivalent to adding a URL parameter to the current page of ictnoland=1
E.g. http://www.example.com/after-funnel?ictnoland=1

/**
 * _disableLand
 */

// example usage
_ictt.push(['_disableLand']);

Method: _addCallback

Adds a callback that will be called when the main tracking request is completed, and when the page has finished loading.
We will also call it each time we have tried to update numbers in the page (apart from after _allocate method calls, which can have their own callbacks).

Our callbacks are useful as you can guarantee that certain variables (Infinity Visitor ID for example) will be available when they are called.
This let's you write simple code without needing to check if our tracking requests have completed.

You can supply a options object argument with a maxRunCount param if you want to set a maximum number of times it can be called. This is useful if your callable is not idempotent.

If you add a callback after tracking has completed, it will be called immediately.

You can either define the function inline of the method call, or assign it to a variable and pass that in (see examples).

/**
 * _addCallback
 * @param Callable The callback to fire
 * @param Object config (Optional) (Properties described below by object param key)
 * @param Object.maxRunCount maxRunCount Maximum number of times the callback will be called
 */

Example usage

_ictt.push(['_addCallback', function() { console.log('do something here') }]);

Example usage with callback defined as variable

var cb = function() {
    // read the infinity visitor ID
    console.log(_ictt.push(['_get', 'ictvid']));
}
_ictt.push(['_addCallback', cb]);

Example which restricts callback to only be called once

var cb = function() {
    console.log('This message will only be seen once');
}
_ictt.push(['_addCallback', cb, {maxRunCount:1}]);

Method: _customTrigger

Sends a trigger with custom action and properties to be recorded against the current visitor.

/**
 * _customTrigger
 * @param String action The callback to fire
 * @param Object details (Optional) An object containing trigger properties to record with the custom trigger (Commonly used is 't' (for title))
 * @param Callable callback (Optional) A callback to fire after the custom trigger has been sent
 */

Example usage

_ictt.push(['_customTrigger', 'DOWNLOAD', {t:'Brochure'}]);

Example usage with callback

_ictt.push(['_customTrigger', 'DOWNLOAD', {t:'Brochure'}, function() { console.log('callback executed') }]);

Method: _allocate

Performs a new scan of the page to find elements with the defined auto discovery class(es), allocates dynamic numbers to any new found auto discovery numbers, then performs a replacement of any matching elements.

If you are adding elements to your page after page load which were not present when initial allocation occurred, you can call this method whenever a change of content may have occurred on your site, and it will efficiently handle the operations required to find and update new elements.

If you add a callback to an _allocate method call, it will be fired in all cases, even if no new numbers are allocated, and/or no new numbers in the page are replaced. This could for example be because; all unique auto discovery numbers in your page already have numbers allocated (no new number allocation), or all the discovered numbers in your page have already been replaced.

/**
 * _allocate
 * @param Callable callback (Optional) A callback to fire once this allocation and number replacement has finished.
 */

// example usage
_ictt.push(['_allocate']);

// example with callback
_ictt.push(['_allocate', function() { console.log('allocation (if required) and number replacement (if applicable) has finished') }]);

Method: _autoPopulateInput

Populates the targeted input (by ID) with the chosen Infinity JavaScript variable.

Available items to populate with are the same as those available in the _get method docs.

You can call this method at any time, we internally handle queuing the task if the variable is not yet available, or execution immediately if it is.

/**
 * _autoPopulateInput
 * @param Object config (Optional) (Properties described below by object param key)
 * @param Object.id id The ID of the input that you want to populate
 * @param Object.item item The nitem to populate the input with input with
 */

// example usage
// populate input with ID 'my-input-id', with the assigned Infinity visitor ID
_ictt.push(['_autoPopulateInput', {id:'my-input-id', item:'ictvid'}]);

Method: _get

Retrieves one of the variables about the current state/visitor

This method must only be called after tracking has occurred.
It is generally best to wrap your logic in a callback and make use of our _addCallback mechanism to guarantee this.

Available items are;

  • ictvid The Infinity Visitor ID
  • igrp The Infinity Installation (IGRP) ID
  • ictnumbers_0 where 0 is the ID of a DGRP that a number has been allocated against (unless using Auto Discovery)

There are also further variables available when the IGRP has the GeoIP setting configured to include them;

  • ipCity The City mapped to the visitor
  • ipCountryCode The Country Code mapped to the visitor
  • ipRegion The Region mapped to the visitor
/**
 * _get
 * @param String name The name of the value you want to retrieve
 * @return Mixed|Boolean false if value is not available, or the value itself if it is.
 */

Example usage to retrieve the assigned Infinity Visitor ID

_ictt.push(['_get', 'ictvid']);

Example usage to retrieve the number allocated to DGRP 99999

_ictt.push(['_get', 'ictnumbers_99999']);

Method: _setDgrp

Sets configuration to map a DGRP to one or more classes. At number replacement time, all elements that have at least one of these classes, will have the contents replaced with the dynamic allocated number.

/**
 * _setDgrp
 *
 * @param Array (Properties described below by index position
 * @param Array:0 String dgrp The ID of the DGRP you are configuring
 * @param Array:1 Array classes The list of classes that you use on elements that are associated with this DGRP
 */

// example usage
_ictt.push(['_setDgrp',['99999',['InfinityNumber99999']]]);

// example usage with multiple classes
_ictt.push(['_setDgrp',['99999',['InfinityNumber99999', 'tel-number-99999']]]);

Method: _enableOverrideMode

Enables Override DGRP Allocation Mode.

This means that only DGRP's that you have _setDgrp calls for, will have numbers allocated.

This let's you control which DGRPs to allocate numbers for on a case-by-case basis. In many instances, auto discovery is a better solution, you can contact support for more information if you feel this is something you would benefit from.

/**
 * _enableOverrideMode
 */

// example usage
_ictt.push(['_enableOverrideMode']);

Method: _tagExternalLinks

Tags external links with information that allows cross-site tracking without needing third party cookies.

/**
 * _tagExternalLinks
 * @param Array domains An array of domains to restrict tagging to
 */

Example usage

_ictt.push(['_tagExternalLinks', ['example.com']]);

Example usage restricting by full domain with specific protocol

_ictt.push(['_tagExternalLinks', ['https://www.example.com']]);

Method: _tagExternalFormActions

Tags external form actions with information that allows cross-site tracking without needing third party cookies.

/**
 * _tagExternalFormActions
 * @param Array domains An array of domains to restrict tagging to
 */

Example usage

_ictt.push(['_tagExternalFormActions', ['example.com']]);

Example usage restricting by full domain with specific protocol

_ictt.push(['_tagExternalFormActions', ['https://www.example.com']]);

Method: _tagExternalDestinations

Tags external elements with information that allows cross-site tracking without needing third party cookies.

This method is a shortcut helper, equivalent to calling both _tagExternalFormActions and _tagExternalLinks.

/**
 * _tagExternalDestinations
 * @param Array domains An array of domains to restrict tagging to
 */

Example usage

_ictt.push(['_tagExternalDestinations', ['example.com']]);

Example usage restricting by full domain with specific protocol

_ictt.push(['_tagExternalDestinations', ['https://www.example.com']]);

Method: _track

Performs visitor tracking, once complete it also makes certain variables about the current visitor and state available, (such as Visitor ID, GEO params if Geo detection is being used).

If you are not using auto discovery, this also handles number allocation, the same request. If you are using auto discovery, when the track request finishes, it will initiate an allocation request (see _allocate).

/**
 * _track
 */

// example usage
_ictt.push(['_track']);

Method: _enableSPAMode

Enables SPA (Single Page Application) mode.

Calling this method also enables Auto Discovery mode as you must be using Auto Discovery mode to use SPA mode.

/**
 * _enableSPAMode
 */

// example usage
_ictt.push(['_enableSPAMode']);

Method: _resetCallbacks

Removes any previously added callbacks and allows new ones to be called.

This method is generally used if you have enabled SPA Mode

/**
 * _resetCallbacks
 */

// example usage
_ictt.push(['_resetCallbacks']);

Method: _resetIntegrations

Removes any previously added integrations and allows new ones to be run.

You will usually be adding your integrations with the _includeExternal method

This method is generally used if you have enabled SPA Mode

/**
 * _resetIntegrations
 */

// example usage
_ictt.push(['_resetIntegrations']);

Method: _resetCustomVars

Removes any previously added customVars and allows new ones to be added.

This method is generally used if you have enabled SPA Mode

/**
 * _resetCustomVars
 */

// example usage
_ictt.push(['_resetCustomVars']);

Method: _resetSegment

Resets any previously set segment so that subsequent requests will not be placed within it.

This method is generally used if you have enabled SPA Mode

/**
 * _resetSegment
 */

// example usage
_ictt.push(['_resetSegment']);

Method: _dropScriptTag

Creates a <script> element, with async enabled and adds to the DOM.
Once the target script has been loaded, the script element is removed (if possible)
When providing the URL argument, you must not include the protocol, this is added based on the protocol of the site running the script.

This method is mostly used internally for integration snippets

/**
 * _dropScriptTag
 *
 * @param String uri The path to the script you want to load (not including protocol)
 * @param Callable callback (Optional) A callback to fire once the script has been loaded
 */

Example usage

_ictt.push(['_dropScriptTag', 'example.com/path/to/jsfile.js']);

Example usage with callback

_ictt.push(['_dropScriptTag', 'example.com/path/to/jsfile.js', function() { console.log('Script loaded'); }]);

Method: _storeItem

Adds an item, to be stored for later retrieval.
The value is stored in a first party cookie, and prefixed with ictf_

This method should not be used for temporary values, or any value that does not directly relate to internal Infinity Tracking systems.

/**
 * _storeItem
 *
 * @param String key The name of the item being stored
 * @param String value The value of the item being stored
 */

// example usage
_ictt.push(['_storeItem', 'key', 'value']);

Method: _retrieveItem

Retrieves an item from the infinity cookie set.
The key for retrieval is prefixed with ictf_ before lookup.

This method should not be used for temporary values, or any value that does not directly relate to internal Infinity Tracking systems.

/**
 * _storeItem
 *
 * @param String key The name of the item being retrieved
 */

// example usage
_ictt.push(['_retrieveItem', 'key']);

HTML Attribute: discovery-number

Normally, the contents of the element that has the defined auto discovery class will be the phone number.

<span class="InfinityNumber">0123 4567 891</span>

But in some cases, the contents will not contain the phone number, in which case you can add an attribute to the element to tell us what number to use.

<span class="InfinityNumber" data-ict-discovery-number="0123 4567 891">Something else here</span>

Which after allocation will become (where 0123 4567 999 is the allocated number);

<span class="InfinityNumber" data-ict-discovery-number="0123 4567 891">0123 4567 999</span>

You can further tweak the behaviour of replacement using the silent-replacements attribute.

By combining the two attributes, you can have an element that does not contain the auto discovery number (it may contain a click to call icon), and just have the href of the A element be updated, not the contents

HTML Attribute: silent-replacements

If you don't want to update the contents of the target element, but just the attributes (href of an A element), then use silent replacements.

<a class="InfinityNumber" href="tel:01234567891" data-ict-silent-replacements="true">
    0123 4567 891
</a>

Only the href will be updated here. This attribute is most useful when used in conjunction with the auto-discovery attribute.

HTML Attribute: auto-discovery with silent-replacements

Normally, the contents of the element that has the defined auto discovery class will be replaced with the allocated phone number. However if the contents are not just a phone number, but maybe a click to call icon, then you would not want to replace the contents.

By using discovery-number and silent-replacements together, you can achieve this.

<a class="InfinityNumber" href="tel:01234567891" data-ict-discovery-number="0123 4567 891" data-ict-silent-replacements="true">
    <i class="fa fa-icon-phone"></i>
</a>

Which after allocation will become (where 0123 4567 999 is the allocated number);

<a class="InfinityNumber" href="tel:01234567999" data-ict-discovery-number="0123 4567 891" data-ict-silent-replacements="true">
    <i class="fa fa-icon-phone"></i>
</a>

Notice that the href has been updated to the allocated number, but the contents remain unchanged.

You can handle custom requirements of markup by combining these two attributes.

Before

<a class="InfinityNumber" href="tel:01234567891" data-ict-discovery-number="0123 4567 891" data-ict-silent-replacements="true">
    <i class="fa fa-icon-phone"></i> <span class="InfinityNumber">0123 4567 891</span>
</a>

After allocation

<a class="InfinityNumber" href="tel:01234567999" data-ict-discovery-number="0123 4567 891" data-ict-silent-replacements="true">
    <i class="fa fa-icon-phone"></i> <span class="InfinityNumber">0123 4567 999</span>
</a>

Notice that the href of the A has been updated, and the inner contents of the span has been updated, but the icon is left in place. Two elements were targeted and updated in different ways.

Please login to rate this article
  1. Getting Started
  2. Enhancing your Installation
  3. Frequently asked questions
  4. Call Management
  5. Number Management
  6. Infinity API