Getting started

Installation

To use our JavaScript API, insert the following code between script tags, preferably within the head tags. Ensure to replace the placeholder YOUR_API_KEY with the API key assigned to you. The pre-configured snippet can be found on your Allo-Media account, under the 'summary' tab of each campaign.

<script>
(function(k,e,t,c,h,u,p){k['AlloAnalyticsObject']=h;k[h]=k[h]||function(){
        (k[h].q=k[h].q||[]).push(arguments)},k[h].l=1*new Date();u=e.createElement(t),
    p=e.getElementsByTagName(t)[0];u.async=1;u.src=c;p.parentNode.insertBefore(u,p)
})(window,document,'script','https://hermes.allo-media.net/static/js/amloader.js','am');

// Configure options here
const options = {
  // Default values
  cohortMode: false,
  cookieVisitorExpires: 31536000, // 1 year
  fallbackToCookies: true,
  ignoreAttributes: ["src", "height", "width"],
  ignoreSelectors: ["style", "link", "noscript", "canvas", "svg"],
  localStorage: false,
  multiPages: true,
  replaceSelectors: [], // Will replace in all selectors except the ones in `ignoreSelectors`
}

am('create', 'YOUR_API_KEY', options);

// You can launch the replacement whenever you want,
// as long as the am object is initialized.
// This is useful if your phone number is not in
// the DOM on page load but added later.
am('start');
</script>

create options

When using the create method, you can specify various options as described below.

cohortMode

Set if you activate the cohort mode, this will enable you to display a tracking phone number without the use of cookies. The tracking phone number will be the same for all the visitors of a given campaign.

Example:

am('create', 'AM-votreapikey', {
    cohortMode: true
});

cookieVisitorExpires

This option enables you to set the maximum amount of time that cookies will be retained.

Example:

am('create', 'AM-votreapikey', {
  cookieVisitorExpires: 15780000 // 6 months in seconds
});

fallbackToCookies

If the localStorage option is set to true, you can choose to use cookies as a fallback option in case 'localStorage' is not supported by the browser.

Example:

am('create', 'AM-votreapikey', {
    fallbackToCookies: true
});

ignoreAttributes

It is possible to prevent the script from replacing phone numbers present in some HTML tag attributes.

Example:

am('create', 'AM-votreapikey', {
    ignoreAttributes: ['data-phonenumber']
});

ignoreSelectors

It is possible to prevent the script from replacing phone numbers according to certain selectors.

This option will be ignored if the replaceSelectors option is used as well.

Example:

am('create', 'AM-votreapikey', {
    ignoreSelectors: ['#header > a']
});

localStorage

If you wish you can use localStorage as an alternative to cookies.

Example:

am('create', 'AM-votreapikey', {
    localStorage: true
});

multipages

This option allows, as much as possible, to keep the same tracking number from page to page. Setting it to false disables cookies.

Example:

am('create', 'AM-votreapikey', {
    multipages: false
});

replaceSelectors

It is possible to replace telephone numbers present only in selected selectors.

Example:

am('create', 'AM-votreapikey', {
    replaceSelectors: ['span']
});

set options

callback: Be notified when the phone numbers have been replaced

You can define a callback function that will be executed after the replacement of the phone number(s).

Exemple :

/**
  * @param {Object|undefined} [payload]           Payload description object
  * @param {string}           payload.campaignId  The campaign id used with `am("start", campaignId)`
*/
function myCallback(payload) {
    // Do something after the phone number has been replaced
    // `payload` is an object with only one property for now:
    // - `campaignId` the campaign id of the callback if set as parameter
    // to the `start` function (eg `am("start", "am1234")`).
    // See "Replace phone numbers from multiple campaigns"
}

am('set', 'callback', myCallback);

onError: Be notified when there is an error

You can define a callback function that will be executed if there is an error while replacing the phone number(s).

Exemple :

/**
  * @param {Object} [error]     Error description object
  * @param {string} error.code  The error code
  * @param {string} error.msg   The error message
*/
function myErrorFunction(error) {
    // Do something in case there is an error.
}

am('set', 'onError', myErrorFunction);

trackingIds: Provide additional data

You can send additional data, usually a customer-controlled identifier, to each page viewed. This data should be sent in the following manner:

am('set', 'trackingIds', {superTracker5: 'tata'})

Be careful, the set parameter overwrites the data previously sent. To add data to the existing ones, it is generally advisable to proceed as follows:

am('set', 'trackingIds', Object.assign(am('get', 'trackingIds'), {
    superTracker5: 'tata'
}));

Collision with the am object

The Allo-Media library creates an object named am in the window object by default. If this conflicts with an object with the same name in the global scope, you can change the name of this object.

Simply modify the am parameter passed as a parameter to the main snippet function, and remember to update the calls to this object.

Example :

// Let's change it for "foo"

(function(k,e,t,c,h,u,p){k['AlloAnalyticsObject']=h;k[h]=k[h]||function(){
        (k[h].q=k[h].q||[]).push(arguments)},k[h].l=1*new Date();u=e.createElement(t),
    p=e.getElementsByTagName(t)[0];u.async=1;u.src=c;p.parentNode.insertBefore(u,p)
})(window,document,'script','https://hermes.allo-media.net/static/js/amloader.js','foo');

// Don't forget to change the calls
foo('create', 'YOUR_API_KEY');
foo('start');

Note These data will be ignored if you're using the cohort mode.

Replace phone numbers from multiple campaigns

If there are multiple phone numbers on the same page, and each of these numbers is part of a different campaign, the script's default operation will only replace the first number it finds.

However, you can execute the am('start') function multiple times, specifying the campaign identifier as a parameter each time, as shown in the following example:

am('start', 'am7658');
// then
am('start', 'am9356');