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.
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]);
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}]);
Enables auto discovery mode
/**
* _enableAutoDiscovery
*/
// example usage
_ictt.push(['_enableAutoDiscovery']);
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']]);
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']);
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']]);
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']]);
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]);
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']);
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']);
Disables any further number replacement.
/**
* _disableNumberReplacement
*/
// example usage
_ictt.push(['_disableNumberReplacement']);
Enables further number replacement.
/**
* _enableNumberReplacement
*/
// example usage
_ictt.push(['_enableNumberReplacement']);
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']);
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']);
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']);
Sets the host name to use for manual 'page' triggers, which are not common in standard installations. If this is not set, these requests use the actual host name of the page.
/**
* _setHost
*
* @param String host The host to use, which replaces the 'actual' host
*/
// example usage
_ictt.push(['_setHost', 'www.example.com']);
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
*/
_ictt.push(['_includeExternal', [{'from':'globallyAvailableParamName','to':'_setCustomVar'}]]);
_ictt.push(['_includeExternal', [{'fromCookie':'cookieNameContainingValue','to':'_setCustomVar'}]]);
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
_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.
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']);
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 the following params:
maxRunCount if you want to set a maximum number of times it can be called. This is useful if your callable is not idempotent.eventName if you want to ensure the callback is triggered after number replacement has completed, set this to afterNumberReplace.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
* @param Object.eventName The event to trigger the callback on, currently only accepts `default` or `afterNumberReplace`
*/
_ictt.push(['_addCallback', function() { console.log('do something here') }]);
var cb = function() {
// read the infinity visitor ID
console.log(_ictt.push(['_get', 'ictvid']));
}
_ictt.push(['_addCallback', cb]);
var cb = function() {
console.log('This message will only be seen once');
}
_ictt.push(['_addCallback', cb, {maxRunCount:1}]);
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
*/
_ictt.push(['_customTrigger', 'DOWNLOAD', {t:'Brochure'}]);
_ictt.push(['_customTrigger', 'DOWNLOAD', {t:'Brochure'}, function() { console.log('callback executed') }]);
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_allocateusing the_getAllocatedNumbersmethod.
/**
* _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
*/
_ictt.push(['_addToDestMap', { type: 'number', identifier: '01234567891' }]);
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
_allocatemethod 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') }]);
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
*/
_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.
{ 01234567891: "01234 987 654" }
{ 123: "01234 987 654" }
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'}]);
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;
There are also further variables available when the IGRP has the GeoIP setting configured to include them;
/**
* _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.
*/
_ictt.push(['_get', 'ictvid']);
_ictt.push(['_get', 'ictnumbers_99999']);
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']]]);
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']);
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
*/
_ictt.push(['_tagExternalLinks', ['example.com']]);
_ictt.push(['_tagExternalLinks', ['https://www.example.com']]);
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
*/
_ictt.push(['_tagExternalFormActions', ['example.com']]);
_ictt.push(['_tagExternalFormActions', ['https://www.example.com']]);
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
_tagExternalFormActionsand_tagExternalLinks.
/**
* _tagExternalDestinations
* @param Array domains An array of domains to restrict tagging to
*/
_ictt.push(['_tagExternalDestinations', ['example.com']]);
_ictt.push(['_tagExternalDestinations', ['https://www.example.com']]);
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
*/
const redirectURL = _ictt.push(['_tagExternalUrl', 'http://myexternaldomain.com?param=1¶m=2']);
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']);
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']);
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
InfinityNumberclass (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
*/
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]);
var elements = $('.cannot_add_class_here').get();
_ictt.push(['_addNumberElements', elements]);
var elements = Array.prototype.slice.call(document.querySelectorAll('a[href="tel:01234567891"]'));
_ictt.push(['_addNumberElements', elements, {silentReplacements: true, discoveryNumber: '01234567891'}]);
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']);
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']);
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']);
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']);
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
_addNumberElementswhich are no longer present.
_ictt.push(['_resetNumberElements']);
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
*/
_ictt.push(['_dropScriptTag', 'example.com/path/to/jsfile.js']);
_ictt.push(['_dropScriptTag', 'example.com/path/to/jsfile.js', function() { console.log('Script loaded'); }]);
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
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']);
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
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.
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.
Getting Started
Enhancing your Installation
Frequently asked questions
Call Management
Number Management
Infinity API