Skip to main content

SDK for JavaScript Reference Guide (2.x and earlier versions)

NOTE: This documentation is for earlier versions of the EUID SDK for JavaScript. If you're using an earlier version, we recommend upgrading. See EUID SDK for JavaScript Reference Guide, which includes a migration guide.

The SDK for JavaScript is intended to facilitate the process of establishing client identity using EUID and retrieving advertising tokens. The following sections describe the high-level workflow for establishing EUID identity, provide the SDK API reference, and explain the EUID cookie format. For integration steps for content publishers, see SDK for JavaScript Integration Guide.

NOTE: Within this documentation, the term "identity" refers to a package of EUID tokens, including the advertising token.

Include the SDK Script

Include the following SDK script on the pages where you want to use EUID to manage identity or retrieve an advertising token for targeted advertising:

<script src="https://prod.euid.eu/static/js/euid-sdk-1.0.0.js" type="text/javascript"></script> TBD

Workflow Overview

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

  1. Initialize the SDK and specify a callback function to be called upon a successful completion of the step.
  2. Wait for the SDK to invoke the callback function. The callback function indicates the identity availability:
  3. Based on the identity state, the SDK does the following:
    • If a valid identity is available, the SDK ensures the identity is available in a first-party cookie.
    • If the identity is unavailable, the SDK takes the appropriate action based on whether identity is refreshable or not. For details, see Workflow States and Transitions.
  4. 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 intended web integration steps, see SDK for JavaScript Integration Guide.

Workflow States and Transitions

The following table outlines the four main states in which the SDK can be, based on the combination of values returned by two main functions, getAdvertisingToken() and isLoginRequired(), and indicates the appropriate action that you, as a developer, can take in each state.

StateAdvertising TokenLogin RequiredDescriptionIdentity Status Value
InitializationundefinedundefinedInitial state until the callback is invoked.N/A
Identity Is AvailableavailablefalseA valid identity has been successfully established or refreshed. You can use the advertising token in targeted advertising.ESTABLISHED or REFRESHED
Identity Is Temporarily UnavailableundefinedfalseThe identity (advertising token) has expired, and automatic refresh failed. Background auto-refresh attempts will continue until the refresh token expires or the user opts out.
You can do either of the following:
- Redirect the user, asking for the email.
- Use untargeted advertising.
NOTE: Identity may be successfully refreshed after some time—for example, if the EUID service is temporarily unavailable.
EXPIRED
Identity Is Not AvailableundefinedfalseThe identity is not available and cannot be refreshed. The SDK clears the first-party cookie.
To use EUID-based targeted advertising again, you must obtain the email from the consumer.
INVALID, NO_IDENTITY, REFRESH_EXPIRED, or OPTOUT

The following diagram illustrates the four states, including the respective identity status values, and possible transitions between them. The SDK invokes the callback function on each transition.

No identity
No identity
Identity is
successfully refreshed
Identity is...
No identity
No identity
init()
init()
Identity is valid,
no refresh is needed
Identity is valid,...
Identity is
successfully refreshed
Identity is...
No identity
No identity
Initialization
getAdvertisingToken() -> undefined
isLoginRequired() -> undefined

Initialization...
Identity Is Available
getAdvertisingToken() -> <valid>
isLoginRequired() -> false

Identity Is Available...
REFRESHED
REFRESHED
ESTABLISHED
ESTABLISHED
NO_IDENTITY
NO_IDENTITY
REFRESH_EXPIRED
REFRESH_EXPIRED
OPTOUT
OPTOUT
EXPIRED
EXPIRED
INVALID
INVALID
Identity Is Not Available
getAdvertisingToken() -> undefined
isLoginRequired() -> true

Identity Is Not Available...
Identity Is Temporarily Unavailable
getAdvertisingToken() -> undefined
isLoginRequired() -> false

Identity Is Temporarily Unavailable...
Identity has expired,
auto-refresh failed
Identity has expired,...
Viewer does not support full SVG 1.1

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 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.
  • An unsuccessful POST /token/refresh response due to the user's optout or the refresh token expiration suspends the background auto-refresh process and requires a new login (isLoginRequired() returns true). In all other cases, auto-refresh attempts will continue in the background.
  • The callback function specified during the SDK initialization is invoked under the following circustances:
    • After each successful refresh attempt.
    • After an initial failure to refresh an expired advertising token.
    • When identity has become invalid—for example, because the user has opted out.
      NOTE: The callback is not invoked when identify is temporarily unavailable and the auto-refresh keeps failing. In this case, the SDK continues using the existing advertising token.
  • A disconnect() call cancels the active timer.

API Reference

IMPORTANT: All interactions with the SDK for JavaScript are done through the global __euid object, which is a member of the EUID class. All of following APIs are members of the EUID class.

constructor()

Constructs a EUID object.

TIP: Instead of calling this function, you can just use the global __euid 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 by the corresponding script tag, typically during page loading.
  • Initialization calls require a callback function that is invoked after the SDK is initialized.
  • When creating an instance for the EUID lifecycle on the client, 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.
  • Since the SDK relies on first-party cookies to store the passed EUID identity information for the session, subsequent init() calls on different page loads may have the identity property empty.
  • To tune specific behaviors, initialization calls may include optional configuration parameters.

The following is a template of an init() call with the server-side generated identity included.

<script>
__euid.init({
callback : function (state) {...}, // Check advertising token and its status within the passed state and initiate targeted advertising.
identity : {...} // The `body` property value from the token/generate or token/refresh API response.
});
</script>

For example:

<script>
__euid.init({
callback : onEuidIdentityUpdated,
identity : {
"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 uses identity from a first-party cookie. You can put a block like this on any page that the user may visit after the identity has been established.

<script>
__euid.init({
callback : function (state) {...} // Check advertising token and its status within the passed state and initiate targeted advertising.
});
</script>

Parameters

The opts object supports the following properties.

PropertyData TypeAttributeDescriptionDefault Value
callbackfunction(object): voidRequiredThe function the SDK is to invoke after validating the passed identity. For details, see Callback Function.N/A
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, leave this property empty.N/A
baseUrlstringOptionalThe base URL of the EUID operator to use when invoking the POST /token/refresh endpoint.
For example: https://my.operator.fr.
https://prod.euid.eu
refreshRetryPeriodnumberOptionalThe number of seconds after which to retry refreshing tokens if intermittent errors occur.5
cookieDomainstringOptionalThe domain name string to apply to the EUID cookie.
For example, if the baseUrl is https://my.operator.fr, the cookieDomain value might be operator.fr.
undefined
cookiePathstringOptionalThe path string to apply to the EUID cookie./

Errors

The init() function can throw the following errors.

ErrorDescription
TypeErrorOne of the following issues has occurred:
- The fuction has already been called.
- The opts value is not an object.
- There is no callback function specified.
- The callback value is not a function.
RangeErrorThe refresh retry period is less than 1.

Callback Function

The function(object): void callback function indicates that the initialization is complete. Subsequently, the SDK invokes the callback when it successfully refreshes the established identity. For details on when the callback function is called, see Background Token Auto-Refresh.

The object parameter includes the following properties.

PropertyData TypeDescription
advertisingTokenstringThe token to be passed to SSPs for targeted advertising. If the token/identity is invalid or unavailable, the value is undefined.
statusEUID.IdentityStatus enumThe numeric value that indicates the status of the identity. For details, see Identity Status Values.
statusTextstringAdditional information pertaining to the identity status.

Identity Status Values

The callback function returns the status field values as numbers from the EUID.IdentityStatus enum, which can be turned into the corresponding strings by calling EUID.IdentityStatus[state.status]. The following table lists the string values for the status enum.

IMPORTANT: The following values are intended only to inform you of identity availability. Do not use them in conditional logic.

StatusAdvertising Token AvailabilityDescription
ESTABLISHEDAvailableThe identity is valid, was set from the passed value or the first-party cookie, and is now available for targeted advertising.
REFRESHEDAvailableThe identity was successfully refreshed by a call to the EUID operator is now available for targeted advertising.
EXPIREDNot availableNo identity is available for targeted advertising, as the SDK failed to refresh the token. Since there is still a valid refresh token available, auto-refresh attempts will continue.
REFRESH_EXPIREDNot availableNo identity is available for targeted advertising, as the refresh token on the first-party cookie or the passed identity has expired.
NO_IDENTITYNot availableNo identity is available for targeted advertising, as a first-party cookie was not set and no identity has been passed to the init() function.
INVALIDNot availableNo identity is available for targeted advertising, as the SDK failed to parse the first-party cookie or the passed identity.
OPTOUTNot availableNo identity is available for targeted advertising, as the user has opted out from refreshing identity.

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

getAdvertisingToken(): string

Gets the current advertising token.

Be sure to call this function after calling init() and invoking the supplied callback, for example:

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

The getAdvertisingToken() function allows you to get access to the advertising token from anywhere (not just from the initialization completion callback) and returns undefined in the following cases:

  • The callback function has not been called yet, which means the SDK initialization is not 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, to determine the best course of action, use the isLoginRequired() function.

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 and the callback function is invoked, 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().

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

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

TIP: You can use this function to be notified of the completion of the SDK for JavaScript initialization from a component that might not be the one that called init().

isLoginRequired(): boolean

Specifies whether an EUID POST /token/generate call is required.

The function can also provide additional context for handling missing identities, as shown in Workflow States and Transitions.

<script>
__euid.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 either of the following:
- The identity is present and valid.
- The identity has expired, and the token was not refreshed due to an intermittent error. The identity may be restored after a successful auto-refresh attempt.
undefinedThe SDK initialization is not complete yet.

disconnect(): void

Clears the EUID identity from the first-party cookie, thus closing the client's identity session and disconnecting the client lifecycle.

When an unauthenticated user is present, or a user wants to log out of targeted advertising on the publisher's site, make the following call:

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

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

abort(): void

Terminates any background timers or requests. The EUID 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 EUID object with a new instance. For example, single-page applications may want to use this to clear the current EUID object and construct or initialize a new one after receiving a new identity in the POST /token/generate response from the server.

The SDK uses first-party cookies to store users' identities.

Properties

The following table lists the cookie properties.

PropertiesDefault ValueComments
Name__euidN/A
ExpiryN/AThe value is the refresh token expiration timestamp as specified by the operator in the POST /token/generate or POST /token/refresh response.
Path/You can set a different path with the cookiePath init() parameter during the SDK initialization.
DomainundefinedYou can specify a different domain with the cookieDomain init() parameter during the SDK initialization.

Contents Structure

The EUID cookie contents are 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 EUID 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,
"private":{
}
}

IMPORTANT: The contents of the private object are explicitly unspecified and 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.