From fa236f5fab410e66988ecda0ef6c0aa171f48f0d Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Thu, 19 Oct 2023 11:34:55 +1100 Subject: [PATCH 01/18] Add documentation for cstg --- modules/uid2IdSystem.md | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index a795d9b1aa1..79a772589c6 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -1,11 +1,46 @@ ## UID2 User ID Submodule -UID2 requires initial tokens to be generated server-side. The UID2 module handles storing, providing, and optionally refreshing them. The module can operate in one of two different modes: *Client Refresh* mode or *Server Only* mode. +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. *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 may not be necessary for all publishers. You can instruct the build to exclude code for this feature: + +``` + $ gulp build --modules=uid2IdSystem --disable UID2_CSTG +``` + **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 + +For publishers seeking a purely client-side integration without the complexities of server-side involvement, the CSTG mode is highly recommended. This mode necessitates the provision of a public key, subscription ID, and directly identifying information (DII). 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.subscription` +2. Provide **ONLY ONE DII** by set `params.email`/`params.phone`/`params.emailHash`/`params.phoneHash` + +### 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. From 7bc4807bb133e2a40a2a63ca8212d265b4ddc7d1 Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Thu, 19 Oct 2023 15:09:00 +1100 Subject: [PATCH 02/18] Add params to the table --- modules/uid2IdSystem.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index 79a772589c6..24f2bfdb370 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -14,11 +14,13 @@ The UID2 module handles storing, providing, and optionally refreshing tokens. Wh ## Client-Side Token Generation (CSTG) mode -For publishers seeking a purely client-side integration without the complexities of server-side involvement, the CSTG mode is highly recommended. This mode necessitates the provision of a public key, subscription ID, and directly identifying information (DII). In the CSTG mode, the module takes on the responsibility of encrypting the DII, generating the UID2 token, and handling token refreshes when necessary. +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.subscription` -2. Provide **ONLY ONE DII** by set `params.email`/`params.phone`/`params.emailHash`/`params.phoneHash` +1. Set `parmas.serverPublicKey` and `params.subscriptionId` +2. Provide **ONLY ONE DII** by setting **ONLY ONE** of `params.email`/`params.phone`/`params.emailHash`/`params.phoneHash` + +For the correct way to generate email and phone hash, refer to this [UID2 documentation](https://unifiedid.com/docs/getting-started/gs-normalization-encoding). ### CSTG example @@ -168,3 +170,9 @@ The below parameters apply only to the UID2 User ID Module integration. | 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="` | From 99b278d67385a34130a15ccff91ddb5ed7444a9d Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Thu, 19 Oct 2023 17:22:28 +1100 Subject: [PATCH 03/18] add table to explain the usage of each param --- modules/uid2IdSystem.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index 24f2bfdb370..4585efc0595 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -20,7 +20,19 @@ To configure the module to use this mode, you must: 1. Set `parmas.serverPublicKey` and `params.subscriptionId` 2. Provide **ONLY ONE DII** by setting **ONLY ONE** of `params.email`/`params.phone`/`params.emailHash`/`params.phoneHash` -For the correct way to generate email and phone hash, refer to this [UID2 documentation](https://unifiedid.com/docs/getting-started/gs-normalization-encoding). +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 setIdentityFromEmail will normalize email addresses, but setIdentityFromPhone requires phone numbers to be normalized.* + +Refer to this page [Normalization and Encoding](https://unifiedid.com/docs/getting-started/gs-normalization-encoding) on [unifiedid.com](https://unifiedid.com/) for details on email address normalization, SHA-256 hashing and Base64 encoding. ### CSTG example From da8884f2f9eb9c660114eb55c80feeca7d6c8356 Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Mon, 23 Oct 2023 12:42:30 +1100 Subject: [PATCH 04/18] Mark cstg as alpha --- modules/uid2IdSystem.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index 4585efc0595..b21931b2468 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -1,14 +1,15 @@ ## 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. +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 (Alpha) 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(Alpha). *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 may not be necessary for all publishers. You can instruct the build to exclude code for this feature: +*Client-Side Token Generation* mode is included in UID2 module by default. However, it's important to note that this mode is currently in an alpha stage of development. 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, we strongly recommend consulting with the UID2 Team before implementing it in your integration. **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. @@ -17,7 +18,7 @@ The UID2 module handles storing, providing, and optionally refreshing tokens. Wh 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` +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. From 0f7309ae997e38615112a4a13812ff31b09b2202 Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Mon, 23 Oct 2023 12:50:42 +1100 Subject: [PATCH 05/18] Address feedback --- modules/uid2IdSystem.md | 73 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 72 insertions(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index b21931b2468..324526e58d4 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -33,7 +33,7 @@ Below is a table that provides guidance on when to use each directly identifying *Note that setIdentityFromEmail will normalize email addresses, but setIdentityFromPhone requires phone numbers to be normalized.* -Refer to this page [Normalization and Encoding](https://unifiedid.com/docs/getting-started/gs-normalization-encoding) on [unifiedid.com](https://unifiedid.com/) for details on email address normalization, SHA-256 hashing and Base64 encoding. +Refer to [Normalization and Encoding](#normalization-and-encoding) for details on email address normalization, SHA-256 hashing and Base64 encoding. ### CSTG example @@ -189,3 +189,74 @@ The below parameters apply only to the UID2 User ID Module integration. | 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. + +## 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. + +>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. + +## 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. + +> 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. + +To normalize an email address, complete the following steps: + +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`. + +## Email Address Hash Encoding + +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. + +| 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. | + +>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. + +## Phone Number Normalization + +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. + +> 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. + +Here's what you need to know about phone number normalization rules: + +- 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`. + +## Phone Number Hash Encoding + +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. + +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. + +| 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. | + +>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. \ No newline at end of file From a4644ac4bf54d83c1a7f4e8a9da7edc94e4e4084 Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Mon, 23 Oct 2023 12:53:34 +1100 Subject: [PATCH 06/18] Address feedback --- modules/uid2IdSystem.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index 324526e58d4..086a1a6e0da 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -9,12 +9,14 @@ The UID2 module handles storing, providing, and optionally refreshing tokens. Wh ``` $ gulp build --modules=uid2IdSystem --disable UID2_CSTG ``` -If you do plan to use Client-Side Token Generation (CSTG) mode, we strongly recommend consulting with the UID2 Team before implementing it in your integration. +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) **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 currently in the alpha stage of development. 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: From b7dfb07e15383d7a3336a79ffb5294670aeb7014 Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Mon, 23 Oct 2023 12:57:03 +1100 Subject: [PATCH 07/18] change wording --- modules/uid2IdSystem.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index 086a1a6e0da..d85cb3aa16f 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -4,7 +4,7 @@ The UID2 module handles storing, providing, and optionally refreshing tokens. Wh *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 currently in an alpha stage of development. 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: +*Client-Side Token Generation* mode is included in UID2 module by default. However, it's important to note that this mode is currently in the alpha stage of development. 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 From 2e6148267b04c21ed9e1aa57923600a2e088f3e8 Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Thu, 19 Oct 2023 11:34:55 +1100 Subject: [PATCH 08/18] Add documentation for cstg --- modules/uid2IdSystem.md | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index a795d9b1aa1..79a772589c6 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -1,11 +1,46 @@ ## UID2 User ID Submodule -UID2 requires initial tokens to be generated server-side. The UID2 module handles storing, providing, and optionally refreshing them. The module can operate in one of two different modes: *Client Refresh* mode or *Server Only* mode. +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. *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 may not be necessary for all publishers. You can instruct the build to exclude code for this feature: + +``` + $ gulp build --modules=uid2IdSystem --disable UID2_CSTG +``` + **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 + +For publishers seeking a purely client-side integration without the complexities of server-side involvement, the CSTG mode is highly recommended. This mode necessitates the provision of a public key, subscription ID, and directly identifying information (DII). 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.subscription` +2. Provide **ONLY ONE DII** by set `params.email`/`params.phone`/`params.emailHash`/`params.phoneHash` + +### 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. From 900643f7c197936a11a5dba110de6e916fdefec5 Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Thu, 19 Oct 2023 15:09:00 +1100 Subject: [PATCH 09/18] Add params to the table --- modules/uid2IdSystem.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index 79a772589c6..24f2bfdb370 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -14,11 +14,13 @@ The UID2 module handles storing, providing, and optionally refreshing tokens. Wh ## Client-Side Token Generation (CSTG) mode -For publishers seeking a purely client-side integration without the complexities of server-side involvement, the CSTG mode is highly recommended. This mode necessitates the provision of a public key, subscription ID, and directly identifying information (DII). In the CSTG mode, the module takes on the responsibility of encrypting the DII, generating the UID2 token, and handling token refreshes when necessary. +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.subscription` -2. Provide **ONLY ONE DII** by set `params.email`/`params.phone`/`params.emailHash`/`params.phoneHash` +1. Set `parmas.serverPublicKey` and `params.subscriptionId` +2. Provide **ONLY ONE DII** by setting **ONLY ONE** of `params.email`/`params.phone`/`params.emailHash`/`params.phoneHash` + +For the correct way to generate email and phone hash, refer to this [UID2 documentation](https://unifiedid.com/docs/getting-started/gs-normalization-encoding). ### CSTG example @@ -168,3 +170,9 @@ The below parameters apply only to the UID2 User ID Module integration. | 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="` | From 552298fa316b4a4c13e941d9627a8c3ab66857c2 Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Thu, 19 Oct 2023 17:22:28 +1100 Subject: [PATCH 10/18] add table to explain the usage of each param --- modules/uid2IdSystem.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index 24f2bfdb370..4585efc0595 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -20,7 +20,19 @@ To configure the module to use this mode, you must: 1. Set `parmas.serverPublicKey` and `params.subscriptionId` 2. Provide **ONLY ONE DII** by setting **ONLY ONE** of `params.email`/`params.phone`/`params.emailHash`/`params.phoneHash` -For the correct way to generate email and phone hash, refer to this [UID2 documentation](https://unifiedid.com/docs/getting-started/gs-normalization-encoding). +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 setIdentityFromEmail will normalize email addresses, but setIdentityFromPhone requires phone numbers to be normalized.* + +Refer to this page [Normalization and Encoding](https://unifiedid.com/docs/getting-started/gs-normalization-encoding) on [unifiedid.com](https://unifiedid.com/) for details on email address normalization, SHA-256 hashing and Base64 encoding. ### CSTG example From ac6163400680f18d4919cf30b09c35b911b0e765 Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Mon, 23 Oct 2023 12:42:30 +1100 Subject: [PATCH 11/18] Mark cstg as alpha --- modules/uid2IdSystem.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index 4585efc0595..b21931b2468 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -1,14 +1,15 @@ ## 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. +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 (Alpha) 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(Alpha). *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 may not be necessary for all publishers. You can instruct the build to exclude code for this feature: +*Client-Side Token Generation* mode is included in UID2 module by default. However, it's important to note that this mode is currently in an alpha stage of development. 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, we strongly recommend consulting with the UID2 Team before implementing it in your integration. **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. @@ -17,7 +18,7 @@ The UID2 module handles storing, providing, and optionally refreshing tokens. Wh 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` +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. From ff7f2bf50e92e90b622ba7fee196de3c9defa19e Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Mon, 23 Oct 2023 12:50:42 +1100 Subject: [PATCH 12/18] Address feedback --- modules/uid2IdSystem.md | 73 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 72 insertions(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index b21931b2468..324526e58d4 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -33,7 +33,7 @@ Below is a table that provides guidance on when to use each directly identifying *Note that setIdentityFromEmail will normalize email addresses, but setIdentityFromPhone requires phone numbers to be normalized.* -Refer to this page [Normalization and Encoding](https://unifiedid.com/docs/getting-started/gs-normalization-encoding) on [unifiedid.com](https://unifiedid.com/) for details on email address normalization, SHA-256 hashing and Base64 encoding. +Refer to [Normalization and Encoding](#normalization-and-encoding) for details on email address normalization, SHA-256 hashing and Base64 encoding. ### CSTG example @@ -189,3 +189,74 @@ The below parameters apply only to the UID2 User ID Module integration. | 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. + +## 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. + +>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. + +## 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. + +> 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. + +To normalize an email address, complete the following steps: + +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`. + +## Email Address Hash Encoding + +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. + +| 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. | + +>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. + +## Phone Number Normalization + +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. + +> 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. + +Here's what you need to know about phone number normalization rules: + +- 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`. + +## Phone Number Hash Encoding + +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. + +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. + +| 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. | + +>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. \ No newline at end of file From 4f97e0387770eda5ffbf0e9a1509fb41883b33ae Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Mon, 23 Oct 2023 12:53:34 +1100 Subject: [PATCH 13/18] Address feedback --- modules/uid2IdSystem.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index 324526e58d4..086a1a6e0da 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -9,12 +9,14 @@ The UID2 module handles storing, providing, and optionally refreshing tokens. Wh ``` $ gulp build --modules=uid2IdSystem --disable UID2_CSTG ``` -If you do plan to use Client-Side Token Generation (CSTG) mode, we strongly recommend consulting with the UID2 Team before implementing it in your integration. +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) **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 currently in the alpha stage of development. 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: From 9a7391a8679ca26a891c1395a66145816ba740f4 Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Mon, 23 Oct 2023 12:57:03 +1100 Subject: [PATCH 14/18] change wording --- modules/uid2IdSystem.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index 086a1a6e0da..d85cb3aa16f 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -4,7 +4,7 @@ The UID2 module handles storing, providing, and optionally refreshing tokens. Wh *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 currently in an alpha stage of development. 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: +*Client-Side Token Generation* mode is included in UID2 module by default. However, it's important to note that this mode is currently in the alpha stage of development. 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 From a31c3646d1f540ea662aadcc76f48d15acb47aee Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Mon, 23 Oct 2023 13:48:50 +1100 Subject: [PATCH 15/18] trigger tests --- modules/uid2IdSystem.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index d85cb3aa16f..9a4e8ad2279 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -261,4 +261,4 @@ The example below shows a simple input phone number, and the result as each 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. | ->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. \ No newline at end of file +>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. From d05b4f2f850f4ae879e57b9818b26a4724430f07 Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Mon, 23 Oct 2023 14:07:18 +1100 Subject: [PATCH 16/18] reset commit and trigger tests --- modules/uid2IdSystem.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index d85cb3aa16f..9a4e8ad2279 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -261,4 +261,4 @@ The example below shows a simple input phone number, and the result as each 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. | ->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. \ No newline at end of file +>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. From 67bf89a97438d09febc0a531c797f4adfad68192 Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Tue, 24 Oct 2023 13:39:07 +1100 Subject: [PATCH 17/18] change wording --- modules/uid2IdSystem.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index 9a4e8ad2279..1bc56b33910 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -1,10 +1,10 @@ ## 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 (Alpha) 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(Alpha). +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. *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 currently in the alpha stage of development. 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: +*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 @@ -15,7 +15,7 @@ If you do plan to use Client-Side Token Generation (CSTG) mode, please consult t ## Client-Side Token Generation (CSTG) mode -**This mode is currently in the alpha stage of development. Please consult UID2 Team first as they will provide required configuration values for you to use.** +**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. From c5458919a96831d63d231e8b9751e79fef91f626 Mon Sep 17 00:00:00 2001 From: Jingyi Gao Date: Tue, 24 Oct 2023 18:04:01 +1100 Subject: [PATCH 18/18] update wording --- modules/uid2IdSystem.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/uid2IdSystem.md b/modules/uid2IdSystem.md index 1bc56b33910..e546f6eafe1 100644 --- a/modules/uid2IdSystem.md +++ b/modules/uid2IdSystem.md @@ -33,7 +33,7 @@ Below is a table that provides guidance on when to use each directly identifying | params.phoneHash | When you have user's hashed, normalized phone number | Yes | Yes | -*Note that setIdentityFromEmail will normalize email addresses, but setIdentityFromPhone requires phone numbers to be normalized.* +*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.