ATS Direct

ATS Direct enables direct media buys on authenticated inventory between publishers and marketers. It provides means of facilitating safe transfer of segment data, enabling marketers to activate their data in direct deals with publishers using ATS.

Requirements

To be able to call the ATS Direct API, you must have the following:

1. An ATS configuration linked to an approved placement in Console. To find your ATS placements, log in to Console, and select Placements in the navigation menu. See Create an ATS Placement to learn more.
2. ATS Direct added to your subscription in Console. Talk to a LiveRamp representative to get this set up for you.

1. Create an ATS Direct Configuration

In Console, publishers are required to create an ATS Direct configuration which is represented as a destination under “ATS Direct” in LiveRamp Connect. Marketers can then select the publisher destination to transfer their segments as RampId’s.

📘

You can only have one ATS Direct configuration per region. The New button on the Deals page will be disabled if you already have an ATS Direct configuration for EU and US.

1. Log in to Console.
2. Select the ATS > Deals.
3. The ATS Direct Configurations table is displayed. Click New.
4. Enter a configuration name.
5. Select the desired placement to tie the configuration to.
6. Select the region for the ATS Direct configuration.
7. Click Create.

2. Approve Deal in Console

When a marketer has transferred their segment to ATS Direct, you can approve or reject them as a ‘deal’ in Console. All transferred deals will be in Pending status by default. This means the segments will not be activated yet until it has been approved. You can also cancel a deal to stop segments from being distributed.

To learn how to manage deals in Console, see Working with Deals.

3. Retrieve ATS Envelopes with Matching Segments

After approving the deal in Console, you can call the ATS envelope API as you normally would. When calling the ATS Envelope API with an ATS Direct-enabled placement, multiple identity envelopes can be returned; one is a regular ATS envelope and the other is a Base64-encoded string of one or multiple matching segments.

🚧

ATS API V2 Endpoint Required

To retrieve the matched segments, you are required to create requests using the ATS API version 2 endpoint. For example:
https://api.rlcdn.com/api/identity/v2/envelope?pid=999&it=4&iv=3e33f1163236952e4fe8ea00ead7b8a2e65a75b694a462b14ef6b71d1913d89f&it=4&iv=939a10fa43251d6eaa21181c2d124435eca00e2f&it=4&iv=78200486ad9e3264708fd1fb36b5941d&atype=2

See our announcement to learn more.

4. Store the Matched Segments

In this scenario, we are going to store matching segments derived from the following response:

{ "envelopes": [ { "type": 19, "source": "envelopeLiveramp", "value": "AhvqG1wcqXtBAfXk3Ae4O0YEFRcoyU019W6KCmizTsAhekcSxApEa1yhH_jxxA6k2iS0UuttR5gKavSttH01RcCBU1UaHpcFPhkSrs3wt67u3AOc6YpvuwU-zIxOKnjl5IMZ", "err": null }, { "type": 26, "source": "atsDirect", "value": "WyIxOTk1ODcyMSIsIjE5OTYzMjQxIl0=", "err": null } ] } 

1. Take the entire atsDirect value object and decode from Base64 format. From the above response, the entire atsDirect value object is the following:
   WyIxOTk1ODcyMSIsIjE5OTYzMjQxIl0
2. After decoding from Base64, it should look like:
   ["19958721","19963241"]
3. Modify the result so it contains the envelope object.
   {"envelope":["19958721","19963241"]}
4. Encode the entire string to Base64 format:
   eyJlbnZlbG9wZSI6WyIxOTk1ODcyMSIsIjE5OTYzMjQxIl19
5. Take the encoded string and store it in a first-party cookie or local storage called _lr_atsDirect.

5. Store the Segment TTL

To be GDPR and CCPA compliant, segments saved in the browser cache should be stored 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.

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 to get an updated list of segments you will also need to update / set a new expiration time
In the example below, we use the first party cookie _lr_atsDirect_exp and the local storage key name _lr_atsDirect_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_atsDirect_exp=' + calculateEnvelopeTTL('US', 'CA'); // Example: set a cookie to track envelope expiration in 30 days document.cookie = '_lr_atsDirect_exp=' + calculateEnvelopeTTL(); // Example: set localStorage to track envelope expiration for 15 days localStorage.setItem('_lr_atsDirect_exp' , calculateEnvelopeTTL('US', 'CA'); // Example: set localStorage to track envelope expiration for 30 days localStorage.setItem('_lr_atsDirect_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_atsDirect_exp"); /* Then, call the Envelope Refresh API as required */ 

And for local storage:

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

6. Refresh the Envelope

Segments can be refreshed by using the ATS Envelope value in the refresh call. We highly recommend calling the Refresh Envelope API on the first subsequent page load after a user authenticates and again every 30 minutes when a user enters a new page or refreshes the current page.

You can refresh envelopes by calling:

https://api.rlcdn.com/api/identity/v2/envelope/refresh?pid=[placement id]&it=[envelope type]&iv=[envelope value]&ct=[consent type]&cv=[consent string]

See Implement ATS Refresh Envelope API to learn more.

7. Enable GAM Targeting

Once you have approved an ATS Direct deal in Console, you can pass the segments to the Google Publisher Tag (GPT). This allows Google Ad Manager (GAM) to correctly target those segments to present relevant users with ad creatives.

1. Retrieve targeting information from the lr_atsDirect cookie or local storage by calling the getATSDirectTargeting function. Optionally, you can use Prebid’s cookie retrieval function.

   JavaScript

   function getATSDirectTargeting() { var atsd_targeting = []; // Check if _lr_atsDirect exists as 1P cookie if (document.cookie.indexOf("_lr_atsDirect") == -1) { console.warn("_lr_atsDirect not found"); } else { // Get the value from the 1P cookie / local storage entry // The value is stored as a b64-encoded value // Decode it and retrieve the "envelope" object // This yields an array of 1 or more key-value pairs. try { var tArr = document.cookie.split(";"); tArr = tArr.filter((a) => a.includes("_lr_atsDirect")) tArr = tArr[0].split("=")[1]; tArr = atob(decodeURIComponent(tArr)); atsd_targeting = JSON.parse(tArr).envelope; } catch (e) { console.warn("Error parsing targeting information from cookie.", e); } } return atsd_targeting; } 

2. Call the enablePageTargeting function using the deal ID (segment ID for Connect users) of the deal you’ve approved in Console.
   To find the deal ID in Console, select ATS > Deals. On the Deals Selection tab, copy the value of the desired deal IDs from the table displayed.

   JavaScript

   const ATS_DIRECT_KEY = 'atsd'; /** * Example function to enable page targeting for Google Publisher Tags (GPT). * @param {Array<string>} atsDirectSegmentIds - An array of ATS Direct deal IDs to target. */ function enablePageTargeting(atsDirectSegmentIds) { // Check if the Google Publisher Tags (GPT) library is loaded if (window.googletag && window.googletag.pubads) { window.googletag.cmd.push(() => { // Set targeting for the specified deal IDs window.googletag.pubads().setTargeting(ATS_DIRECT_KEY, atsDirectSegmentIds); }); } else { // Log a warning if the GPT library is missing console.warn(`Can't set page ad targeting. Ensure the GPT library is loaded.`); } }; 

3. Combine the steps into a single operation below.

   JavaScript

   const atsDirectSegmentIds = getATSDirectTargeting(); enablePageTargeting(atsDirectSegmentIds);