Skip to main content

Server-Side Integration Guide for JavaScript

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

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

It includes the following sections:

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 authentication and data capture, how to manage EUID 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 EUID and retrieving advertising tokens, the web integration steps provided in this guide rely on the EUID 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 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 EUID SDK for JavaScript API Reference for your identity management.

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

Integration Steps

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

Publisher Flow

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

  1. Establish identity: capture user data
  2. Bid Using EUID Tokens
  3. Refresh Tokens
  4. Clear Identity: User Logout

Establish Identity: Capture User Data

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, an EUID 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 an EUID, use the POST /token/generate endpoint to generate an EUID token using the email address provided by the user. Make sure it is normalized.
1-ePOST /token/generateThe endpoint returns an EUID token generated from the user's hashed or unhashed email address.
1-fEUID SDK for JavaScriptThe SDK sends the returned EUID token from step 1-e to the SDK in the identity property of its init() function.
1-gEUID SDK for JavaScriptProvide the SDK a callback function that will receive identity updates from the SDK and use them to initiate targeted advertising.
  window.__euid = window.__euid || {};
window.__euid.callbacks = window.__euid.callbacks || [];

// Step 1-f
window.__euid.callbacks.push((eventType, payload) => {
if (eventType === 'SdkLoaded') {
__euid.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.__euid.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. Trigger a workflow for obtaining email address if you want to use EUID 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 EUID 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-aEUID SDK for JavaScriptGets the current user's advertising token by using the getAdvertisingToken() function as shown below.

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

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

NOTE: You need to consider how you pass the returned advertising token to SSPs. With some other approaches to client-side EUID implementation, such as using Prebid.js (see EUID Integration Overview for Prebid.js), the implementation includes functions that manage passing the returned advertising token. If you're using the EUID SDK for JavaScript you'll need to manage this yourself.

TIP: Instead of calling __euid.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-aEUID SDK for JavaScriptThe SDK automatically refreshes EUID tokens in the background. No manual action is required.
3-bEUID 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 EUID). 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-bEUID SDK for JavaScriptThe SDK clears the EUID identity from the first-party cookie and disconnects the client lifecycle by using the disconnect() function as shown below.
<script>
__euid.disconnect();
</script>

FAQs

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