UID2 module: Add documentation for cstg

modules/uid2IdSystem.md

@@ -1,11 +1,60 @@
 ## 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 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` 
+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 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
+
+Configuration:
+```
+pbjs.setConfig({
+    userSync: {
+        userIds: [{
+            name: 'uid2',
+            params: {
+               serverPublicKey: '...server public key...',
+               subscriptionId: '...subcription id...',
+               email: '[email protected]',
+               //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.
@@ -133,3 +182,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. | `"[email protected]"` |
+| 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="` |