ATS
Guides

5. Store the Identity Envelope With a Timestamp

Suggest Edits

When you successfully retrieve an Identity Envelope from the Envelope API , store the envelope in a first-party cookie or local storage based on the type of identifiers. Before doing so, you must encode the entire Envelope API response with Base64.

Encode The Entire Envelope API Response

When you successfully retrieve an Identity Envelope from the Envelope API, the Envelope API response will look like:

{"envelopes":[{"type":19,"source":"envelopeLiveramp","value":"Aqs3wtOuqIRic78_s4Nqilcr0MGn0cDvKzvpEhSGVjwV8Ci0Jy73B1bkfpv03GwK2uyKbME4kSAtVFn_5sCLWstyHTnEWYurbjLXLpgtf9MfLP1AeDTUQ_0ESnD3x1pr6gYfBOOUH8BPhbfscxdaGUA-_sacPab3nzc05koLhbqrJIQC7JBraEbpOJPDAHp9f44DXIXm","err":null},{"type":25,"source":"pairIds","value":"WyJBeVhiNUF0dmsvVS8xQ1d2ejJuRVk5aFl4T1g3TVFPUTJVQk1BMFdiV1ZFbSJd","err":null}]}

The response will contain at least one LiveRamp envelope (within "envelopeLiveramp" object) and possibly other types of online identifiers such as PAIR ID as shown in the above example. Before storing the LiveRamp envelope response, you must modify the response so it contains an envelope object.

The result should look like this:

{"envelope":"Aqs3wtOuqIRic78_s4Nqilcr0MGn0cDvKzvpEhSGVjwV8Ci0Jy73B1bkfpv03GwK2uyKbME4kSAtVFn_5sCLWstyHTnEWYurbjLXLpgtf9MfLP1AeDTUQ_0ESnD3x1pr6gYfBOOUH8BPhbfscxdaGUA-_sacPab3nzc05koLhbqrJIQC7JBraEbpOJPDAHp9f44DXIXm"}

As a final step, you need to Base64 encode the entire JSON object as shown above (not just the value of the envelope).

After it is encoded into Base64, the result will look like:

eyJlbnZlbG9wZSI6IkFxczN3dE91cUlSaWM3OF9zNE5xaWxjcjBNR24wY0R2S3p2cEVoU0dWandWOENpMEp5NzNCMWJrZnB2MDNHd0sydXlLYk1FNGtTQXRWRm5fNXNDTFdzdHlIVG5FV1l1cmJqTFhMcGd0ZjlNZkxQMUFlRFRVUV8wRVNuRDN4MXByNmdZZkJPT1VIOEJQaGJmc2N4ZGFHVUEtX3NhY1BhYjNuemMwNWtvTGhicXJKSVFDN0pCcmFFYnBPSlBEQUhwOWY0NERYSVhtIn0=

The Base64 encoded envelope value can then be stored in a first-party cookie or local storage. Different cookie and storage keys are used depending on the type of envelope/identifiers you receive. _lr_env.

Storing the Envelope

You must use the following keys based on the type of identifiers (or segments in the case of ATS Direct) you want to store. If you are working with CAPI products (with the exception of Meta CAPI), you only need to store the identity envelope.

Storing the Envelope in a First-Party Cookie

function setCookieForRampIDEnvelope(envelope) {   
   document.cookie = '_lr_env=' + encodeURIComponent(envelope);
}

Storing the Envelope in Local Storage

function setLocalStorageForRampIDEnvelope(envelope) {   
   localStorage.setItem('_lr_env' , envelope);
}

Envelope Expiration Times

To be GDPR and CCPA compliant, envelopes are generated with a 15-day TTL ("Time to Live" / expiration time) for California (U.S.) and a 30-day TTL for all other countries and regions.

To avoid passing expired envelopes that cannot be decrypted by the SideCar (an API that is implemented on the SSP side to read and decrypt envelopes) or other envelope APIs, we recommend you to store a timestamp next to your envelope. With timestamps in place, you can more easily determine if the expiration time has passed and refresh the envelope if needed.

Storing the Envelope TTL

We’ve provided an example below for setting a timestamp for first-party cookies and for local storage. Based on the users geo location you will need to set the correct expiration time. It is important to note that every time you refresh the envelope you will also need to update or set a new expiration time.

In the example below, we use the first party cookie _lr_env_exp and the local storage key name _lr_env_exp:

function calculateEnvelopeTTL(countryCode, regionCode) {
  let expirationTime = 2592000000;
  if (countryCode === 'US') {
    if (regionCode === 'CA') {
      expirationTime = 1296000000;
    }
  }
  expirationTime += +new Date();
  return expirationTime;
}

// Example: set a cookie to track envelope expiration in 15 days
document.cookie = '_lr_env_exp=' + calculateEnvelopeTTL('US', 'CA');

// Example: set a cookie to track envelope expiration in 30 days
document.cookie = '_lr_env_exp=' + calculateEnvelopeTTL();  

// Example: set localStorage to track envelope expiration for 15 days
localStorage.setItem('_lr_env_exp' , calculateEnvelopeTTL('US', 'CA');

// Example: set localStorage to track envelope expiration for 30 days
localStorage.setItem('_lr_env_exp' , calculateEnvelopeTTL());

You can then read out the appropriate timestamp like so for cookies:

// Example helper function to get cookie by name
function getCookieValue(cookieName) {
   cookieName += "=";
   var tCookieArr = document.cookie.split(';');
    for (var i = 0; i < tCookieArr.length; i++) {
     var tCookie = tCookieArr[i].trim();
 
     if (tCookie.indexOf(cookieName) === 0) {
       var cookieVal = tCookie.substring(cookieName.length, tCookie.length)
       return decodeURIComponent(cookieVal);
     }
   }
    return "";
}
 
getCookieValue("_lr_env_exp");
/* Then, call the Envelope Refresh API as required */

And for local storage:

localStorage.getItem("_lr_env_exp");
/* Then, call the Envelope Refresh API as required */

Updated 2 months ago

What’s Next