Skip to main content

UID2 SDK for JavaScript Reference Guide

Use this SDK to facilitate the process of establishing client identity using UID2 and retrieving advertising tokens. The following sections describe the high-level workflow for establishing UID2 identity, provide the SDK API reference, and explain the UID2 storage format.

tip

If you're using Prebid.js with the UID2 Identity Module, or with another product that has UID2 support, you probably don't need to use the SDK at all. The Prebid.js module manages everything. For details, see UID2 Client-Side Integration Guide for Prebid.js.

This page describes version 3 of the UID2 SDK for JavaScript. If you are maintaining an integration using an earlier version, do one of the following:

Related information:

For integration steps for content publishers, see:

For example applications with associated documentation, see:

Functionality​

This SDK simplifies development for publishers who want to build their own customized UID2 integration. The following table shows the functions it supports.

Encrypt Raw UID2 to UID2 TokenDecrypt UID2 TokenGenerate UID2 Token from DIIRefresh UID2 Token
Not supportedNot supportedNot supportedSupported

API Permissions​

To use this SDK, you'll need to complete the UID2 account setup by following the steps described in the Account Setup page.

You'll be granted permission to use specific functions offered by the SDK, and given credentials for that access. Bear in mind that there might be functions in the SDK that you don't have permission to use. For example, publishers get a specific API permission to generate and refresh tokens, but the SDK might support other activities, such as sharing, which require a different API permission.

For details, see API Permissions.

SDK Version​

This documentation is for version 3 of the UID2 SDK for JavaScript.

GitHub Repository​

The source for this SDK is in the following open-source GitHub repository:

SDK Distribution​

The SDK is published in these locations:

  • CDN: https://cdn.prod.uidapi.com/uid2-sdk-${VERSION_ID}.js

    As of the latest update to this document, the most recent version is 3.2.0. You can also see the list of available versions.

  • CDN (Integration): https://cdn.integ.uidapi.com/uid2-sdk-${VERSION_ID}.js

    This integration URL contains un-minified code and is intended for testing purposes only. Do not use this URL for your production site.

    As of the latest update to this document, the most recent version is 3.2.0. You can also see the list of available versions.

Terminology​

In this document, the following terms apply:

  • Identity refers to a package of values, returned by the POST /token/generate or POST /token/refresh endpoint, that includes the UID2 token, the refresh token, and associated values such as timestamps.
  • Advertising token refers to the UID2 token.
  • Callback function refers to a callback function built for the current version of this SDK and registered using the Array Push Pattern.
  • Legacy callback function refers to a callback function built for version 1.x or 2.x of this SDK and registered in the call to init.

Include the SDK Script​

On every page where you want to use UID2 for targeted advertising, include the following SDK script:

<script src="https://cdn.prod.uidapi.com/uid2-sdk-3.2.0.js" type="text/javascript"></script>

Async or Defer Loading the SDK Script​

Version 3 and above of the SDK can be used with async or defer script loading.

If you are using async or defer script loading on your site, do the following:

  • (Required) Make sure you are calling __uid2.init from a callback function when it receives the SdkLoaded event.

  • (Required) Add the relevant attribute to the script tag.

  • (Recommended) Make sure that the script tag is in the <head> portion of the page, as shown in the following example:

    <head>
      <!-- ... -->
      <script async src="https://cdn.prod.uidapi.com/uid2-sdk-3.2.0.js" type="text/javascript"></script>
      <!-- ... -->
    </head>

Workflow Overview​

The high-level client-side workflow for establishing UID2 identity using the SDK consists of the following steps:

  1. Register a callback function using the Array Push Pattern.

  2. When your callback receives the SdkLoaded event, initialize the SDK using the init function.

  3. Wait for your event listener to receive the InitCompleted event. The event data indicates the identity availability:

  4. Handle the IdentityUpdated callback event that indicates changes to the identity.

    The identity property on the event payload either contains the new identity, or is null if a valid identity is not available.

  5. Handle the identity based on its state:

    • If the advertising token is available, use it to initiate requests for targeted advertising.
    • If the advertising token is not available, either use untargeted advertising or redirect the user to the data capture with the consent form.

For more detailed web integration steps, see Server-Side Integration Guide for JavaScript.

Background Token Auto-Refresh​

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

Here's what you need to know about the token auto-refresh:

  • Only one token refresh call can be active at a time.
  • If the POST /token/refresh response is unsuccessful because the user has opted out, or because the refresh token has expired, this suspends the background auto-refresh process. To use UID2-based targeted advertising again, you must obtain the email or phone number from the consumer. In all other cases, auto-refresh attempts continue in the background.
  • All callback functions provided using the Array Push Pattern are invoked in the following cases:
    • After each successful refresh attempt.
    • When identity has become invalid—for example, because the user has opted out.
      NOTE: The callback is not invoked when identity is temporarily unavailable and the auto-refresh keeps failing. In this case, the SDK continues using the existing advertising token as long as it hasn't expired.
  • A disconnect() call cancels the active timer.

Callback Function​

You can register functions to receive events from the UID2 SDK using the Array Push Pattern. There are a number of events currently available:

  • SdkLoaded is raised after the SDK has been parsed and the global __uid2 object has been constructed. This is useful for calling init(), especially if your script loading order is not guaranteed (for example, if you are using async or defer script loading).
  • InitCompleted is raised when init() has finished and the SDK is ready for use. If an identity was provided in the init call, or the SDK was able to load a previously-provided identity, the identity is included in the payload.
  • IdentityUpdated is raised whenever there is a new identity available, or the existing identity is no longer available.
tip

You can provide as many callback functions as you want, and register them from anywhere. This allows you to split your code up in a way that makes sense for your site.

Callback Function Signature​

Your callback function should accept two parameters: an event type and a payload. The type of the payload depends on the event type.

The following example callback handles the SdkLoaded event to call init and then, if an identity isn't available once init has completed, uses the InitCompleted event to provide an identity.

  window.__uid2 = window.__uid2 || {};
  window.__uid2.callbacks = window.__uid2.callbacks || [];
  window.__uid2.callbacks.push((eventType, payload) => {
    if (eventType === 'SdkLoaded') {
      __uid2.init({});
    }
    if (eventType === 'InitCompleted' && !payload.identity) {
        const generatedIdentity = await requestIdentityFromServer(); // Call your server-side integration to generate a token for the logged-in user
        __uid2.setIdentity(generatedIdentity);
    }
  });

Event Types and Payload Details​

EventPayloadDetails
SdkLoaded{}Called when the SDK script has loaded and the global __uid2 has been constructed. When you receive this event, it is safe to call __uid2.init. Callbacks always receive this event once. If the SDK has already been loaded when the callback is registered, it receives the event immediately.
InitCompleted{ identity: Identity | null }Called once init() has finished. Callbacks always receive this event once, as long as a successful call to init has been made. If init has already been completed when the callback is registered, it receives this immediately after it receives the SdkLoaded event.
IdentityUpdated{ identity: Identity | null }Called whenever the current identity changes. If the identity doesn't change after the callback is registered, callbacks do not receive this event.

The Identity type is the same type as the identity you can provide when calling init().

Array Push Pattern​

In order to best support script tags that are not guaranteed to load in order (for example, if you're using async or defer script tags), use the following pattern to register callbacks:

window.__uid2 = window.__uid2 || {};
window.__uid2.callbacks = window.__uid2.callbacks || [];
window.__uid2.callbacks.push(callbackFunction);

This ensures the following:

  • If your code runs before the SDK has loaded (meaning the global __uid2 object is not available), you can still provide a callback that the SDK can find.
  • If the SDK runs before your code does, you do not overwrite the __uid2 object or the callbacks array.
  • If multiple callbacks are registered using this pattern, they do not overwrite each other.

Provide an Identity to the SDK​

Unless the SDK is able to load a previously-stored identity from local storage or the cookie, you must provide an identity to it. There are several ways to do this:

If you store a first-party cookie, as described in the storage format section, and the value is newer than the value available in local storage, the SDK loads the value from the cookie. If you have set the useCookie init option to true, it always loads this value, and does not check local storage. You can control several other things about the cookie using init parameters.

Provide an Identity in the Call to init​

You can provide a new identity when you call init.

Provide an Identity by Calling setIdentity​

At any time after init has completed, you can call setIdentity to provide the SDK with a new identity to use.

API Reference​

info

All interactions with the UID2 SDK for JavaScript are done through the global __uid2 object, which is an instance of the UID2 class. All of the following JavaScript functions are members of the UID2 class.

constructor()​

Constructs a UID2 object. This is not intended to be used directly: when the SDK loads, it automatically initializes an instance of the UID2 class and stores it as the global __uid2 object. Advanced integrations may make use of this constructor directly, but must take care to avoid having multiple active instances of the SDK running. This is not a supported use case.

tip

Instead of calling this function, just use the global __uid2 object.

init(opts: object): void​

Initializes the SDK and establishes user identity for targeted advertising.

Here's what you need to know about this function:

  • You can call init() any time after the SDK has been loaded. The recommended way to do this is by registering a callback function that handles the SdkLoaded event using the Array Push Pattern. By using this pattern you can make sure that your code works regardless of script load order, and that using async or defer on your script tags does not cause UID2 SDK errors.
  • The identity property in the init() call refers to the body property of the response JSON object returned from a successful POST /token/generate or POST /token/refresh call with the server-side generated identity. This is a good way to provide the identity if your server-side integration ensures you always have a current token available and it is more convenient to provide it using JavaScript.
  • If the identity property in the init() call is falsy, the SDK attempts to load the identity from local storage or the cookie.
    • Once init() is complete, all callbacks receive the InitCompleted event. If the identity property on the payload of this event is null, no identity could be loaded, and you should therefore provide an identity to the SDK. This is the recommended way to provide an identity if your server-side integration does not ensure a current identity is always available, and you need to request it from the server only when necessary.
    • If you are using a first-party cookie (see UID2 Storage Format) to store the passed UID2 information for the session, a call to init() made by a page on a different domain might not be able to access the cookie. You can adjust the settings used for the cookie with the cookieDomain and cookiePath options.
  • To tune specific behaviors, initialization calls might include optional configuration init parameters.

The following is an example of an init() call made using a callback with the server-side generated identity included.

<script>
  window.__uid2 = window.__uid2 || {};
  window.__uid2.callbacks = window.__uid2.callbacks || [];
  window.__uid2.callbacks.push((eventType, payload) => {
    if (eventType === "SdkLoaded") {
      __uid2.init({
        identity : { // The `body` property value from the token/generate or token/refresh API response.
          "advertising_token": "AgmZ4dZgeuXXl6DhoXqbRXQbHlHhA96leN94U1uavZVspwKXlfWETZ3b/besPFFvJxNLLySg4QEYHUAiyUrNncgnm7ppu0mi6wU2CW6hssiuEkKfstbo9XWgRUbWNTM+ewMzXXM8G9j8Q=",
          "refresh_token": "Mr2F8AAAF2cskumF8AAAF2cskumF8AAAADXwFq/90PYmajV0IPrvo51Biqh7/M+JOuhfBY8KGUn//GsmZr9nf+jIWMUO4diOA92kCTF69JdP71Ooo+yF3V5yy70UDP6punSEGmhf5XSKFzjQssCtlHnKrJwqFGKpJkYA==",
          "identity_expires": 1633643601000,
          "refresh_from": 1633643001000,
          "refresh_expires": 1636322000000
        }
      });
    }
  });
</script>

The following is an example of an init() call that loads a previously-provided identity from local storage, if one is available. You can put a script like this on any page that the user might visit after the identity has been established.

<script>
  window.__uid2 = window.__uid2 || {};
  window.__uid2.callbacks = window.__uid2.callbacks || [];
  window.__uid2.callbacks.push((eventType, payload) => {
    if (eventType === "SdkLoaded") {
      __uid2.init({}); // Note that you must provide a configuration object, even if you're not providing any options.
    }
  });
</script>

Init Parameters​

The opts object supports the following properties.

PropertyData TypeAttributeDescriptionDefault Value
identityobjectOptionalThe body property value from a successful POST /token/generate or POST /token/refresh call that has been run on the server to generate an identity.
To use the identity from a first-party cookie (see UID2 Storage Format), leave this property empty.		N/A
baseUrlstringOptionalThe custom base URL of the UID2 operator to use when invoking the POST /token/refresh endpoint.
For example: https://my.operator.com.		https://prod.uidapi.com.
refreshRetryPeriodnumberOptionalThe number of milliseconds after which to retry refreshing a token if an intermittent error occurs.
This value must be >= 1000.		5000
cookieDomainstringOptionalThe domain name string to apply to the UID2 cookie (see UID2 Storage Format).
For example, if the baseUrl is https://my.operator.com, the cookieDomain value might be operator.com.		undefined
cookiePathstringOptionalThe path string to apply to the UID2 cookie (see UID2 Storage Format)./
useCookiebooleanOptionalSet this to true to tell the SDK to store the identity in cookie storage instead of local storage. You can still provide an identity using a first-party cookie if this value is false or not provided.
callbackfunction(object): voidDeprecatedThe function that the SDK should invoke after validating the passed identity. Do not use this for new integrations.N/A

Errors​

The init() function can throw the following errors.

ErrorDescription
TypeErrorOne of the following issues has occurred:
  • The function has already been called.
  • The opts value is not an object.
  • A legacy callback is provided, but it is not a function.
  • refreshRetryPeriod is provided, but it is not a number.
RangeErrorThe refresh retry period is less than 1000.

Legacy Callback Function​

This is provided for backward compatibility only: new integrations should use the new-style callback function. Note that the callback parameters are not compatible in either direction: legacy callbacks cannot be registered using the Array Push Pattern, and new-style callbacks cannot be provided to init.

For details, see Legacy Callback Function in the documentation for earlier versions of this SDK.

If you have already built an integration using a legacy callback function, you can use it with the current version of the SDK with no changes. However, this functionality will be removed in a future version of the SDK. We strongly recommend that you update your integration to use the new-style callback function.

getAdvertisingToken(): string​

Gets the current advertising token.

Before calling this function, be sure to call init() and wait until your callback handler has received an InitCompleted event.

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

The getAdvertisingToken() function allows you to access the advertising token from anywhere—not just from the callback that's done when initialization is complete.

This function returns undefined if any of the following conditions apply:

  • The callback function has not received an InitCompleted event, which means that the SDK initialization is not yet complete.
  • The SDK initialization is complete, but there is no valid identity to use.
  • The SDK initialization is complete, but the auto-refresh has cleared the identity—for example, because the user has opted out.

If the identity is not available, use the isLoginRequired() function to determine the best course of action.

getAdvertisingTokenAsync(): Promise​

Gets a Promise string for the current advertising token.

This function can be called before or after the init() call. The returned promise is settled after the initialization is complete, based on the availability of the advertising token:

  • If the advertising token is available, the promise is fulfilled with the current advertising token.
  • If the advertising token is not available, even temporarily, the promise is rejected with an instance of Error. To determine the best course of action in this case, you can use isLoginRequired().

You can use this function to be notified of the completion of the Client-Side JavaScript SDK initialization if you only want to receive the identity available once init is complete, and you do not want to continue receiving updates to the identity.

info

If the getAdvertisingTokenAsync() function is called after the initialization is complete, the promise is settled immediately based on the current state.

tip

It might be easier to use the callback function to be notified whenever the identity changes.

<script>
  __uid2.getAdvertisingTokenAsync()
    .then(advertisingToken => { /* initiate targeted advertising */ })
    .catch(err => { /* advertising token not available */ });
</script>

isLoginRequired(): boolean​

Specifies whether a UID2 POST /token/generate call is required.

<script>
  __uid2.isLoginRequired();
</script>

Return Values​

ValueDescription
trueThe identity is not available. This value indicates any of the following:
  • The user has opted out.
  • The refresh token has expired.
  • A first-party cookie is not available and no server-generated identity has been supplied.
falseThis value indicates one of the following:
  • The identity is present and valid.
  • The identity has expired (but the refresh token has not expired), and the token was not refreshed due to an intermittent error. The identity might be restored after a successful auto-refresh attempt.
undefinedThe SDK initialization is not yet complete.

disconnect(): void​

Clears the UID2 identity from the first-party cookie and local storage (see UID2 Storage Format). This closes the client's identity session and disconnects the client lifecycle.

When a user logs out of the publisher's site, make the following call:

<script>
  __uid2.disconnect();
</script>

After this function is executed, the getAdvertisingToken() function returns undefined and the isLoginRequired() function returns true.

danger

If you need to provide a cookieDomain or cookiePath for the SDK to access the correct cookie, and init has not been completed, the SDK cannot clear the cookie. In this case, no error is raised.

abort(): void​

Terminates any background timers or requests. The UID2 object remains in an unspecified state and cannot be used anymore.

This function is intended for use in advanced scenarios where you might want to replace the existing UID2 object with a new instance.

callbacks​

This is an array that stores all of the registered callbacks. You should only interact with it using the Array Push Pattern.

setIdentity(identity: Identity): void​

Use this function to provide a new identity to the UID2 SDK. Any existing refresh attempts are cancelled, and the new identity is used for all future operations. A new refresh timer is started. Once the identity has been validated, all registered event handlers are called with an IdentityUpdated event containing the new identity.

setIdentity throws an error if it is called before init has completed.

tip

setIdentity() is useful if your page is a single-page app that might not have the identity available when it first loads. This allows you to call init (and load any stored identity) on page load, and then provide an identity later if there was no stored identity.

getIdentity(): Identity | null​

Returns the current stored identity, if available.

If there is a valid identity available, the return value is an object representing the full stored identity. The properties of the object are the same as the stored value as described in the contents structure section.

If there is no currently valid identity (even if the identity is only temporarily unavailable), the return value is null. If you need to know whether the identity is only temporarily unavailable, you can call isLoginRequired().

UID2 Storage Format​

The SDK uses either local storage or a first-party cookie to store the user's identity. The default option is to use local storage, but this can be changed using an init parameter.

Even when using local storage, the SDK checks to see if there is a newer identity available in a first-party cookie. This allows the SDK to make use of local storage while still allowing you to provide an identity by setting the first-party cookie.

If cookie storage is being used, the cookie uses the properties in the following table.

PropertiesDefault ValueComments
Name__uid_2N/A
ExpiryN/AThe value is the refresh token expiration timestamp as specified in the POST /token/generate or POST /token/refresh response.
Path/If you want to use a different value, you can set it during SDK initialization using the cookiePath init() parameter.
DomainundefinedIf you want to use a different value, you can set it during SDK initialization using the cookieDomain init() parameter.

Contents Structure​

The content of the UID2 local storage or cookie is a URI-encoded string representation of a JSON object with the structure identical to that of the body property in a POST /token/generate or POST /token/refresh response, with the exception of the private object.

The following is an example of the UID2 cookie structure:

{
   "advertising_token":"AgAAAAVacu1uAxgAxH+HJ8+nWlS2H4uVqr6i+HBDCNREHD8WKsio/x7D8xXFuq1cJycUU86yXfTH9Xe/4C8KkH+7UCiU7uQxhyD7Qxnv251pEs6K8oK+BPLYR+8BLY/sJKesa/koKwx1FHgUzIBum582tSy2Oo+7C6wYUaaV4QcLr/4LPA==",
   "refresh_token":"AgAAAXxcu2RbAAABfGHhwFsAAAF79zosWwAAAAWeFJRShH8u1AYc9dYNTB20edyHJU9mZv11e3OBDlLTlS5Vb97iQVumc7b/8QY/DDxr6FrRfEB/D85E8GzziB4YH7WUCLusHaXKLxlKBSRANSD66L02H3ss56xo92LMDMA=",
   "identity_expires":1633643601000,
   "refresh_from":1633643001000,
   "refresh_expires":1636322000000,
   "refresh_response_key":"dYNTB20edyHJU9mZv11e3OBDlLTlS5Vb97iQVumc7b/8QY/DDxr6FrRfEB/D",
   "private":{     
   }
}
danger

The contents of the private object are explicitly unspecified and are left for the SDK to interpret. Do not make any assumptions about the structure, semantics, or compatibility of this object. Any updates to the cookie must retain its structure.

Migration Guide​

This section includes all the information you need to upgrade from an earlier version of the UID2 SDK for JavaScript to the current version, v3. It includes:

Benefits of Migrating​

If your existing integration uses version 1.x or 2.x of the SDK, version 3 is fully backwards-compatible. You can update to version 3 of the SDK just by changing your script tag to refer to the new URL. Doing this gives you the following benefits:

  • The script is now distributed using the UID2 CDN, and should therefore load faster.

  • The SDK tries to use local storage instead of cookies for storing the identity. If the cookie provides a newer token than the one in local storage, the SDK still loads the identity from the cookie.

    Notes about this approach:

    • A default of local storage has been requested by a number of publishers who are close to the maximum size limit for cookies.
    • If you rely on setting a first-party cookie to provide a new identity, you do not gain any benefit from this change.
    • If you only provide the identity by passing it to init, the SDK no longer writes to the cookie.

Some of the functionality from versions 1.x and 2.x has been deprecated, and you should make changes to future-proof your integration.

  • The legacy callback system has been deprecated and will eventually be removed.

By updating your integration, you can take advantage of the additional features available:

  • Script loading using async or defer is now fully supported.

  • The callback system is simpler, with fewer states to manage.

  • You can provide multiple callbacks, and they can be registered at any time—before or after init has been called.

  • Full TypeScript support.

  • Functions to set the identity after init() has been called.

    This makes the SDK much easier to use in single-page app scenarios.

Required Changes​

Update your script URL​

Update your script tag to load the SDK from the version 3 CDN URL.

We strongly recommend that you implement the following changes to get the benefits of version 3 of the SDK:

Migrate to the Version 3 Callback System​

In earlier versions, the callback accepts a single object as a parameter, with properties advertisingToken, status, and statusText. For version 3, change this function to use the new Callback Function Signature.

Your original callback probably has some logic to deal with different values of status. The previous system had a variety of different status values to handle, such as EXPIRED, REFRESHED, and NO_IDENTITY. The new system instead has only three event types: SdkLoaded, InitCompleted, and IdentityUpdated.

This guide cannot cover every possible scenario, and you should review the Callback Function section and consider the best way to implement your requirements using the new system. However, there are some general guidelines that should help:

  • Check the event parameter. If the value is SdkLoaded, return immediately.
  • Otherwise, check to see if the payload parameter has an identity property.
    • If there is no object on the identity property, there is no UID2 identity available. You should invoke whatever the previous callback did in the equivalent situation.
    • Otherwise, the identity property is an object with a string property named advertising_token. You should use this in the same way that the old callback did.

Remove the old callback from your init call, and provide your updated callback function to the SDK using the Array Push Pattern:

window.__uid2 = window.__uid2 || {};
window.__uid2.callbacks = window.__uid2.callbacks || [];
window.__uid2.callbacks.push(callbackFunction);

Take advantage of setIdentity and other new features​

Previous versions of the SDK had only one way to provide a new identity: in the call to init. This meant that some publishers had to make use of various workarounds to provide a new identity later in the page lifecycle. You might be able to simplify your integration by removing these workarounds and simply calling setIdentity if you want to pass a new identity to the SDK after init has been called.

Change how you call init​

The recommended way to call init is by using the Array Push Pattern. Your existing call to init should be moved inside a callback handler that only handles the SdkLoaded event, as shown in the following example:

window.__uid2 = window.__uid2 || {};
window.__uid2.callbacks = window.__uid2.callbacks || [];
window.__uid2.callbacks.push((eventType) => {
  // Each callback function you register with the SDK is invoked once with the `SdkLoaded` event type after the SDK has been loaded by the browser and is ready to use.
  if (eventType === 'SdkLoaded' {    
    __uid2.init({
      /* Provide the same options as in your previous code. If you're not using the legacy callback any more, remove it from here. */
    });
  })
});

Optional Changes​

Add async or defer to your script tag​

If you have decided to use async or defer script loading, move the script tag that loads the SDK into the document header and add the appropriate keyword.

Deciding to use async or defer script loading is not something the UID2 team can provide advice on, because it depends on the individual website. If you're not sure, it is safe to ignore this change and leave your script tag unchanged.