From 18868449c70911133455a42b78acd9e439b5f10a Mon Sep 17 00:00:00 2001 From: Matt Collins Date: Mon, 12 Feb 2024 15:16:21 +1100 Subject: [PATCH 1/8] Update UID2 User ID submodule documentation - Link to guides on unifiedid.com - Replace references to "CSTG" with "client-side integration" - Split up params based on integration type - Link to unifiedid.com for normalization and encoding --- modules/uid2IdSystem.md | 274 +++++++--------------------------------- 1 file changed, 47 insertions(+), 227 deletions(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index e546f6eafe1..f204ae2f1c5 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -1,264 +1,84 @@ -## UID2 User ID Submodule +# UID2 User ID Submodule -The UID2 module handles storing, providing, and optionally refreshing tokens. While initial tokens traditionally required server-side generation, the introduction of the *Client-Side Token Generation (CSTG)* mode offers publishers the flexibility to generate UID2 tokens directly from the module, eliminating this need. Publishers can choose to operate the module in one of three distinct modes: *Client Refresh* mode, *Server Only* mode and *Client-Side Token Generation* mode. +## Overview -*Server Only* mode was originally referred to as *legacy mode*, but it is a popular mode for new integrations where publishers prefer to handle token refresh server-side. - -*Client-Side Token Generation* mode is included in UID2 module by default. However, it's important to note that this mode is created and made available recently. For publishers who do not intend to use it, you have the option to instruct the build to exclude the code related to this feature: - -``` - $ gulp build --modules=uid2IdSystem --disable UID2_CSTG -``` -If you do plan to use Client-Side Token Generation (CSTG) mode, please consult the UID2 Team first as they will provide required configuration values for you to use (see the Client-Side Token Generation (CSTG) mode section below for details) +The UID2 module handles storing, providing, and optionally generating and refreshing tokens. For more details, see the [UID2 Integration Overview for Prebid.js](https://unifiedid.com/docs/guides/integration-prebid). **Important information:** UID2 is not designed to be used where GDPR applies. The module checks the passed-in consent data and will not operate if the `gdprApplies` flag is true. -## Client-Side Token Generation (CSTG) mode - -**This mode is created and made available recently. Please consult UID2 Team first as they will provide required configuration values for you to use.** - -For publishers seeking a purely client-side integration without the complexities of server-side involvement, the CSTG mode is highly recommended. This mode requires the provision of a public key, subscription ID and [directly identifying information (DII)](https://unifiedid.com/docs/ref-info/glossary-uid#gl-dii) - either emails or phone numbers. In the CSTG mode, the module takes on the responsibility of encrypting the DII, generating the UID2 token, and handling token refreshes when necessary. - -To configure the module to use this mode, you must: -1. Set `parmas.serverPublicKey` and `params.subscriptionId` (please reach out to the UID2 team to obtain these values) -2. Provide **ONLY ONE DII** by setting **ONLY ONE** of `params.email`/`params.phone`/`params.emailHash`/`params.phoneHash` - -Below is a table that provides guidance on when to use each directly identifying information (DII) parameter, along with information on whether normalization and hashing are required by the publisher for each parameter. - -| DII param | When to use it | Normalization required by publisher? | Hashing required by publisher? | -|------------------|-------------------------------------------------------|--------------------------------------|--------------------------------| -| params.email | When you have users' email address | No | No | -| params.phone | When you have user's phone number | Yes | No | -| params.emailHash | When you have user's hashed, normalized email address | Yes | Yes | -| params.phoneHash | When you have user's hashed, normalized phone number | Yes | Yes | - - -*Note that setting params.email will normalize email addresses, but params.phone requires phone numbers to be normalized.* - -Refer to [Normalization and Encoding](#normalization-and-encoding) for details on email address normalization, SHA-256 hashing and Base64 encoding. - -### CSTG example - -Configuration: -``` -pbjs.setConfig({ - userSync: { - userIds: [{ - name: 'uid2', - params: { - serverPublicKey: '...server public key...', - subscriptionId: '...subcription id...', - email: 'user@email.com', - //phone: '+0000000', - //emailHash: '...email hash...', - //phoneHash: '...phone hash ...' - } - }] - } -}); -``` - -## Client Refresh mode - -This is the recommended mode for most scenarios. In this mode, the full response body from the UID2 Token Generate or Token Refresh endpoint must be provided to the module. As long as the refresh token remains valid, the module will refresh the advertising token as needed. - -To configure the module to use this mode, you must **either**: -1. Set `params.uid2Cookie` to the name of the cookie which contains the response body as a JSON string, **or** -2. Set `params.uid2Token` to the response body as a JavaScript object. - -The `uid2Cookie` param was originally `uid2ServerCookie`. The old name can still be used, however the inclusion of the word 'server' was causing some confusion. If both values are provided, `uid2ServerCookie` will be ignored. - -### Client refresh cookie example - -In this example, the cookie is called `uid2_pub_cookie`. - -Cookie: -``` -uid2_pub_cookie={"advertising_token":"...advertising token...","refresh_token":"...refresh token...","identity_expires":1684741472161,"refresh_from":1684741425653,"refresh_expires":1684784643668,"refresh_response_key":"...response key..."} -``` - -Configuration: -``` -pbjs.setConfig({ - userSync: { - userIds: [{ - name: 'uid2', - params: { - uid2Cookie: 'uid2_pub_cookie' - } - }] - } -}); -``` - -### Client refresh uid2Token example - -Configuration: -``` -pbjs.setConfig({ - userSync: { - userIds: [{ - name: 'uid2', - params: { - uid2Token: { - 'advertising_token': '...advertising token...', - 'refresh_token': '...refresh token...', - // etc. - see the Sample Token below for contents of this object - } - } - }] - } -}); -``` - -## Server-Only Mode +Depending on access to DII, there are two methods to generate UID2 tokens for use with Prebid.js, as shown in the following table. -In this mode, only the advertising token is provided to the module. The module will not be able to refresh the token. The publisher is responsible for implementing some other way to refresh the token. +Determine which method is best for you, and then follow the applicable integration guide. -To configure the module to use this mode, you must **either**: -1. Set a cookie named `__uid2_advertising_token` to the advertising token, **or** -2. Set `value` to an ID block containing the advertising token (see "Server only value" example below). - -### Server only cookie example - -Cookie: -``` -__uid2_advertising_token=...advertising token... -``` - -Configuration: -``` -pbjs.setConfig({ - userSync: { - userIds: [{ - name: 'uid2' - }] - } -}); -``` - -### Server only value example - -Configuration: -``` -pbjs.setConfig({ - userSync: { - userIds: [{ - name: 'uid2' - value: { - 'uid2': { - 'id': '...advertising token...' - } - } - }] - } -}); -``` +| Scenario | Integration Guide | +| :--- | :--- | +| You have access to DII on the client side and want to do front-end development only. | [UID2 Client-Side Integration Guide for Prebid.js](https://unifiedid.com/docs/guides/integration-prebid-client-side). | +| You have access to DII on the server side and can do server-side development. | [UID2 Server-Side Integration Guide for Prebid.js](https://unifiedid.com/docs/guides/integration-prebid-server-side). | ## Storage The module stores a number of internal values. By default, all values are stored in HTML5 local storage. You can switch to cookie storage by setting `params.storage` to `cookie`. The cookie size can be significant and this is not recommended, but is provided as an option if local storage is not an option. -## Sample token - -`{`
  `"advertising_token": "...",`
  `"refresh_token": "...",`
  `"identity_expires": 1633643601000,`
  `"refresh_from": 1633643001000,`
  `"refresh_expires": 1636322000000,`
  `"refresh_response_key": "wR5t6HKMfJ2r4J7fEGX9Gw=="`
`}` - -### Notes - -If you are trying to limit the size of cookies, provide the token in configuration and use the default option of local storage. - -If you provide an expired identity and the module has a valid identity which was refreshed from the identity you provide, it will use the refreshed identity. The module stores the original token used for refreshing the token, and it will use the refreshed tokens as long as the original token matches the one supplied. - -If a new token is supplied which does not match the original token used to generate any refreshed tokens, all stored tokens will be discarded and the new token used instead (refreshed if necessary). - -You can set `params.uid2ApiBase` to `"https://operator-integ.uidapi.com"` during integration testing. Be aware that you must use the same environment (production or integration) here as you use for generating tokens. - ## Parameter Descriptions for the `usersync` Configuration Section -The below parameters apply only to the UID2 User ID Module integration. +The following parameters apply only to the UID2 User ID Module integration. | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | -| name | Required | String | ID value for the UID2 module - `"uid2"` | `"uid2"` | -| value | Optional, Server only | Object | An object containing the value for the advertising token. | See the example above. | -| params.uid2Token | Optional, Client refresh | Object | The initial UID2 token. This should be `body` element of the decrypted response from a call to the `/token/generate` or `/token/refresh` endpoint. | See the sample token above. | -| params.uid2Cookie | Optional, Client refresh | String | The name of a cookie which holds the initial UID2 token, set by the server. The cookie should contain JSON in the same format as the uid2Token param. **If uid2Token is supplied, this param is ignored.** | See the sample token above. | -| params.uid2ApiBase | Optional, Client refresh | String | Overrides the default UID2 API endpoint. | `"https://prod.uidapi.com"` _(default)_| -| params.storage | Optional, Client refresh | String | Specify whether to use `cookie` or `localStorage` for module-internal storage. It is recommended to not provide this and allow the module to use the default. | `localStorage` _(default)_ | -| params.serverPublicKey | Optional, Client-side token generation | String | A public key for encrypting the DII payload for the Operator's CSTG endpoint. **This is required for client-side token generation.** | - | -| params.subscriptionId | Optional, Client-side token generation | String | A publisher Identifier. **This is required for client-side token generation.** | - | -| params.email | Optional, Client-side token generation | String | The user's email address. Provide this parameter if using email as the DII. | `"test@example.com"` | -| params.emailHash | Optional, Client-side token generation | String | A hashed, normalized representation of the user's email. Provide this parameter if using emailHash as the DII. | `"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="` | -| params.phone | Optional, Client-side token generation | String | The user's phone number. Provide this parameter if using phone as the DII. | `"+15555555555"` | -| params.phoneHash | Optional, Client-side token generation | String | A hashed, normalized representation of the user's phone number. Provide this parameter if using phoneHash as the DII. | `"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="` | - -# Normalization and Encoding - -This section provides information about normalizing and encoding [directly Identifying information (DII)](https://unifiedid.com/docs/ref-info/glossary-uid#gl-dii). It's important that, in working with UID2, normalizing and encoding are performed correctly. +| name | Required | String | ID value for the UID2 module. Must be `"uid2"`. | `"uid2"` | +| params.uid2ApiBase | Optional | String | Overrides the default UID2 API endpoint. | `"https://prod.uidapi.com"` _(default)_| +| params.storage | Optional | String | Specify whether to use `cookie` or `localStorage` for module-internal storage. It is recommended to not provide this and allow the module to use the default. | `localStorage` _(default)_ | -## Introduction -When you're taking user information such as an email address, and following the steps to create a raw UID2 and/or a UID2 advertising token, it's very important that you follow all the required steps. Whether you normalize the information or not, whether you hash it or not, follow the steps exactly. By doing so, you can ensure that the UID2 value you create can be securely and anonymously matched up with other instances of online behavior by the same user. +### Client-side Integration ->Note: Raw UID2s, and their associated UID2 tokens, are case sensitive. When working with UID2, it's important to pass all IDs and tokens without changing the case. Mismatched IDs can cause ID parsing or token decryption errors. +The following parameters apply to the UID2 User ID Module if you are following the client-side integration guide. Exactly one of params.email, params.emailHash, params.phone, and params.phoneHash must be provided. -## Types of Directly Identifying Information -UID2 supports the following types of directly identifying information (DII): -- Email address -- Phone number - -## Email Address Normalization - -If you send unhashed email addresses to the UID2 Operator Service, the service normalizes the email addresses and then hashes them. If you want to hash the email addresses yourself before sending them, you must normalize them before you hash them. +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| params.serverPublicKey | Required for client-side integration | String | A public key for encrypting the DII payload for the Operator's CSTG endpoint. | - | +| params.subscriptionId | Required for client-side integration | String | A publisher identifier. | - | +| params.email | Optional | String | The user's email address. Provide this parameter if using email as the DII. | `"test@example.com"` | +| params.emailHash | Optional | String | A hashed, normalized representation of the user's email. Provide this parameter if using emailHash as the DII. | `"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="` | +| params.phone | Optional | String | The user's phone number. Provide this parameter if using phone as the DII. | `"+15555555555"` | +| params.phoneHash | Optional | String | A hashed, normalized representation of the user's phone number. Provide this parameter if using phoneHash as the DII. | `"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="` | -> IMPORTANT: Normalizing before hashing ensures that the generated UID2 value will always be the same, so that the data can be matched. If you do not normalize before hashing, this might result in a different UID2, reducing the effectiveness of targeted advertising. +### Server-side Integration -To normalize an email address, complete the following steps: +#### Server-only Mode -1. Remove leading and trailing spaces. -2. Convert all ASCII characters to lowercase. -3. In `gmail.com` email addresses, remove the following characters from the username part of the email address: - 1. The period (`.` (ASCII code 46)).
For example, normalize `jane.doe@gmail.com` to `janedoe@gmail.com`. - 2. The plus sign (`+` (ASCII code 43)) and all subsequent characters.
For example, normalize `janedoe+home@gmail.com` to `janedoe@gmail.com`. +The following parameters apply to the UID2 User ID Module if you are following the server-side integration guide with server-only mode. -## Email Address Hash Encoding +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| value | Required for server-only mode | Object | An object containing the value for the advertising token. | See the example below. | -An email hash is a Base64-encoded SHA-256 hash of a normalized email address. The email address is first normalized, then hashed using the SHA-256 hashing algorithm, and then the resulting bytes of the hash value are encoded using Base64 encoding. Note that the bytes of the hash value are encoded, not the hex-encoded string representation. +#### Client Refresh Mode -| Type | Example | Comments and Usage | -| :--- | :--- | :--- | -| Normalized email address | `user@example.com` | Normalization is always the first step. | -| SHA-256 hash of normalized email address | `b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514` | This 64-character string is a hex-encoded representation of the 32-byte SHA-256.| -| Hex to Base64 SHA-256 encoding of normalized email address | `tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=` | This 44-character string is a Base64-encoded representation of the 32-byte SHA-256.
WARNING: The SHA-256 hash string in the example above is a hex-encoded representation of the hash value. You must Base64-encode the raw bytes of the hash or use a Base64 encoder that takes a hex-encoded value as input.
Use this encoding for `email_hash` values sent in the request body. | +The following parameters apply to the UID2 User ID Module if you are following the server-side integration guide with client refresh mode. Either params.uid2Token or params.uid2Cookie must be provided. ->WARNING: When applying Base64 encoding, be sure to Base64-encode the raw bytes of the hash or use a Base64 encoder that takes a hex-encoded value as input. +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| params.uid2Token | Optional | Object | The initial UID2 token. This should be `body` element of the decrypted response from a call to the `/token/generate` or `/token/refresh` endpoint. | See the sample token below. | +| params.uid2Cookie | Optional | String | The name of a cookie which holds the initial UID2 token, set by the server. The cookie should contain JSON in the same format as the uid2Token param. **If uid2Token is supplied, this param is ignored.** | See the sample token below. | -## Phone Number Normalization +## Sample token -If you send unhashed phone numbers to the UID2 Operator Service, the service normalizes the phone numbers and then hashes them. If you want to hash the phone numbers yourself before sending them, you must normalize them before you hash them. +`{`
  `"advertising_token": "...",`
  `"refresh_token": "...",`
  `"identity_expires": 1633643601000,`
  `"refresh_from": 1633643001000,`
  `"refresh_expires": 1636322000000,`
  `"refresh_response_key": "wR5t6HKMfJ2r4J7fEGX9Gw=="`
`}` -> IMPORTANT: Normalization before hashing ensures that the generated UID2 value will always be the same, so that the data can be matched. If you do not normalize before hashing, this might result in a different UID2, reducing the effectiveness of targeted advertising. +## Normalization and Encoding -Here's what you need to know about phone number normalization rules: +Refer to [Normalization and Encoding](https://unifiedid.com/docs/getting-started/gs-normalization-encoding). -- The UID2 Operator accepts phone numbers in the [E.164](https://en.wikipedia.org/wiki/E.164) format, which is the international phone number format that ensures global uniqueness. -- E.164 phone numbers can have a maximum of 15 digits. -- Normalized E.164 phone numbers use the following syntax, with no spaces, hyphens, parentheses, or other special characters:
- `[+] [country code] [subscriber number including area code]` - Examples: - - US: `1 (123) 456-7890` is normalized to `+11234567890`. - - Singapore: `65 1243 5678` is normalized to `+6512345678`. - - Sydney, Australia: `(02) 1234 5678` is normalized to drop the leading zero for the city plus include the country code: `+61212345678`. +## Notes -## Phone Number Hash Encoding +- If you provide an expired identity and the module has a valid identity which was refreshed from the identity you provide, it will use the refreshed identity. The module stores the original token used for refreshing the token, and it will use the refreshed tokens as long as the original token matches the one supplied. -A phone number hash is a Base64-encoded SHA-256 hash of a normalized phone number. The phone number is first normalized, then hashed using the SHA-256 hashing algorithm, and the resulting hex value is encoded using Base64 encoding. +- If a new token is supplied which does not match the original token used to generate any refreshed tokens, all stored tokens will be discarded and the new token used instead (refreshed if necessary). -The example below shows a simple input phone number, and the result as each step is applied to arrive at a secure, opaque, URL-safe value. +- You can set `params.uid2ApiBase` to `"https://operator-integ.uidapi.com"` during integration testing. Be aware that you must use the same environment (production or integration) here as you use for generating tokens. -| Type | Example | Comments and Usage | -| :--- | :--- | :--- | -| Normalized phone number | `+12345678901` | Normalization is always the first step. | -| SHA-256 hash of normalized phone number | `10e6f0b47054a83359477dcb35231db6de5c69fb1816e1a6b98e192de9e5b9ee` |This 64-character string is a hex-encoded representation of the 32-byte SHA-256. | -| Hex to Base64 SHA-256 encoding of normalized and hashed phone number | `EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=` | This 44-character string is a Base64-encoded representation of the 32-byte SHA-256.
NOTE: The SHA-256 hash is a hexadecimal value. You must use a Base64 encoder that takes a hex value as input. Use this encoding for `phone_hash` values sent in the request body. | +- If you are building Prebid.js and following the server-side integration guide, you can create a smaller Prebid.js build by disabling client-side integration functionality. To do this, pass the `--disable UID2_CSTG` flag: ->WARNING: When applying Base64 encoding, be sure to use a function that takes a hex value as input. If you use a function that takes text as input, the result is a longer string which is invalid for the purposes of UID2. +``` + $ gulp build --modules=uid2IdSystem --disable UID2_CSTG +``` \ No newline at end of file From 3d91f81851bed111859e3400e7dfde03ff7a6c90 Mon Sep 17 00:00:00 2001 From: Matt Collins Date: Tue, 13 Feb 2024 15:00:30 +1100 Subject: [PATCH 2/8] Address UID2 documentation feedback --- modules/uid2IdSystem.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index f204ae2f1c5..e9d6b438535 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -2,9 +2,9 @@ ## Overview -The UID2 module handles storing, providing, and optionally generating and refreshing tokens. For more details, see the [UID2 Integration Overview for Prebid.js](https://unifiedid.com/docs/guides/integration-prebid). +The UID2 module handles storing, providing, and optionally generating and refreshing tokens. For more details, see [UID2 Integration Overview for Prebid.js](https://unifiedid.com/docs/guides/integration-prebid). -**Important information:** UID2 is not designed to be used where GDPR applies. The module checks the passed-in consent data and will not operate if the `gdprApplies` flag is true. +**Important information:** UID2 is not designed to be used where GDPR applies. The module checks the passed-in consent data and does not operate if the `gdprApplies` flag is true. Depending on access to DII, there are two methods to generate UID2 tokens for use with Prebid.js, as shown in the following table. @@ -29,28 +29,28 @@ The following parameters apply only to the UID2 User ID Module integration. | params.uid2ApiBase | Optional | String | Overrides the default UID2 API endpoint. | `"https://prod.uidapi.com"` _(default)_| | params.storage | Optional | String | Specify whether to use `cookie` or `localStorage` for module-internal storage. It is recommended to not provide this and allow the module to use the default. | `localStorage` _(default)_ | -### Client-side Integration +### Client-Side Integration The following parameters apply to the UID2 User ID Module if you are following the client-side integration guide. Exactly one of params.email, params.emailHash, params.phone, and params.phoneHash must be provided. | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | -| params.serverPublicKey | Required for client-side integration | String | A public key for encrypting the DII payload for the Operator's CSTG endpoint. | - | -| params.subscriptionId | Required for client-side integration | String | A publisher identifier. | - | +| params.serverPublicKey | Required for client-side integration | String | See [Subscription ID and Public Key](https://unifiedid.com/docs/getting-started/gs-credentials#subscription-id-and-public-key). | - | +| params.subscriptionId | Required for client-side integration | String | See [Subscription ID and Public Key](https://unifiedid.com/docs/getting-started/gs-credentials#subscription-id-and-public-key). | - | | params.email | Optional | String | The user's email address. Provide this parameter if using email as the DII. | `"test@example.com"` | | params.emailHash | Optional | String | A hashed, normalized representation of the user's email. Provide this parameter if using emailHash as the DII. | `"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="` | | params.phone | Optional | String | The user's phone number. Provide this parameter if using phone as the DII. | `"+15555555555"` | | params.phoneHash | Optional | String | A hashed, normalized representation of the user's phone number. Provide this parameter if using phoneHash as the DII. | `"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="` | -### Server-side Integration +### Server-Side Integration -#### Server-only Mode +#### Server-Only Mode The following parameters apply to the UID2 User ID Module if you are following the server-side integration guide with server-only mode. | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | -| value | Required for server-only mode | Object | An object containing the value for the advertising token. | See the example below. | +| value | Required for server-only mode | Object | An object containing the value for the advertising token. | See [Sample Token](#sample-token). | #### Client Refresh Mode @@ -58,10 +58,10 @@ The following parameters apply to the UID2 User ID Module if you are following t | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | -| params.uid2Token | Optional | Object | The initial UID2 token. This should be `body` element of the decrypted response from a call to the `/token/generate` or `/token/refresh` endpoint. | See the sample token below. | -| params.uid2Cookie | Optional | String | The name of a cookie which holds the initial UID2 token, set by the server. The cookie should contain JSON in the same format as the uid2Token param. **If uid2Token is supplied, this param is ignored.** | See the sample token below. | +| params.uid2Token | Optional | Object | The initial UID2 token. This should be `body` element of the decrypted response from a call to the `/token/generate` or `/token/refresh` endpoint. | See [Sample Token](#sample-token). | +| params.uid2Cookie | Optional | String | The name of a cookie which holds the initial UID2 token, set by the server. The cookie should contain JSON in the same format as the uid2Token param. **If uid2Token is supplied, this param is ignored.** | See [Sample Token](#sample-token). | -## Sample token +## Sample Token `{`
  `"advertising_token": "...",`
  `"refresh_token": "...",`
  `"identity_expires": 1633643601000,`
  `"refresh_from": 1633643001000,`
  `"refresh_expires": 1636322000000,`
  `"refresh_response_key": "wR5t6HKMfJ2r4J7fEGX9Gw=="`
`}` @@ -71,11 +71,11 @@ Refer to [Normalization and Encoding](https://unifiedid.com/docs/getting-started ## Notes -- If you provide an expired identity and the module has a valid identity which was refreshed from the identity you provide, it will use the refreshed identity. The module stores the original token used for refreshing the token, and it will use the refreshed tokens as long as the original token matches the one supplied. +- If you provide an expired identity, and the module has a valid update from refreshing the same identity, the module uses the refreshed identity in place of the expired one you provided. -- If a new token is supplied which does not match the original token used to generate any refreshed tokens, all stored tokens will be discarded and the new token used instead (refreshed if necessary). +- If you provide a new token that doesn't match the original token used to generate any refreshed tokens, the module discards all stored tokens and uses the new token instead, and keeps it refreshed. -- You can set `params.uid2ApiBase` to `"https://operator-integ.uidapi.com"` during integration testing. Be aware that you must use the same environment (production or integration) here as you use for generating tokens. +- During integration testing, set `params.uid2ApiBase` to `"https://operator-integ.uidapi.com"`. You must set this value to the same environment (production or integration) that you use for generating tokens. - If you are building Prebid.js and following the server-side integration guide, you can create a smaller Prebid.js build by disabling client-side integration functionality. To do this, pass the `--disable UID2_CSTG` flag: From 543ed66c2d07b63175598da64502a8bcdb88c247 Mon Sep 17 00:00:00 2001 From: Matt Collins Date: Tue, 13 Feb 2024 15:06:06 +1100 Subject: [PATCH 3/8] Fix uid2_pub_cookie and storage example values --- modules/uid2IdSystem.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index e9d6b438535..9eeb7876cbf 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -27,7 +27,7 @@ The following parameters apply only to the UID2 User ID Module integration. | --- | --- | --- | --- | --- | | name | Required | String | ID value for the UID2 module. Must be `"uid2"`. | `"uid2"` | | params.uid2ApiBase | Optional | String | Overrides the default UID2 API endpoint. | `"https://prod.uidapi.com"` _(default)_| -| params.storage | Optional | String | Specify whether to use `cookie` or `localStorage` for module-internal storage. It is recommended to not provide this and allow the module to use the default. | `localStorage` _(default)_ | +| params.storage | Optional | String | Specify whether to use `cookie` or `localStorage` for module-internal storage. It is recommended to not provide this and allow the module to use the default. | `"localStorage"` _(default)_ | ### Client-Side Integration @@ -59,7 +59,7 @@ The following parameters apply to the UID2 User ID Module if you are following t | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | | params.uid2Token | Optional | Object | The initial UID2 token. This should be `body` element of the decrypted response from a call to the `/token/generate` or `/token/refresh` endpoint. | See [Sample Token](#sample-token). | -| params.uid2Cookie | Optional | String | The name of a cookie which holds the initial UID2 token, set by the server. The cookie should contain JSON in the same format as the uid2Token param. **If uid2Token is supplied, this param is ignored.** | See [Sample Token](#sample-token). | +| params.uid2Cookie | Optional | String | The name of a cookie which holds the initial UID2 token, set by the server. The cookie should contain JSON in the same format as the uid2Token param. **If uid2Token is supplied, this param is ignored.** | `"uid2_pub_cookie"` | ## Sample Token From 51ef5af7214b7a526e1927179d2d67247f270ddf Mon Sep 17 00:00:00 2001 From: Matt Collins Date: Thu, 15 Feb 2024 15:47:00 +1100 Subject: [PATCH 4/8] Address review feedback --- modules/uid2IdSystem.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index 9eeb7876cbf..7e5aa5a5f67 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -2,11 +2,18 @@ ## Overview -The UID2 module handles storing, providing, and optionally generating and refreshing tokens. For more details, see [UID2 Integration Overview for Prebid.js](https://unifiedid.com/docs/guides/integration-prebid). +UID2 provides a Prebid.js module that supports the following: + +- [Generating the UID2 token](https://unifiedid.com/docs/guides/integration-prebid#generating-the-uid2-token) +- [Refreshing the UID2 token](https://unifiedid.com/docs/guides/integration-prebid#refreshing-the-uid2-token) +- [Storing the UID2 token in the browser](https://unifiedid.com/docs/guides/integration-prebid#storing-the-uid2-token-in-the-browser) +- [Passing the UID2 token to the bid stream](https://unifiedid.com/docs/guides/integration-prebid#passing-the-uid2-token-to-the-bid-stream) + +For more details, see [UID2 Integration Overview for Prebid.js](https://unifiedid.com/docs/guides/integration-prebid). **Important information:** UID2 is not designed to be used where GDPR applies. The module checks the passed-in consent data and does not operate if the `gdprApplies` flag is true. -Depending on access to DII, there are two methods to generate UID2 tokens for use with Prebid.js, as shown in the following table. +Depending on access to [directly identifying information](https://unifiedid.com/docs/ref-info/glossary-uid#d) (DII), there are two methods to generate UID2 tokens for use with Prebid.js, as shown in the following table. Determine which method is best for you, and then follow the applicable integration guide. @@ -31,22 +38,22 @@ The following parameters apply only to the UID2 User ID Module integration. ### Client-Side Integration -The following parameters apply to the UID2 User ID Module if you are following the client-side integration guide. Exactly one of params.email, params.emailHash, params.phone, and params.phoneHash must be provided. +The following parameters apply to the UID2 User ID Module if you are following the [client-side integration guide](https://unifiedid.com/docs/guides/integration-prebid-client-side). Exactly one of params.email, params.emailHash, params.phone, and params.phoneHash must be provided. For information on how to normalize and hash these parameters, refer to [Normalization and Encoding](https://unifiedid.com/docs/getting-started/gs-normalization-encoding). | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | | params.serverPublicKey | Required for client-side integration | String | See [Subscription ID and Public Key](https://unifiedid.com/docs/getting-started/gs-credentials#subscription-id-and-public-key). | - | | params.subscriptionId | Required for client-side integration | String | See [Subscription ID and Public Key](https://unifiedid.com/docs/getting-started/gs-credentials#subscription-id-and-public-key). | - | | params.email | Optional | String | The user's email address. Provide this parameter if using email as the DII. | `"test@example.com"` | -| params.emailHash | Optional | String | A hashed, normalized representation of the user's email. Provide this parameter if using emailHash as the DII. | `"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="` | -| params.phone | Optional | String | The user's phone number. Provide this parameter if using phone as the DII. | `"+15555555555"` | -| params.phoneHash | Optional | String | A hashed, normalized representation of the user's phone number. Provide this parameter if using phoneHash as the DII. | `"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="` | +| params.emailHash | Optional | String | A [hashed, normalized](https://unifiedid.com/docs/getting-started/gs-normalization-encoding) representation of the user's email. Provide this parameter if using emailHash as the DII. | `"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="` | +| params.phone | Optional | String | A [normalized representation](https://unifiedid.com/docs/getting-started/gs-normalization-encoding) of the user's phone number. Provide this parameter if using phone as the DII. | `"+15555555555"` | +| params.phoneHash | Optional | String | A [hashed, normalized](https://unifiedid.com/docs/getting-started/gs-normalization-encoding) representation of the user's phone number. Provide this parameter if using phoneHash as the DII. | `"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="` | ### Server-Side Integration #### Server-Only Mode -The following parameters apply to the UID2 User ID Module if you are following the server-side integration guide with server-only mode. +The following parameters apply to the UID2 User ID Module if you are following the [server-side integration guide](https://unifiedid.com/docs/guides/integration-prebid-server-side) with [server-only mode](https://unifiedid.com/docs/guides/integration-prebid-server-side#server-only-mode). | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | @@ -54,7 +61,7 @@ The following parameters apply to the UID2 User ID Module if you are following t #### Client Refresh Mode -The following parameters apply to the UID2 User ID Module if you are following the server-side integration guide with client refresh mode. Either params.uid2Token or params.uid2Cookie must be provided. +The following parameters apply to the UID2 User ID Module if you are following the [server-side integration guide](https://unifiedid.com/docs/guides/integration-prebid-server-side) with [client refresh mode](https://unifiedid.com/docs/guides/integration-prebid-server-side#client-refresh-mode). Either params.uid2Token or params.uid2Cookie must be provided. | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | From 938c3e802e922440e49868448444eefff4a56587 Mon Sep 17 00:00:00 2001 From: Matt Collins Date: Thu, 15 Feb 2024 15:52:21 +1100 Subject: [PATCH 5/8] Restore deleted context about normalizing and encoding --- modules/uid2IdSystem.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index 7e5aa5a5f67..2dc63b1a167 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -74,7 +74,9 @@ The following parameters apply to the UID2 User ID Module if you are following t ## Normalization and Encoding -Refer to [Normalization and Encoding](https://unifiedid.com/docs/getting-started/gs-normalization-encoding). +It's important that, in working with UID2, normalizing and encoding are performed correctly. By doing so, you can ensure that the UID2 value you create can be securely and anonymously matched up with other instances of online behavior by the same user. + +For more information, refer to [Normalization and Encoding](https://unifiedid.com/docs/getting-started/gs-normalization-encoding). ## Notes From 039aa4b30278fc4403d885c47a4dcaf52319a6d7 Mon Sep 17 00:00:00 2001 From: Matt Collins Date: Thu, 15 Feb 2024 16:02:45 +1100 Subject: [PATCH 6/8] Use a code block for sample token --- modules/uid2IdSystem.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index 2dc63b1a167..ec666b685c8 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -70,7 +70,16 @@ The following parameters apply to the UID2 User ID Module if you are following t ## Sample Token -`{`
  `"advertising_token": "...",`
  `"refresh_token": "...",`
  `"identity_expires": 1633643601000,`
  `"refresh_from": 1633643001000,`
  `"refresh_expires": 1636322000000,`
  `"refresh_response_key": "wR5t6HKMfJ2r4J7fEGX9Gw=="`
`}` +``` +{ + "advertising_token": "...", + "refresh_token": "...", + "identity_expires": 1633643601000, + "refresh_from": 1633643001000, + "refresh_expires": 1636322000000, + "refresh_response_key": "wR5t6HKMfJ2r4J7fEGX9Gw==" +} +``` ## Normalization and Encoding From 2bd00917f1a9e365251dedf1197e6e4407580336 Mon Sep 17 00:00:00 2001 From: Matt Collins Date: Thu, 15 Feb 2024 16:07:50 +1100 Subject: [PATCH 7/8] Fix example for value --- modules/uid2IdSystem.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index ec666b685c8..a8ac2369296 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -57,7 +57,7 @@ The following parameters apply to the UID2 User ID Module if you are following t | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | -| value | Required for server-only mode | Object | An object containing the value for the advertising token. | See [Sample Token](#sample-token). | +| value | Required for server-only mode | Object | An object containing the value for the advertising token. | 
{
  uid2: {
    id: '...advertising token...'
  }
}
| #### Client Refresh Mode From f5af7c8e101c16ec08332976650fed4a4c006913 Mon Sep 17 00:00:00 2001 From: Matt Collins Date: Fri, 16 Feb 2024 14:30:36 +1100 Subject: [PATCH 8/8] Address review feedback --- modules/uid2IdSystem.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index a8ac2369296..c3b38e36531 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -9,7 +9,7 @@ UID2 provides a Prebid.js module that supports the following: - [Storing the UID2 token in the browser](https://unifiedid.com/docs/guides/integration-prebid#storing-the-uid2-token-in-the-browser) - [Passing the UID2 token to the bid stream](https://unifiedid.com/docs/guides/integration-prebid#passing-the-uid2-token-to-the-bid-stream) -For more details, see [UID2 Integration Overview for Prebid.js](https://unifiedid.com/docs/guides/integration-prebid). +For details, see [UID2 Integration Overview for Prebid.js](https://unifiedid.com/docs/guides/integration-prebid). **Important information:** UID2 is not designed to be used where GDPR applies. The module checks the passed-in consent data and does not operate if the `gdprApplies` flag is true. @@ -38,7 +38,7 @@ The following parameters apply only to the UID2 User ID Module integration. ### Client-Side Integration -The following parameters apply to the UID2 User ID Module if you are following the [client-side integration guide](https://unifiedid.com/docs/guides/integration-prebid-client-side). Exactly one of params.email, params.emailHash, params.phone, and params.phoneHash must be provided. For information on how to normalize and hash these parameters, refer to [Normalization and Encoding](https://unifiedid.com/docs/getting-started/gs-normalization-encoding). +The following parameters apply to the UID2 User ID Module if you are following the [client-side integration guide](https://unifiedid.com/docs/guides/integration-prebid-client-side). Exactly one of `params.email`, `params.emailHash`, `params.phone`, and `params.phoneHash` must be provided. For information on how to normalize and hash these parameters, refer to [Normalization and Encoding](https://unifiedid.com/docs/getting-started/gs-normalization-encoding). | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | @@ -46,7 +46,7 @@ The following parameters apply to the UID2 User ID Module if you are following t | params.subscriptionId | Required for client-side integration | String | See [Subscription ID and Public Key](https://unifiedid.com/docs/getting-started/gs-credentials#subscription-id-and-public-key). | - | | params.email | Optional | String | The user's email address. Provide this parameter if using email as the DII. | `"test@example.com"` | | params.emailHash | Optional | String | A [hashed, normalized](https://unifiedid.com/docs/getting-started/gs-normalization-encoding) representation of the user's email. Provide this parameter if using emailHash as the DII. | `"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="` | -| params.phone | Optional | String | A [normalized representation](https://unifiedid.com/docs/getting-started/gs-normalization-encoding) of the user's phone number. Provide this parameter if using phone as the DII. | `"+15555555555"` | +| params.phone | Optional | String | A [normalized](https://unifiedid.com/docs/getting-started/gs-normalization-encoding) representation of the user's phone number. Provide this parameter if using phone as the DII. | `"+15555555555"` | | params.phoneHash | Optional | String | A [hashed, normalized](https://unifiedid.com/docs/getting-started/gs-normalization-encoding) representation of the user's phone number. Provide this parameter if using phoneHash as the DII. | `"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="` | ### Server-Side Integration @@ -61,12 +61,12 @@ The following parameters apply to the UID2 User ID Module if you are following t #### Client Refresh Mode -The following parameters apply to the UID2 User ID Module if you are following the [server-side integration guide](https://unifiedid.com/docs/guides/integration-prebid-server-side) with [client refresh mode](https://unifiedid.com/docs/guides/integration-prebid-server-side#client-refresh-mode). Either params.uid2Token or params.uid2Cookie must be provided. +The following parameters apply to the UID2 User ID Module if you are following the [server-side integration guide](https://unifiedid.com/docs/guides/integration-prebid-server-side) with [client refresh mode](https://unifiedid.com/docs/guides/integration-prebid-server-side#client-refresh-mode). Either `params.uid2Token` or `params.uid2Cookie` must be provided. | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | -| params.uid2Token | Optional | Object | The initial UID2 token. This should be `body` element of the decrypted response from a call to the `/token/generate` or `/token/refresh` endpoint. | See [Sample Token](#sample-token). | -| params.uid2Cookie | Optional | String | The name of a cookie which holds the initial UID2 token, set by the server. The cookie should contain JSON in the same format as the uid2Token param. **If uid2Token is supplied, this param is ignored.** | `"uid2_pub_cookie"` | +| params.uid2Token | Optional | Object | The initial UID2 token. This should be the `body` element of the decrypted response from a call to the `/token/generate` or `/token/refresh` endpoint. | See [Sample Token](#sample-token). | +| params.uid2Cookie | Optional | String | The name of a cookie that holds the initial UID2 token, set by the server. The cookie should contain JSON in the same format as the uid2Token param. **If uid2Token is supplied, this param is ignored.** | `"uid2_pub_cookie"` | ## Sample Token