Skip to main content

JavaScript Standard Integration Guide

This guide is intended for publishers with web assets who want to generate identity tokens using UID2 for the RTB bid stream, while integrating directly with UID2 rather than UID2-enabled single-sign-on or identity providers. This requires server-side changes such as generating UID2 tokens on the server side and passing them to the publishers' web pages. If you want to integrate with UID2 via only client-side JavaScript changes, refer to JavaScript Express Integration Guide instead.

For technical details about the SDK, see UID2 SDK for JavaScript Reference Guide.

Sample Implementation Website​

For an example application, see the UID2 Google ESP with SDK v3 example:

Introduction​

This guide outlines the basic steps that you need to consider if you are building an integration without using an SDK. For example, you need to decide how to implement user login and logout, how to manage UID2 identity information and use it for targeted advertising, and how to refresh tokens, deal with missing identities, and handle user opt-outs.

For a workflow diagram, see Integration Steps. See also FAQs.

To facilitate the process of establishing client identity using UID2 and retrieving advertising tokens, the web integration steps provided in this guide rely on the UID2 SDK for JavaScript. Here's an example application that illustrates the integration steps described in this guide and the usage of the SDK (currently only for email addresses). For the application documentation, see UID2 SDK Integration Example.

tip

The first-party cookie and local storage implementation details might change in the future. To avoid potential issues, be sure to rely on the functionality documented in the UID2 SDK for JavaScript API Reference for your identity management.

For integration scenarios for publishers that do not use the UID2 SDK for JavaScript, see Publisher Integration Guide, Server-Only.

note

If you are using Google Ad Manager and want to use the secure signals feature, first follow the steps in this guide and then follow the additional steps in the Google Ad Manager Secure Signals Integration Guide.

Integration Steps​

The following diagram outlines the steps required for establishing a user's UID2 token with a publisher and how the UID2 token integrates with the RTB bid stream.

Publisher Flow

The following sections provide additional details for each step in the diagram:

  1. Establish identity: User Login
  2. Bid Using UID2 Tokens
  3. Refresh Tokens
  4. Clear Identity: User Logout

Establish Identity: User Login​

After authentication in step 1-c, which forces the user to accept the rules of engagement and allows the publisher to validate the user's email address or phone number, a UID2 token must be generated on the server side. The following table details the token generation steps.

StepEndpoint/SDKDescription
1-dPOST /token/generateAfter the user authenticates and authorizes the creation of a UID2, use the POST /token/generate endpoint to generate a UID2 token using the email address or phone number provided by the user. Make sure it is normalized.
1-ePOST /token/generateThe endpoint returns a UID2 token generated from the user's email address, phone number, or the respective hash.
1-fUID2 SDK for JavaScriptThe SDK sends the returned UID2 token from step 1-e to the SDK in the identity property of its init() function.
1-gUID2 SDK for JavaScriptProvide the SDK a callback function that will receive identity updates from the SDK and use them to initiate targeted advertising.
  window.__uid2 = window.__uid2 || {};
  window.__uid2.callbacks = window.__uid2.callbacks || [];

  // Step 1-f
  window.__uid2.callbacks.push((eventType, payload) => {
    if (eventType === 'SdkLoaded') {
      __uid2.init({
        identity : {
          "advertising_token": "AgmZ4dZgeuXXl6DhoXqbRXQbHlHhA96leN94U1uavZVspwKXlfWETZ3b/besPFFvJxNLLySg4QEYHUAiyUrNncgnm7ppu0mi6wU2CW6hssiuEkKfstbo9XWgRUbWNTM+ewMzXXM8G9j8Q=",
          "refresh_token": "Mr2F8AAAF2cskumF8AAAF2cskumF8AAAADXwFq/90PYmajV0IPrvo51Biqh7/M+JOuhfBY8KGUn//GsmZr9nf+jIWMUO4diOA92kCTF69JdP71Ooo+yF3V5yy70UDP6punSEGmhf5XSKFzjQssCtlHnKrJwqFGKpJkYA==",
          "identity_expires": 1633643601000,
          "refresh_from": 1633643001000,
          "refresh_expires": 1636322000000,
          "refresh_response_key":"dYNTB20edyHJU9mZv11e3OBDlLTlS5Vb97iQVumc7b/8QY/DDxr6FrRfEB/D",
        }
      });
    }
  });

  // Step 1-g
  window.__uid2.callbacks.push((eventType, payload) => {
    if (eventType !== 'SdkLoaded') {
      if (payload.identity) {
        const advertisingToken = payload.identity.advertising_token;
        // Pass advertising_token to your advertising system to use
      } else {
        // No identity is available for targeted advertising - trigger a login flow if you want to use UID2 for targeted advertising
      }
    }
  });

The SDK invokes the specified callback function (which indicates the identity availability) and makes the established identity available client-side for bidding.

tip

Depending on the structure of your code, it might be convenient to combine the callbacks for steps 1-f and 1-g into a single callback function.

Bid Using UID2 Tokens​

Based on the status and availability of a valid identity, the SDK does the following:

  1. Sets up the background token auto-refresh.
  2. Stores identity information in local storage or a first-party cookie.
  3. Uses the identity information to initiate requests for targeted advertising.

The bidding step is shown in the following table.

StepEndpoint/SDKDescription
2-aUID2 SDK for JavaScriptGets the current user's advertising token by using the getAdvertisingToken() function as shown below.

NOTE: For an example of what a UID2 token might look like in the bid stream, when it's sent from an SSP to a DSP, see What does a UID2 token look like in the bid stream?

<script>
  let advertisingToken = __uid2.getAdvertisingToken();
</script>
info

You need to consider how you pass the returned advertising token to SSPs. With some other approaches to client-side UID2 implementation, such as using Prebid.js (see Prebid Integration Guide) or Google Ad Manager Secure Signals (see Google Ad Manager Secure Signals Integration Guide), the implementation includes functions that manage passing the returned advertising token. If you're using the UID2 SDK for JavaScript you'll need to manage this yourself.

tip

Instead of calling __uid2.getAdvertisingToken(), you can use the advertising_token property of the identity passed to the callback that you set up for step 1-g. The callback will be called every time the identity changes.

Refresh Tokens​

As part of its initialization, the SDK sets up a token auto-refresh for the identity, which is triggered in the background by the timestamps on the identity or by failed refresh attempts due to intermittent errors.

StepEndpoint/SDKDescription
3-aUID2 SDK for JavaScriptThe SDK automatically refreshes UID2 tokens in the background. No manual action is required.
3-bUID2 SDK for JavaScriptIf the user hasn't opted out, the POST /token/refresh endpoint automatically returns new identity tokens.

Clear Identity: User Logout​

The client lifecycle is complete when the user decides to log out from the publisher's site (not UID2). This closes the client's identity session and clears the first-party cookie information.

StepEndpoint/SDKDescription
4-aN/AThe user logs out from the publisher's asset.
4-bUID2 SDK for JavaScriptThe SDK clears the UID2 identity from the first-party cookie and disconnects the client lifecycle by using the disconnect() function as shown below.
<script>
  __uid2.disconnect();
</script>

FAQs​

For a list of frequently asked questions for the publisher audience, see FAQs for Publishers.