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: _setHref

Sets the URL to use for tracking and number allocation requests. If this is not set, these requests use the actual URL of the page.

/**
 * _setHref
 *
 * @param String href The href to use, which replaces the 'actual' href
 */

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

Method: _setTitle

Sets the page title to use for tracking and number allocation requests. If this is not set, these requests use the actual title of the page.

/**
 * _setTitle
 *
 * @param String title The page title to use, which replaces the 'actual' page title
 */

// example usage
_ictt.push(['_setTitle', 'Example Page']);

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 action name
 * @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: _addToDestMap

Adds configuration to allocate a phone number for an auto discovery number or DGRP.

The destination map is populated automatically in auto discovery mode. It is rare that this method would need to be used as part of a standard installation.
This method is useful if you need to also allocate numbers which are not present on the page. The allocated number mapping can be retrieved after calls to _allocate using the _getAllocatedNumber method.

/**
 * _addToDestMap 
 * @param Object config (Properties described below by object param key)
 * @Param Object.type String               The type of entry (dgrp|number)
 * @Param Object.identifier String         The identifier for the entry (phone number, or DGRP ID)
 * @Param Object.classes (optional) Array  The classes that we use to find the item in the page to replace
 */

Example usage

_ictt.push(['_addToDestMap', { type: 'number',  identifier: '01234567891' }]);

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: _getAllocatedNumbers

Returns a mapping of the allocated numbers. This will only return data when the number allocation is completed, otherwise returns an empty object.

/**
 * _getAllocatedNumbers
 * @return Object The phone number mapping
 */

Example usage

_ictt.push(['_getAllocatedNumbers']);

The Object is keyed on auto discovery number when using this mode, or DGRP ID if you're using the older, _setDgrp approach.

Example response when using Auto Discovery

{ 01234567891: "01234 987 654" }

Example response when using 'Classic'

{ 123: "01234 987 654" }

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: _tagExternalUrl

Appends infinity parameters to the URL that is passed in to allow cross-site tracking without needing third party cookies.

This is useful when your site needs to send the user to another URL but that URL is not exposed to the Infinity's tracking script for auto tagging.

/**
* _tagExternalUrl
* @param String url URL for the external resources that should include Infinity params
* @return String URL that is passed in as the argument with infinity params appended
*/

Example usage

const redirectURL = _ictt.push(['_tagExternalUrl', 'http://myexternaldomain.com?param=1&param=2']);

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: _addNumberElements

Adds user-provided DOM elements to be included in number replacement.

Calling this method multiple times will add to any previously added elements, this allows you to easily add multiple elements with different combinations of selectors and options.

You must call _allocate to perform number replacement on elements added by this method, unless the elements are added before the call to _track.

This method is particularly useful if you are not able to add the InfinityNumber class (and don't have a suitable existing class) or data attributes to your elements.

/**
 * _addNumberElements 
 * @param Array elements
 * @param Object config (Properties described below by object param key)
 * @Param Object.silentReplacements Boolean   Whether to only replace attributes of the elements (default false)
 * @Param Object.discoveryNumber    String    The number to use for replacement, if not provided will use the text content of the element
 */

Example usage - native JavaScript

Be sure to check your required browser support if using querySelectorAll in your custom selector code.

var elements = Array.prototype.slice.call(document.querySelectorAll('.cannot_add_class_here'));
_ictt.push(['_addNumberElements', elements]);

Example usage - jQuery

var elements = $('.cannot_add_class_here').get();
_ictt.push(['_addNumberElements', elements]);

Example usage - auto-discovery with silent-replacements

var elements = Array.prototype.slice.call(document.querySelectorAll('a[href="tel:01234567891"]'));
_ictt.push(['_addNumberElements', elements, {silentReplacements: true, discoveryNumber: '01234567891'}]);

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: _resetNumberElements

Resets the list of user-provided DOM elements to be included in number replacement.

This method is useful for a Single Page Application to remove any elements previously added by _addNumberElements which are no longer present.

Example usage

_ictt.push(['_resetNumberElements']);

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
 * @param Number|Boolean lifetime Optional. Specifies the length of time item needs to be stored for
 *                       If not provided (undefined) then item is stored for 10 years (default)
 *                       If a number is provided then the item is stored for the number of milliseconds specified by the number
 *                       If set to false then item is only stored for the length of the session
 */

// example usage
_ictt.push(['_storeItem', 'key', 'value']); // key stored for 10 years
_ictt.push(['_storeItem', 'key', 'value',  86400000]); // key stored for one day i.e. 86400000ms = 1 day
_ictt.push(['_storeItem', 'key', 'value',  false]); // key stored for the length of the session

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