This example demonstrates how a content publisher who is working with Google Interactive Media Ads(IMA) SDKs can use Google Secure Signal and the UID2 SDK for JavaScript to share UID2 directly with bidders, in an implementation that uses this SDK.
For an example application without using the UID2 SDK, see Server-Side UID2 Integration Example.
NOTE: Although the server side of the example application is implemented in JavaScript using node.js, it is not a requirement. You can use any technology of your choice and refer to the example application for an illustration of the functionality that needs to be implemented.
The easiest way to try the example is to do the following:
- Open this repo in VS Code
- Create a
.envfile in this folder and populateUID2_API_KEYandUID2_CLIENT_SECRET:UID2_BASE_URL=http://localhost:8080 UID2_API_KEY=<your-integ-API-key> UID2_CLIENT_SECRET=<your-integ-client-secret> AD_TAG_URL=https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/extrernal/adx-test-tag&tfcd=0&npa=0&sz=640x480&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator= UID2_JS_SDK_URL=http://localhost:9091/uid2-sdk.js - Click the Run and Debug tab or hit
Crtl+Shift+D - Select
Launch Secure Signals (Chrome)from the configuration dropdown - Click
Start Debuggingor hit F5
The other way to try the example is to use the following Docker Build command. First, open this folder in your terminal, then run the following:
docker build . -t uid2-secure-signals-standard docker run -it --rm -p 3000:3000 ` -e UID2_BASE_URL="https://operator-integ.uidapi.com" ` -e UID2_API_KEY="<your-integ-API-key>" ` -e UID2_CLIENT_SECRET="<your-integ-client-secret>" ` -e AD_TAG_URL="https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/extrernal/adx-test-tag&tfcd=0&npa=0&sz=640x480&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=" ` -e UID2_JS_SDK_URL="<your-JS-SDK-URL>" ` uid2-secure-signals-standard The following table lists the environment variables that you must specify to start the application.
| Parameter | Data Type | Description |
|---|---|---|
UID2_BASE_URL | string | The base URL of the UID2 service. For example: Testing environment: https://integ.uidapi.comProduction environment: https://prod.uidapi.com |
UID2_API_KEY | string | Your UID2 authentication key for the UID2 service specified in UID2_BASE_URL. |
UID2_CLIENT_SECRET | string | Your UID2 client secret for the UID2 service specified in UID2_BASE_URL. |
AD_TAG_URL | string | The ad tag URL to test ad requests. |
UID2_JS_SDK_URL | string | The UID2 JS SDK. If this optional parameter it not provided, it will default to the integ URL specified in server.js |
Output similar to the following indicates that the example application is up and running.
> uid2-publisher@1.0.0 start /usr/src/app > node server.js Example app listening at http://localhost:3000 If needed, to close the application, terminate the Docker container or use the Ctrl+C keyboard shortcut.
The following table outlines and annotates the steps you can take to test and explore the example application.
| Step | Description | Comments |
|---|---|---|
| 1 | In your browser, navigate to the application main page at http://localhost:3000. | The displayed main (index) page of the example application provides a login form for the user to complete the UID2 login process. IMPORTANT: A real-life application must also display a form for the user to consent to targeted advertising. |
| 2 | In the text field at the bottom, enter the email address that you want to use for testing and click Log In. | The click calls the Secure Signal clearAllCache() function, to clear all cached signals from local storage, and then calls the /login endpoint (server.js). The login initiated on the server side then calls the POST /token/generate endpoint and processes the received response. |
| A confirmation message appears with the established UID2 identity information. | The displayed identity information is the body property of the JSON response payload from the POST /token/generate response. It has been passed to the loginview for rendering client-side JavaScript. Next, the identity information is passed to the UID2 SDK init() function. If the identity is valid, the SDK stores it either in local storage or a first-party UID2 cookie (see UID2 Storage Format for use on subsequent page loads. | |
| 3 | Click the Back to the main page link. | On the updated application main page, note the newly populated UID2 Advertising Token value and a video player. While the page view is loading, GPT auto-loads the Secure Signal UID2 script which pushes the advertising token to GPT local storage, and the IMA makes an ad request which transmits the encoded signal in the request. The page view calls the init() function again, but this time without passing an explicit identity. Instead, the identity is loaded from the first-party cookie. |
| 4 | Click Play. | This triggers AdsManager to insert the ad returned from the ad request, for display. The ad tag used in this example contains a 10-second pre-roll ad. |
| 5 | Keep the application main page open, or refresh it after a while, and note the UID2 identity state, updated counter, and login information values. | In the background, the UID2 SDK continuously validates whether the advertising token is up to date, and refreshes it automatically when needed. If the refresh succeeds, the user opts out, or the refresh token expires, the callback function is invoked, and the UI elements are updated with the current state of the UID2 identity. For details, see Workflow Overview and Background Token Auto-Refresh. |
| 6 | To exit the application, click Log Out. | This calls the UID2 SDK disconnect() function, which clears the UID2 session and the first-party cookie and calls the Secure Signal clearAllCache() function to clear all cached signals. This call also makes the UID2 SDK isLoginRequired() function return true, which presents the user with the login form again.NOTE: The page displays the Log Out button as long as the user identity is valid and refreshable. |
