ATS.js Functions and Events

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.

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

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.

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

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 .

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>"
   ]
})

If you have enabled the Data Layer Detection for a conversions API event, call this function once event data has been stored in data layer to detect the event's configured properties. This function should be called on every page where ATS.js needs to detect the event.

To learn more about configuring conversions API events, see "Implement Meta CAPI", "Implement Pinterest CAPI", or "Implement Snapchat CAPI".

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());
    });

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();
    });

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>"
]
     });
    });

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

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);
});

This event will be fired when a conversion API module loads. See "CAPI Programs" to learn more.

Example:

// ATS conversion module is ready to be used.
window.addEventListener("conversionModuleReady", () => {
    ats.sendSnapchatEvents(['name_of_event']);
});

This event will be fired when the eCST (Enhanced Client-Side Tag) module is loaded. If you are running LiveRamp eCST, we recommend subscribing to the event as early as possible before any other scripts or libraries are loaded by placing the code higher up on your page. You can then trigger any eCST event to collect user activities after ecstModuleReady is fired.

To learn more, see "Enhanced Client-Side Tag for ATS for Web (Beta)".

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);
});