ATS

The Quickstart Guide

Suggest Edits

In certain situations, you may prefer to call the ATS API directly, versus including and configuring the ats.js code. Direct interaction will let you cut down the weight of the page and potentially make fewer client-side network requests, but does add to the implementation complexity.

Follow the steps below to learn how you can implement ATS with API correctly.

1. Call the Envelope API

  1. Provide a valid TCF consent string
    When calling the Envelope API for users in the EU/EEA, you will need to supply a valid TCF consent string with LiveRamp listed as a vendor (ID 97) for all it’s purposes in order to obtain an envelope. Consent can be detected by ATS through a standard CMP JS API call.

  2. Hash identifiers properly
    Ensure that you are properly hashing identifiers and indicating the correct identifier type when you call the Envelope API.
    For phone number identifiers: In order to obtain an envelope for a user with a phone number identifier, only SHA1 hashes should be passed. Note that hashed phone numbers are currently only supported for US ten-digit phone numbers.
    For email identifiers: In order to obtain the best possible envelope for a user with an email identifier, we recommend calling the API with all three email hash types to get the best match rate; SHA256 (Use this for EU if you are only able to hash one), SHA1 (Use this for US if you are only able to hash one), and MD5.

  3. Call the Envelope API
    Make an API call via the following path:
    https://api.rlcdn.com/api/identity/v2/envelope?pid=[placement id]&it=[identifier type]&iv=[hashed identifier]&ct=[consent type]&cv=[consent string]

  • pid: Your partner/placement ID (API key).
  • it: The identifier type of the call. "4" corresponds to hashed emails and "11" represents phone number hashes.
  • iv: The hashed version of the raw email.
  • ct: The type of consent passed to the API. "1" represents a TCF v1.1 compatible consent string and "4" represents a TCFv2 compatible string. Consent is required for processing in the EU.
  • cv: The relevant consent string value.
  • Origin header: Include a whitelisted origin on your requests if you're calling the ATS API directly.
    Learn more about the envelope API here.

2. Return Stored Envelopes

When you successfully retrieve an envelope from the Envelope API, we highly recommend you to store the envelope value in a first-party cookie called _lr_env. To retrieve envelopes, call the function window.ats.retrieveEnvelope().

If you are working with prebid.js and our Prebid embedded identityLink module, you will need to call the function with a callback or expecting a promise.
If you integrate directly with the API, you will need to expose this function to look up your stored envelopes from the DOM. This function should return a JSON object containing {"envelope":"envelope_value"}.

For example, assuming your envelope is stored in the first-party cookie _lr_env:

function mockEnvelope(func) {
  let env = undefined;
  try {
    env = JSON.stringify({
      "envelope": document.cookie.match('(^|;) *_lr_env=([^;]*)')[2]
    });
  } catch (e) {
    console.log(e);
  } finally {
    func(env)
  }
}

window['ats'] = {};
window.ats.retrieveEnvelope = mockEnvelope;

3. Apply rules and conditions for Refresh Envelope API

By default, envelopes are generated with a 15 day TTL. To avoid passing expired envelopes that cannot be decrypted by the SideCar (an API that is implemented on the SSP side to read envelopes) or other envelope APIs, it is advised to store a timestamp next to your envelope. With timestamps in place you can more easily call the Refresh Envelope API to remove and refresh envelopes before they expire.

How to call the Refresh Envelope API
The refreshing of envelopes is an important factor to keep the match rate as high as possible for your users. Existing envelopes can be exchanged for fresh envelopes by calling https://api.rlcdn.com/api/identity/envelope/refresh?pid=<PID>&it=19&iv=<envelope_value>. This will reset the envelope expiration to the maximum allowed value.

When to call the Refresh Envelope API
We highly recommend calling the Refresh Envelope API on the first subsequent page load after a user authenticates. After that, do it every 30 minutes when a user enters a new page or refreshes the current page.

Updated 6 months ago