Store the Identity Envelope With a Timestamp

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

Encode The Entire Envelope API Response

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

{"envelope":"At27EmplJfDNtsjSrBrThDsCQEdBNgdZ1bJG3arMwRtdhK220ob-ouZuGPAWjLSYU3lLAZAs0ulsvbx2K42UzwSGINKI_asxDO_7"}

Before storing the response, you must Base64 encode the entire JSON object (not just the value of the envelope). After it is encoded into Base64, the result will look like:

eyJlbnZlbG9wZSI6IkF0MjdFbXBsSmZETnRzalNyQnJUaERzQ1FFZEJOZ2RaMWJKRzNhck13UnRkaEsyMjBvYi1vdVp1R1BBV2pMU1lVM2xMQVpBczB1bHN2YngySzQyVXp3U0dJTktJX2FzeERPXzcifQ==

The Base64 encoded envelope value can then be stored in a first-party cookie or local storage called _lr_env.

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 call the Refresh Envelope API to remove and refresh envelopes before they expire.

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.

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 */