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.
Label | Type | Comment |
---|---|---|
cohortMode | boolean | Default value: false . |
Example:
am('create', 'AM-votreapikey', {
cohortMode: true
});
cookieVisitorExpires
This option allows you to customize the maximum cookie retention time.
Label | Type | Comment |
---|---|---|
cookieVisitorExpires | int | Cookies' expiration delay, in seconds. Default value: 1 year. |
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.
Label | Type | Comment |
---|---|---|
fallbackToCookies | boolean | If false, browsers that do not support localStorage will not replace phone numbers. Default value: true . |
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.
Label | Type | Comment |
---|---|---|
ignoreAttributes | string[] | A table containing the list of attributes you wish to ignore. Default value: [] . |
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.
Label | Type | Comment |
---|---|---|
ignoreSelectors | string[] | An array containing the list of selectors. Default value: ["#comment", "svg"] . |
Example:
am('create', 'AM-votreapikey', {
ignoreSelectors: ['#header > a']
});
localStorage
If you wish you can use localStorage as an alternative to cookies.
Label | Type | Comment |
---|---|---|
localStorage | boolean | If true, enable the use of localStorage instead of cookies. Default value: false . |
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.
Label | Type | Comment |
---|---|---|
multipages | boolean | Default value: true . |
Example:
am('create', 'AM-votreapikey', {
multipages: false
});
replaceSelectors
It is possible to replace telephone numbers present only in selected selectors.
Label | Type | Comment |
---|---|---|
replaceSelectors | string[] | A table containing the list of selectors in which to search for phone numbers. Default value: [] . |
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');