Skip to content

Latest commit

 

History

History
94 lines (64 loc) · 7.55 KB

publisher-client-side.md

File metadata and controls

94 lines (64 loc) · 7.55 KB
Raw

UID2 API Documentation > v1 > Integration Guides > Publisher Integration Guide

Overview

This guide covers integration steps for publishers with web assets who would like to generate identity tokens utilizing UID2 for the bid stream. This guide focuses on publishers who would like to integrate directly with UID2 to create and manage tokens rather than integrate with UID2-enabled single-sign-on or identity providers.

Integration Steps

The following integration steps outline the lifecycle for a user establishing a UID2 token with a publisher and how the UID2 token integrates with the RTB bid stream.

Publisher Flow

1. Establish Identity

This section focuses on publisher-specific steps 1-d, 1-e, and 1-f illustrated in the above diagram.

Note
The UID2 token must only be generated on the server side after authentication. Security concerns forbid token generation on the browser side.

Step Endpoint/SDK Instruction
d GET /token/generate There are two ways for publishers to establish identity with UID2.
1. Integrate with a UID2-enabled single-sign-on provider.
2. Generate UID2 tokens when a user authenticates using the GET /token/generate endpoint. The request includes a user's normalized email address.
e GET /token/generate The token generation service returns UID2 tokens.
f UID2 client-side identity SDK Send returned UID2 tokens from step e to the SDK using identity mechanism below. The mechanism ensures UID2 tokens are available for the user until they logout.

Client-Side SDK Identity Mechanism

<script>
  __uid2.init({
    identity : <Response from the generate token api>
  });
</script>

2. Bid Using UID2 Tokens

This section focuses on publisher-specific step 2-a illustrated in the above diagram.

Step Endpoint/SDK Instruction
a UID2 client-side identity SDK The established identity is available client-side for bidding. The mechnanism below returns access to a user's advertising_token to pass to SSPs.

Client-Side SDK Identity Access Mechanism

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

3. Refresh Tokens

Step Endpoint/SDK Instruction
a UID2 client-side identity SDK The SDK automatically refreshes UID2 tokens. No manual action is required.
b UID2 client-side identity SDK If a user hasn't opted out, the refresh token returns new identity tokens.

If you decide to integrate using options other than the SDK, we recommend refreshing identity tokens every 5 minutes.

4. User Logout

Step Endpoint/SDK Instruction
a The user logs out from a publisher asset.
b UID2 client-side identity SDK Remove UID2 tokens from the user's local storage when they log out. Use the disconnect mechanism from the SDK to clear out UID2 tokens.

Client-Side SDK Disconnect Identity

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

Frequently Asked Questions

How will I be notified of user opt-out?

The token refresh process handles user opt-outs. If a user opts out, using their refresh token automatically clears their session. UID2 client-side SDK. No manual action is required.

How can I test my integration?

There are two built-in tools you can use to test your integration.

Test that PII sent and returned tokens match

You can use the GET /token/validate endpoint to check whether the PII you are sending through GET /token/generate is valid.

  1. Send a GET /token/generate request using [email protected] as email, or create a base64-encoded SHA256 hash of [email protected] and send it through as an email hash. Store the advertising_token returned to use in step 2.
  2. Send a GET /token/validate request using the email or email_hash you sent in step 1 and the token as the advertising_token returned in step 1. If the response returns true, the email or email_hash you sent as a request in step 1 match the token you received in the response of step 1. If it returns false, there may be an issue with the way you are sending email addresses or email hashes.

Test refresh token logout workflow

You can use the email address [email protected] to test your token refresh workflow. Using this email for the request always generates an identity response with a refresh_token that results in a logout response.

  1. Send a GET /token/generate request using [email protected] as email, or create a base64-encoded SHA256 hash of [email protected] and send it through as an email hash. Store the refresh_token returned to use in step 2.
  2. Send a GET /token/validate request using the email or email_hash you sent in step 1 and the refresh_token as the refresh_token returned in step 1. The body response should be empty because the [email protected] email always results in a logged out refresh token.