Getting started

Installation

To use our JavaScript API, you need to place the following code between script tags, preferably in between head tags. Remember to change the value YOUR_API_KEY by the key API you have been assigned. You can find this pre-configured snippet on your Allo-Media account, in the "summary" tab of each of your campaigns.

<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 calling the create method, it is possible to specify a series of options, detailed below.

cohortMode

Set if you activate the cohort mode, which allows you to display a tracking phone number without 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 allows you to customize the maximum cookie retention time.

Example:

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

fallbackToCookies

If the localStorage option is set to true, it is possible to specify if you still want to use cookies if localStorage is not available on the browser used.

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 by default an object named am in the window object. You can change the name of this object if it conflicts with an object with the same name in the global scope.

Simply change the am parameter passed as a parameter to the main snippet function, and remember to modify 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 you have several phone numbers on the same page, and each of these numbers is part of a different campaign, the classic operation of the script will allow you to replace only the first number found.

A solution exists. You have to execute the am('start') function several times, specifying in parameter the identifier of the campaign, as in the following example :

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