Skip to main content

Configure Prebid.js for ATS

ATS provides addressable inventory without dependence on third-party cookies for any website and is optimized to plug into the open-source Prebid.js. In this article, you will learn how to configure Prebid.js to monetize your inventory.

If you are implementing ATS directly via API, the method in this article also works for you. See the diagrams below to learn how Prebid.js integration works with ATS.js and API implementation.

How Prebid.js Works With ATS.js (ATS for Web)

Prebid_js_with_ats.jpg
  1. ATS.js checks for a positive consent signal when required.

  2. ATS.js will detect the identifier on the page and applies hashes.

  3. ATS.js sends the hashed identifier to the ATS Envelope API which resolves it to an identity envelope and returns the identity envelope back to ATS.js.

  4. ATS.js stores the identity envelope according to configured storage.

  5. Prebid.js retrieves the identity envelope from configured storage and stores it according to Prebid specifications so it can be used for advertisement purposes.

  6. Prebid.js sends out ad requests with the identity envelope to bidders downstream.

  7. Bidders respond to the ad requests and an advertisement is served on the page.

How Prebid.js Works With Direct ATS API Implementation

Prebid_js_dan_api_.jpg
  1. Publisher provides the hashed identifier, and a positive consent signal when required, directly to the ATS Envelope API.

  2. ATS Envelope API resolves the hashed identifier to an identity envelope and makes it available to the publisher. Publisher then stores the identity envelope in a first-party cookie or local storage.

  3. Prebid.js retrieves the identity envelope from configured storage and stores it according to Prebid specifications so it can be used for advertisement purposes.

  4. Prebid.js sends out ad requests with the identity envelope to bidders downstream.

  5. Bidders respond to the ad requests and an advertisement is served on the page.

Before You Begin

Make sure you have implemented ATS.js or the ATS API. For envelopes to be successfully passed to bidders, you must have ATS running on all Prebid-enabled pages.

How to Configure Prebid.js for ATS

  1. Go to Prebid.org

  2. Select the latest version of Prebid.js core.

  3. Include the following ATS / RampID compatible modules:

    1. RampID (formerly known as identityLink ID) - For retrieving and storing of RampID envelopes for Prebid to send downstream.

      Notice

      As of May 24, 2021, the name for LiveRamp's pseudonymous identifier (formerly known as "IdentityLink" or "IDL") is now "RampID." You might continue to see the previous names in help documentation and in third-party resource names. See this announcement for more information.

    2. ATS Analytics (Optional) - Analytics adapter to track header bidding performance for your site. To use this module you will need to subscribe to the ATS Analytics product in Console and create an adapter.

      Caution

      If the ATS Analytics module is not added to your Prebid.js set up, and later on you want to take advantage of ATS Analytics, you will have to overwrite your existing Prebid.js configuration and restart the set up process.

    3. Consent Management - GDPR - If you have users in Europe, this module works with your Consent Management Platform to pass consent info to bidders and help align with EU regulations. See also the GDPR Enforcement module.

    4. Consent Management - U.S. Privacy - If you have users in California, this module works with your Consent Management Platform to pass CCPA/U.S.-Privacy data to bidders.

    5. GDPR Enforcement - If you have users in Europe, you'll want this module that enforces GDPR consent.

  4. After you download your properly-configured Prebid.js file, update your call to pbjs.setConfig to pass the required information to the RampID user ID module. See the example below to learn how you can do this for cookie and local storage.

    Identity envelope stored in a cookie:

    pbjs.setConfig({
        userSync: {
            userIds: [{
                name: "identityLink",
                params: {
                    pid: '999',             // Set your ATS Placement ID here
                    notUse3P: true/false    // If you want to generate and use a RampID based on a LiveRamp 3p cookie (from a previous authentication) until ATS can generate a new RampID, set this property to false.
                },
                storage: {
                    type: "cookie",
                    name: "idl_env",        // "idl_env" is the required storage name
                    expires: 15,            // Identity envelope can last for 15 days
                    refreshInSeconds: 1800  // Identity envelope will be updated every 30 minutes
                }
            }],
            syncDelay: 3000                 // 3 seconds after the first auction
        }
    });

    Identity envelope stored in local storage:

    pbjs.setConfig({
        userSync: {
            userIds: [{
                name: "identityLink",
                params: {
                    pid: '999',             // Set your ATS Placement ID here
                    notUse3P: true/false    // If you want to generate a RampID based on a LiveRamp 3p cookie (from a previous authentication) until ATS can generate a new RampID, set this property to false.
                },
                storage: {
                    type: "html5",
                    name: "idl_env",        // "idl_env" is the required storage name
                    expires: 15,            // Identity envelope can last for 15 days
                    refreshInSeconds: 1800  // Identity envelope will be updated every 30 minutes
                }
            }],
            syncDelay: 3000                 // 3 seconds after the first auction
        }
    });

Note

LiveRamp will encrypt the RampID envelope that is delivered to Prebid with a rotating key to avoid unauthorized usage and to enforce privacy requirements. Therefore, we strongly recommend setting storage.refreshInSeconds to 30 minutes (1800 seconds, as illustrated in the code example above ) to ensure all demand partners receive an ID that has been encrypted with the latest key, has up-to-date privacy signals, and allows them to transact against it.

Test Your RampID Module Configuration

  1. Navigate to one of the pages of your website where ATS is installed and provide the identifier.

  2. To ensure that your ATS.js or ATS API-only implementation was able to resolve the identifier and store the identity envelope in configured storage, open the browser console and enter window.ats.retrieveEnvelope();. The response should contain an identity envelope.

  3. Open a Prebid-enabled page on your site.

  4. To ensure that Prebid returns an identity envelope, open the browser console and enter pbjs.getUserIds();. If no LiveRamp identity envelope is returned in the response it can indicate that:

    1. There is no ATS.js running on the Prebid-enabled page or there is no function available to retrieve envelopes. Check if the Prebid-enabled page is included in your ATS.js configuration.

    2. No LiveRamp identity envelope is stored in a first-party cookie or local storage and thus there is no ‘assigned’ identity.

  5. Switch to the "Network" tab and see if the envelopes are being pushed to SSPs (Suply-Side Platforms) in ad calls. Pubmatic's POST to https://hbopenbid.pubmatic.com/translator?source=prebid-client, for example, is easy to check, looking for something like the below screenshot:

    f46b1a7-image_2.png

Set up ATS Analytics

If you have added the Analytics module and completed the Prebid.js configuration above, you can set up the Analytics module to get a better understanding of how ATS improves your digital monetization. Setting up the Analytics module also allows you access to the ATS Analytics dashboard.

To learn how to configure the Analytics module, see "Configure ATS Analytics for Prebid.js".