Configuring ATS is essential to its proper operation. The configuration object you pass to ATS will instruct it how and when to transform PII into secure, encrypted identity envelopes.

While you can manually write your own configuration object, the easiest way to create a valid configuration is to use the LiveRamp configuration tool. To use the configuration tool, see the external showcase.

Required Attributes

You must include a valid placementID in your configuration object. This value is provided by LiveRamp to identify your instance of ATS.

If you don't have a placementID, please reach out to [email protected].

Direct vs. Detect

ats.js has two basic modes of operation: direct and detect.

In direct mode, you provide the identifier directly to the ATS library. If you already have user login information on your backend, a sure-fire way to ensure that it is usable by demand is to include it directly in your configuration.

If you know that users will provide an identifier on your property, but you aren't able to provide it server-side (for example, if you have a newsletter signup provided by a Marketo or Mailchimp widget), you can use DOM or URL-driven detection methods.

Direct

ATS currently supports two routes to pass identifiers directly to the library.

{
  "placementID": 9999,
  "email": "[email protected]"
}
or
{
  "placementID": 9999,
  "phoneNumber": "4152218778"
}

{
  "placementID": 9999,
  "emailHashes": [
    "b364fe946d9982c6c547d5637645f9c3dd60ca2aa174e551718509d5dee66ab7",
    "b2c0928035d5f521a880381dc7ec85df7b7e06b3",
    "4466aba660dd65e279fb8700f7ff1cb9"
  ]
}

We recommend that you pass either a plaintext email address, a plaintext phone number, or pass all three hash types of an email address to ATS to ensure the best possible identity resolution (and therefore matches to users that advertisers want to reach).

If you decide to pass email hashes, make sure that you follow these steps:

1. Validate the email against a regular expression
2. Remove whitespace (spaces, tabs, etc)
3. Downcase the email address
   

   🚧

   Phone Number Support

   Phone numbers are only supported in the US at the moment.

   Due to a lack of support for SHA1 hashing, phone numbers are not supported on Microsoft IE/Edge browsers.

Detect

DOM Detection

ATS can be configured to accept one or more standard CSS selectors that instruct it where to watch for identifiers.

{
  "placementID": 9999,
  "cssSelectors": [
    "input[type=text]",
    "input[type=email]",
    "#newsletterSignup"
  ]
}

When you configure CSS selectors for ATS, detection is running when the page first loads (if the identifier already exists in the element) and when an onBlur event is fired on the element.

URL Detection - Plaintext and Hashed

You can alternatively instruct ATS to watch for an identifier in a URL parameter. For example, if users click through email notifications and land on https://example.com/[email protected], you can configure ATS to check values in the email_trigger parameter. Ensure you pass the url value under the detectionType attribute.

{
  "placementID": 9999,
  "detectionType": "url",
  "urlParameter": "email_trigger"
}

ats.js also supports passing of hashed identifiers in the URL. Be sure to specify whether an email address or phone number is provided. As a hashed version of the configuration about, the user could click through to https://example.com/alerts?email_trigger=b2c0928035d5f521a880381dc7ec85df7b7e06b3. The ats.js configuration would be enabled as:

{
  "placementID": 9999,
  "detectionType": "url",
  "urlParameter": "email_trigger",
  "detectionSubject": "all"
}

DOM Recheck

If your site has parts that load dynamically, please make sure to add the DOM Recheck function. An example of this would include, a website that has infinite scroll or a newsletter subscription pop-over that appears after the initial page load.

You will need to add the below parameter to your ats.js.
"detectDynamicNodes": true,

Full ats.js with Dom Recheck:

"placementID": 999,
  "detectionType": "scrapeAndUrl",
  "urlParameter": "env",
  "detectDynamicNodes": true,
  "detectionEventType": 'onblur',
  "cssSelectors": [
    "input[type=email]",
    "input[type=text]"
  "logging":"debug",
  ]
}

Simultaneous DOM and URL Detection

You can instruct ATS to use both on-page and URL element by passing the scrapeAndUrl attribute in the configuration:

{
  "placementID": 9999,
  "detectionType": "scrapeAndUrl",
  "urlParameter": "env",
  "cssSelectors": [
    "input[type=text]",
    "input[type=email]",
    "#newsletterSignup"
  ],
   "urlParameter": "email_trigger",
  "detectionSubject": "email"
}