Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 17 additions & 12 deletions docs/guides/integration-google-ss.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,8 @@ If you want to use Secure Signals with Prebid.js, you must complete both these a

For details, see [ESP Configurations](https://docs.prebid.org/dev-docs/modules/userId.html#esp-configurations) in the Prebid documentation.

A sample implementation for Prebid.js with Secure Signals is also available. For details, see [Sample Implementations](#sample-implementations).

## Integrating with Single Sign-On (SSO)

<SnptIntegratingWithSSO />
Expand Down Expand Up @@ -154,18 +156,21 @@ For details, see [Client-Side Integration Guide for JavaScript](integration-java

The following sample implementations are available to illustrate how to integrate with the Google Ad Manager secure signals feature:

- Server-side integration example using the UID2 JavaScript SDK with Google secure signals:
- [Sample implementation](https://secure-signals-server-side-integ.uidapi.com/)
- [Code repository](https://github.com/IABTechLab/uid2-web-integrations/tree/main/examples/google-secure-signals-integration/server_side)
- Client-server integration example using the UID2 JavaScript SDK with Google secure signals:
- [Sample implementation](https://secure-signals-client-server-integ.uidapi.com/)
- [Code repository](https://github.com/IABTechLab/uid2-web-integrations/tree/main/examples/google-secure-signals-integration/with_sdk_v3)
- Client-side integration example using the UID2 JavaScript SDK with Google secure signals:
- [Sample implementation](https://secure-signals-client-side-integ.uidapi.com/)
- [Code repository](https://github.com/IABTechLab/uid2-web-integrations/tree/main/examples/google-secure-signals-integration/client_side)
- Client-side integration example using React, the UID2 JavaScript SDK, and Google secure signals:
- [Sample implementation](https://secure-signals-react-integ.uidapi.com)
- [Code repository](https://github.com/IABTechLab/uid2-web-integrations/tree/main/examples/google-secure-signals-integration/react_client_side)
- Client-side integration example using the UID2 JavaScript SDK with Google Secure Signals:
- Site: [Client-Side UID2 Integration with Google Secure Signals](https://secure-signals-client-side.samples.uidapi.com/)
- Code: [uid2-examples/web-integrations/google-secure-signals/client-side](https://github.com/IABTechLab/uid2-examples/tree/main/web-integrations/google-secure-signals/client-side)
- Client-server integration example using the UID2 JavaScript SDK with Google Secure Signals:
- Site: [Client-Server UID2 SDK Integration Example with Google Secure Signals](https://secure-signals-client-server.samples.uidapi.com/)
- Code: [uid2-examples/web-integrations/google-secure-signals/client-server](https://github.com/IABTechLab/uid2-examples/tree/main/web-integrations/google-secure-signals/client-server)
- Server-side integration example using the UID2 JavaScript SDK with Google Secure Signals:
- Site: [Server-Side UID2 Integration with Google Secure Signals](https://secure-signals-server-side.samples.uidapi.com/)
- Code: [uid2-examples/web-integrations/google-secure-signals/server-side](https://github.com/IABTechLab/uid2-examples/tree/main/web-integrations/google-secure-signals/server-side)
- Client-side integration example using React, the UID2 JavaScript SDK, and Google Secure Signals:
- Site: [React Client-Side UID2 Integration with Google Secure Signals](https://secure-signals-react.samples.uidapi.com/)
- Code: [uid2-examples/web-integrations/google-secure-signals/react-client-side](https://github.com/IABTechLab/uid2-examples/tree/main/web-integrations/google-secure-signals/react-client-side)
- Client-side integration example using Prebid.js with Google Secure Signals:
- Site: [Client-Side UID2 Integration with Prebid.js (with Google Secure Signals)](https://prebid-secure-signals.samples.uidapi.com/)
- Code: [uid2-examples/web-integrations/prebid-secure-signals](https://github.com/IABTechLab/uid2-examples/tree/main/web-integrations/prebid-secure-signals)

Each sample implementation has its own instructions.

Expand Down
15 changes: 8 additions & 7 deletions docs/guides/integration-javascript-client-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,6 @@ If you prefer to integrate with UID2 via **only** client-side JavaScript changes

For technical details about the SDK, see [SDK for JavaScript Reference Guide](../sdks/sdk-ref-javascript.md).

## Sample Implementation

For a sample implementation, see the UID2 SDK Integration example:
- [Client-Server UID2 SDK Integration Example](https://example-jssdk-integ.uidapi.com/)
- [Code Repository with Readme](https://github.com/IABTechLab/uid2-web-integrations/tree/main/examples/js-sdk)

## 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 UID2 identity information and use it for targeted advertising, and how to refresh tokens, deal with missing identities, and handle user opt-outs.
Expand All @@ -36,7 +30,7 @@ For a workflow diagram, see [Integration Steps](#integration-steps). See also [F

For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md).

To facilitate the process of establishing client identity using UID2 and retrieving advertising tokens, the web integration steps provided in this guide rely on the SDK for JavaScript. Here's an [example application](https://example-jssdk-integ.uidapi.com/) 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 [UID2 SDK Integration Example](https://github.com/IABTechLab/uid2-web-integrations/tree/main/examples/js-sdk).
To facilitate the process of establishing client identity using UID2 and retrieving advertising tokens, the web integration steps provided in this guide rely on the SDK for JavaScript. For an example, see [Sample Implementation](#sample-implementation).

:::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 [SDK for JavaScript API Reference](../sdks/sdk-ref-javascript.md#api-reference) for your identity management.
Expand Down Expand Up @@ -175,6 +169,13 @@ The client lifecycle is complete when the user decides to log out from the publi
</script>
```

## Sample Implementation

A sample implementation is available for client-server integration using the UID2 SDK for JavaScript:

- Site: [Client-Server UID2 Integration Example using JavaScript SDK](https://js-client-server.samples.uidapi.com/)
- Code: [uid2-examples/web-integrations/javascript-sdk/client-server](https://github.com/IABTechLab/uid2-examples/tree/main/web-integrations/javascript-sdk/client-server)

## FAQs

For a list of frequently asked questions for the publisher audience, see [FAQs for Publishers](../getting-started/gs-faqs.md#faqs-for-publishers).
15 changes: 7 additions & 8 deletions docs/guides/integration-javascript-client-side.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,14 +57,6 @@ If you want to use a debug build of the SDK, use the following URL instead:

- [https://cdn.integ.uidapi.com/uid2-sdk-4.0.1.js](https://cdn.integ.uidapi.com/uid2-sdk-4.0.1.js)

## Sample Implementation

For a sample implementation, see this example:
- Code: [Example Client-Side Integration for JavaScript](https://github.com/IABTechLab/uid2-web-integrations/tree/main/examples/cstg)
- Running site: [Client-Side Integration Example, UID2 JavaScript SDK](https://cstg-integ.uidapi.com/)

<!-- (Source code for running site: https://github.com/IABTechLab/uid2-web-integrations) -->

## Integrating with Single Sign-On (SSO)

<SnptIntegratingWithSSO />
Expand Down Expand Up @@ -407,3 +399,10 @@ function bytesToBase64(bytes) {
return btoa(binString);
}
```

## Sample Implementation

A sample implementation is available for client-side integration using the UID2 SDK for JavaScript:

- Site: [Client-Side UID2 Integration Example using JavaScript SDK](https://js-client-side.samples.uidapi.com/)
- Code: [uid2-examples/web-integrations/javascript-sdk/client-side](https://github.com/IABTechLab/uid2-examples/tree/main/web-integrations/javascript-sdk/client-side)
12 changes: 8 additions & 4 deletions docs/guides/integration-prebid-client-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,10 +36,6 @@ Information about how to integrate Prebid with UID2 is also in the following loc
- On the Prebid site, on the [Unified ID 2.0](https://docs.prebid.org/dev-docs/modules/userid-submodules/unified2.html) page for the Prebid User ID submodule.
- In the Prebid GitHub repository, on the [UID2 User ID Submodule](https://github.com/prebid/Prebid.js/blob/master/modules/uid2IdSystem.md) page.

<!-- ## Integration Example

GWH note 12/14/23 updated 2/7/25: we have a client-side example for Prebid.js but no client-server example. -->

## Integrating with Single Sign-On (SSO)

<SnptIntegratingWithSSO />
Expand Down Expand Up @@ -394,3 +390,11 @@ if you're using Prebid.js, and you're planning to pass UID2 tokens to Google usi

- In your Google Ad Manager account, make sure that encrypted signals are properly shared with third-party bidders: see [Allow Secure Signals Sharing](integration-google-ss.md#allow-secure-signals-sharing).
- Update your Prebid.js configuration: see [Optional: Enable Secure Signals in Prebid.js](integration-google-ss.md#optional-enable-secure-signals-in-prebidjs).

## Sample Implementation

The following sample implementation is available to illustrate how to integrate UID2 with Prebid.js using client-server integration:

- Client-server integration example using Prebid.js:
- Site: [Client-Server UID2 Integration with Prebid.js](https://prebid-client-server.samples.uidapi.com/)
- Code: [uid2-examples/web-integrations/prebid-integrations/client-server](https://github.com/IABTechLab/uid2-examples/tree/main/web-integrations/prebid-integrations/client-server)
65 changes: 58 additions & 7 deletions docs/guides/integration-prebid-client-side.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,13 +27,6 @@ This implementation requires Prebid.js version 8.21.0 or later. For version info

If you need to use an earlier version of Prebid.js, use the implementation solution presented in the [UID2 Client-Server Integration Guide for Prebid.js](integration-prebid-client-server.md) instead.

## Integration Example

An example of the UID2 Prebid.js client-side integration is available at the following links:

- Code: [Example Prebid.js UID2 Integration](https://github.com/IABTechLab/uid2docs/tree/main/static/examples/cstg-prebid-example)
- Running site: [UID2 Prebid.js Client-Side Integration Example](https://unifiedid.com/examples/cstg-prebid-example/)

## Integrating with Single Sign-On (SSO)

<SnptIntegratingWithSSO />
Expand Down Expand Up @@ -205,9 +198,67 @@ pbjs.setConfig({
});
```

## Optional: Deferred Client-Side UID2 Configuration with mergeConfig

If you already have Prebid.js configured but didn't include UID2 in the initial setup, you can still add the UID2 module using two functions provided by Prebid.js:

- [mergeConfig()](https://docs.prebid.org/dev-docs/publisher-api-reference/mergeConfig.html): Merges new configuration into the existing Prebid config without overwriting other settings. Use this to add the UID2 module to your existing `userSync.userIds` array.
- [refreshUserIds()](https://docs.prebid.org/dev-docs/publisher-api-reference/refreshUserIds.html): Reruns the user ID submodules to fetch the latest IDs. Call this after `mergeConfig()` to trigger UID2 token generation.

You still pass the same configuration information as described above (API base URL, credentials, and DII) so that Prebid can handle the entire UID2 token lifecycle:

```js
// Step 1: Define the UID2 configuration
const uidConfig = {
userSync: {
userIds: [{
name: 'uid2',
params: {
uid2ApiBase: 'https://operator-integ.uidapi.com',
email: '[email protected]',
subscriptionId: subscriptionId,
serverPublicKey: publicKey
}
}]
}
};

// Step 2: Merge UID2 config into existing Prebid config (additive, won't overwrite)
pbjs.mergeConfig(uidConfig);

// Step 3: Trigger user ID refresh to generate the token
await pbjs.refreshUserIds({ submoduleNames: ['uid2'] });
```

:::note
Once you add UID2 to your configuration, Prebid does not provide functionality to remove individual submodules without overwriting the entire `userIds` array. For client-side integrations where Prebid has access to the UID2 token in localStorage, it is important to clear localStorage where the token is stored after the user logs out and reload the page to clear caches. This prevents future bid requests from using the identity.

If you are managing the UID2 SDK separately, use `window.__uid2.disconnect()` which handles all logout functionality&#8212;clearing both memory and storage&#8212;without requiring a page refresh.
:::

A sample implementation for deferred configuration is also available. For details, see [Sample Implementations](#sample-implementations).

## Optional: Prebid.js Integration with Google Secure Signals

if you're using Prebid.js, and you're planning to pass UID2 tokens to Google using Google Secure Signals, there are a couple of additional configuration steps:

- In your Google Ad Manager account, make sure that encrypted signals are properly shared with third-party bidders: see [Allow Secure Signals Sharing](integration-google-ss.md#allow-secure-signals-sharing).
- Update your Prebid.js configuration: see [Optional: Enable Secure Signals in Prebid.js](integration-google-ss.md#optional-enable-secure-signals-in-prebidjs).

A sample implementation for Prebid.js with Secure Signals is also available. For details, see [Sample Implementations](#sample-implementations).

## Sample Implementations

The following sample implementations are available to illustrate how to integrate UID2 with Prebid.js on the client side:

- Client-side integration example using Prebid.js:
- Site: [Client-Side UID2 Integration with Prebid.js](https://prebid-client.samples.uidapi.com/)
- Code: [uid2-examples/web-integrations/prebid-integrations/client-side](https://github.com/IABTechLab/uid2-examples/tree/main/web-integrations/prebid-integrations/client-side)
- Deferred client-side integration example using Prebid.js:
- Site: [Deferred Client-Side UID2 Integration with Prebid.js](https://prebid-deferred.samples.uidapi.com/)
- Code: [uid2-examples/web-integrations/prebid-integrations/client-side-deferred](https://github.com/IABTechLab/uid2-examples/tree/main/web-integrations/prebid-integrations/client-side-deferred)
- Client-side integration example using Prebid.js with Google Secure Signals:
- Site: [Client-Side UID2 Integration with Prebid.js (with Google Secure Signals)](https://prebid-secure-signals.samples.uidapi.com/)
- Code: [uid2-examples/web-integrations/prebid-secure-signals](https://github.com/IABTechLab/uid2-examples/tree/main/web-integrations/prebid-secure-signals)

Each sample implementation has its own instructions.
6 changes: 3 additions & 3 deletions docs/guides/integration-publisher-server-side.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,10 +131,10 @@ If the user logs out, do not use the UID2 token.

## Sample Implementation

A sample implementation is available for server-side integration. See:
A sample implementation is available for server-side integration:

- [Server-Only UID2 Integration Example](https://example-srvonly-integ.uidapi.com/login)
- [Server-Only UID2 Integration Example (readme)](https://github.com/IABTechLab/uid2-examples/blob/main/publisher/server_only/README.md)
- Site: [Server-Side UID2 Integration Example](https://server-side.samples.uidapi.com/)
- Code: [uid2-examples/web-integrations/server-side](https://github.com/IABTechLab/uid2-examples/tree/main/web-integrations/server-side)

## FAQs

Expand Down
Loading
Loading