Skip to main content

ATS.js Functions and Events

Learn about the ATS.js functions you can use for specific tasks and the events that ATS.js fires.

ATS.js Functions

ats.retrieveEnvelope(callback);

Fetch the envelope from configured storage; the callback function is optional. If the function is called without a callback, a promise will be returned. If the function is called with a callback, an envelope value will be returned.

ats.outputCurrentConfiguration();

This will return the current configuration object. The callback function is optional. In both ways it will return the current config object.

ats.triggerDetection();

This function will (re)scan DOM (Document Object Model) elements with the CSS selectors specified in your configuration. You can call this function if the ATS.js library has been started.

ats.invalidateEnvelope();

This function will remove the current envelope (including PAIR, Facebook, and Pinterest) that is stored in local storage/cookie.

ats.setAdditionalData(data);

If direct mode is enabled, this function can be called with object and properties id (identifier) and type of identifier. Use this function together with the event listener envelopeModuleReady .

Warning

Make sure the event listener envelopeModuleReady is loaded before ats.setAdditionalData to avoid the risk of the ATS library being called before the envelope module is fully loaded.

Type parameters are email, phoneNumber, emailHashes, and phoneNumberHashes.

You can also pass custom IDs if you do not work with any of the valid type parameters. See "Custom ID Support" to learn more.

,emailHashes must be passed in an array, even when only passing a single email hash. Example of function :

ats.setAdditionalData({
   'type': 'emailHashes',
   'id': [
       "<EMAIL_HASH_SHA1>",
       "<EMAIL_HASH_SHA256>",
       "<EMAIL_HASH_MD5>"
   ]
})

Events

lrEnvelopePresent

This event will be fired when a new or existing identity envelope is stored in configured storage.

Example:

    // An ATS envelope has been located!
    window.addEventListener("lrEnvelopePresent", async () => {
        console.log("lrEnvelopePresent: ", await atsenvelopemodule.retrieveEnvelope());
    });

detectionModuleReady

This event will be fired when the detection module (for detecting the identifier on page) is fully loaded.

Example:

    // ATS detection module is ready to be used.
    window.addEventListener("detectionModuleReady", () => {
        atsdetectionmodule.outputCurrentConfiguration();
    });

envelopeModuleReady

This event will be fired when the envelope module (for creating an identity envelope and storing it in configured storage) is fully loaded. Make sure to place the code higher up in the body of the page to ensure the event is registered before ATS.js is loaded.

Example with a raw email:

// ATS envelope module is ready to be used.
    window.addEventListener("envelopeModuleReady", () => {
        // For example, you can directly feed it emails, like so:
        atsenvelopemodule.setAdditionalData({
            'type': 'email',
            'id': "test@liveramp.com"
        });
    });

Example with email hashes:

window.addEventListener("envelopeModuleReady", function(){
        atsenvelopemodule.setAdditionalData({
            'type': 'emailHashes',
            'id': ["<EMAIL_HASH_SHA1>",
    "<EMAIL_HASH_SHA256>",
    "<EMAIL_HASH_MD5>"
]
     });
    });

dropMatchPixelModuleReady

This event will be fired when the Match Pixel Module (for dropping Match Pixel on the page) is fully loaded.

fbEnvelopePresent

This event will be fired when an envelope scoped for Facebook is stored in the configured storage. See Facebook CAPI to learn more about this feature.

Example:

window.addEventListener("fbEnvelopePresent", async () => {
   const fbEnvelope = await ats.retrieveEnvelope(undefined, '_lr_fb_env');
   console.log("fbEnvelopePresent: ", JSON.parse(fbEnvelope).envelope);
});

pairIdEnvelopePresent

This event will be fired when a PAIR ID is stored in the configured storage. See Google PAIR and ATS to learn more about this feature.

window.addEventListener("pairIdEnvelopePresent", async () => {
   const pairIdEnvelope = await ats.retrieveEnvelope(undefined, '_lr_pairId');
   console.log("pairIdEnvelopePresent: ", JSON.parse(pairIdEnvelope).envelope);
});