Merge branch 'main' into gwh-APIDOCS-2923-js-sdk-v4

Author: genwhittTTD

docs/getting-started/gs-faqs.md

@@ -213,7 +213,7 @@ If a user opts out through your website, you should follow your internal procedu
 
 In general yes, the process of generating a raw UID2 from DII is the same, and results in the same value, no matter who sent the request. If two UID2 participants were to send the same email address to the [POST /identity/map](../endpoints/post-identity-map.md) endpoint at the same time, they would both get the same raw UID2 in response.
 
-However, there is a variable factor, which is the <Link href="../ref-info/glossary-uid#gl-salt">salt</Link> value that's used in generating the raw UID2. The salt values are rotated roughly once per year (for details, see [How often should UID2s be refreshed for incremental updates?](#how-often-should-uid2s-be-refreshed-for-incremental-updates)). If the salt value changes between one request and another, those two requests result in two different raw UID2, even when the DII is the same.
+However, there is a variable factor, which is the secret <Link href="../ref-info/glossary-uid#gl-salt">salt</Link> value that's used in generating the raw UID2. The salt values are rotated roughly once per year (for details, see [How often should UID2s be refreshed for incremental updates?](#how-often-should-uid2s-be-refreshed-for-incremental-updates)). If the salt value changes between one request and another, those two requests result in two different raw UID2, even when the DII is the same.
 
 For more information, see [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s](../guides/integration-advertiser-dataprovider-overview.md#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s) in the *Advertiser/Data Provider Integration Guide*.
 

docs/getting-started/gs-normalization-encoding.md

@@ -61,7 +61,7 @@ An email hash is a Base64-encoded <Link href="../ref-info/glossary-uid#gl-sha-25
 | :--- | :--- | :--- |
 | Normalized email address | `[email protected]` | 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.<br/>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.<br/>Use this encoding for `email_hash` values sent in the request body. |
+| Hex to Base64 encoding of SHA-256 hash | `tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=` | This 44-character string is a Base64-encoded representation of the 32-byte SHA-256.<br/>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.<br/>Use this encoding for `email_hash` values sent in the request body. |
 
 :::important
 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.
@@ -100,7 +100,7 @@ The following table shows an example of a simple input phone number, and the res
 | :--- | :--- | :--- |
 | 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.<br/>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. |
+| Hex to Base64 encoding of SHA-256 hash | `EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=` | This 44-character string is a Base64-encoded representation of the 32-byte SHA-256.<br/>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.

docs/ref-info/glossary-uid.md

@@ -204,7 +204,7 @@ import Link from '@docusaurus/Link';
 <!-- <dd>**new**</dd> -->
 
 <dt><MdxJumpAnchor id="gl-core-service"><a href="#gl-core-service">Core Service</a></MdxJumpAnchor></dt>
-<dd>The UID2 Core Service is a centralized service that manages access to <a href="#gl-salt">salts</a>, encryption keys, and other relevant data in the UID2 ecosystem.</dd>
+<dd>The UID2 Core Service is a centralized service that manages access to secret <a href="#gl-salt">salts</a>, encryption keys, and other relevant data in the UID2 ecosystem.</dd>
 <dd>For an overview of all the UID2 services, see <a href="../intro#components">Components</a>.</dd>
 
 </dl>
@@ -339,7 +339,7 @@ import Link from '@docusaurus/Link';
 
 <dt><MdxJumpAnchor id="gl-operator"><a href="#gl-operator">Operator</a></MdxJumpAnchor></dt>
 <dd>An Operator is an organization or entity that runs the UID2 <a href="#gl-operator-service">Operator Service</a>. The UID2 Operator is the API server in the UID2 ecosystem.</dd>
-<dd>Operators perform multiple functions, such as receiving <a href="#gl-encryption-key">encryption keys</a> and <a href="#gl-salt">salts</a> from the UID2 Core Service, salting and hashing personal data (<Link href="#gl-dii">DII</Link>) to return raw UID2s, and encrypting raw UID2s to generate UID2 tokens.</dd>
+<dd>Operators perform multiple functions, such as receiving <a href="#gl-encryption-key">encryption keys</a> and secret <a href="#gl-salt">salts</a> from the UID2 Core Service, salting and hashing personal data (<Link href="#gl-dii">DII</Link>) to return raw UID2s, and encrypting raw UID2s to generate UID2 tokens.</dd>
 <dd>A participant can also choose to become a <a href="#gl-private-operator">Private Operator</a> to access UID2 APIs and to generate raw UID2s and UID2 tokens from within a private infrastructure.</dd>
 <dd>For details, see <a href="../intro#participants">participants</a> and <a href="../ref-info/ref-operators-public-private">The UID2 Operator</a>.</dd>
 
@@ -406,15 +406,15 @@ import Link from '@docusaurus/Link';
 <dl>
 
 <dt><MdxJumpAnchor id="gl-salt"><a href="#gl-salt">Salt</a></MdxJumpAnchor></dt>
-<dd>A string of characters that is used in the process of transforming an email address or phone number into a secure, opaque value that cannot by itself be traced back to the original value (raw UID2 or UID2 token).</dd>
+<dd>A string of characters that is used in the process of transforming an email address or phone number into a secure, opaque value that cannot by itself be traced back to the original value (raw UID2 or UID2 token). Salt values are kept secret.</dd>
 <dd>The UID2 service uses salt as part of the process, along with hashing and encryption, to secure the original value. Salt is added to the input value before hashing.</dd>
 
 <dt><MdxJumpAnchor id="gl-salt-bucket"><a href="#gl-salt-bucket">Salt bucket</a></MdxJumpAnchor></dt>
 <dd>A salt bucket is used to manage secret <a href="#gl-salt">salt</a> values, used to generate raw UID2s or UID2 tokens, over time. Each bucket contains a single current salt value, which remains active for approximately one year before being rotated to a new value. Buckets can be updated independently of one another.</dd>
 <dd>There are just over one million salt buckets, and each email address or phone number is assigned to a specific bucket in a deterministic manner. However, this assignment is not permanent; it might change when the bucket's current secret salt is rotated to a new value.</dd>
 
 <dt><MdxJumpAnchor id="gl-salt-bucket-id"><a href="#gl-salt-bucket-id">Salt bucket ID</a></MdxJumpAnchor></dt>
-<dd>A salt bucket ID is a unique string of characters that identifies a specific <a href="#gl-salt-bucket">salt bucket</a>. The salt bucket ID can be used to check which salt buckets have recently had their salt values updated, indicating which emails or phone numbers need their raw UID2 values regenerated.</dd>
+<dd>A salt bucket ID is a unique string of characters that identifies a specific <a href="#gl-salt-bucket">salt bucket</a>. The salt bucket ID can be used to check which salt buckets have recently had their secret salt values updated, indicating which emails or phone numbers need their raw UID2 values regenerated.</dd>
 <dd>For an example of a salt bucket ID, see the response to the `POST /identity/buckets` endpoint: <a href="../endpoints/post-identity-buckets#decrypted-json-response-format">Decrypted JSON Response Format</a>.</dd>
 
 <dt><MdxJumpAnchor id="gl-salted-hash"><a href="#gl-salted-hash">Salted hash</a></MdxJumpAnchor></dt>
@@ -510,7 +510,7 @@ import Link from '@docusaurus/Link';
 <dd>The token value is opaque: No assumptions should be made about the format or about the length of the string.</dd>
 <dd>The token has a limited life, but can be refreshed in the background using the <a href="#gl-refresh-token">refresh token</a>.</dd>
 <dd>Publishers send UID2 tokens in the bidstream.</dd>
-<dd>For details, see <a href="../intro#uid2-identifier-types">UID2 Identifier Types</a> and <a href="ref-tokens#uid2-tokens-key-information">UID2 Tokens: Key Information</a>.</dd>
+<dd>For details, see <a href="../intro#uid2-identifier-types">UID2 Identifier Types</a>, <a href="ref-tokens#uid2-tokens-key-information">UID2 Tokens: Key Information</a>, and <a href="ref-how-uid-is-created">How the UID2 Token Is Created</a>.</dd>
 
 <dt><MdxJumpAnchor id="gl-unified-id-20"><a href="#gl-unified-id-20">Unified ID 2.0</a></MdxJumpAnchor></dt>
 <dd>The term UID2 can be used to mean the <a href="#gl-uid2-framework">UID2 framework</a>, the <a href="#gl-uid2-service">UID2 service</a>, a <a href="#gl-raw-uid2">raw UID2</a>, or a <a href="#gl-uid2-token">UID2 token</a> (advertising token).</dd>

docs/ref-info/images/HowUID2Created_UID2ImplementationPlaybook.jpg

@@ -0,0 +1,87 @@
+---
+title: How the UID2 Token Is Created
+description: Reference information about the process for generating a UID2 token.
+hide_table_of_contents: false
+sidebar_position: 06
+---
+
+import Link from '@docusaurus/Link';
+
+# How the UID2 Token Is Created
+
+:::note
+This article describes how the UID2 token that the publisher sends in the bidstream is created. The process is the same for advertisers creating UID2 tokens for conversion pixels. It does not apply to <Link href="../ref-info/glossary-uid#gl-tokenized-sharing">tokenized sharing</Link>, where raw UID2s are encrypted into UID2 tokens before sending to another sharing participant.
+:::
+
+When a publisher sends a user's <Link href="../ref-info/glossary-uid#gl-dii">DII</Link>&#8212;<Link href="../ref-info/glossary-uid#gl-hash">hashed</Link> or unhashed email addresses or phone numbers&#8212;to the UID2 <Link href="../ref-info/glossary-uid#gl-operator">Operator</Link>, and in return receives a <Link href="../ref-info/glossary-uid#gl-uid2-token">UID2 token</Link> to use for targeted advertising, there is a very specific sequence of processing steps that occurs along the way.
+
+ Some preliminary steps are taken by the publisher, but most of the processing steps are done by the UID2 Operator.
+
+It's very important that the publisher steps are performed in the correct sequence:
+- When steps are performed in sequence, the resulting value can be recognized as related to other [UID2 identifiers](../intro.md#uid2-identifier-types) generated from online activity by the same individual: the underlying [raw UID2](../ref-info/glossary-uid.md#gl-raw-uid2) matches the raw UID2s generated by other UID2 participants from the same DII, and therefore the token is suitable for targeted advertising.
+- If steps are taken out of sequence, the resulting value cannot be related to other UID2 identifiers generated from online activity by the same individual, and therefore the token is not suitable for targeted advertising.
+
+For a summary, see [Steps to Create a UID2 Token](#steps-to-create-a-uid2-token). For an example in diagram form, see [Creating a UID2 Token&#8212;Example](#creating-a-uid2-tokenexample).
+
+## Steps to Create a UID2 Token
+
+The following table shows the steps for creating a UID2 token from DII, the sequence, and who performs each step.
+
+For an example with sample values, see [Creating a UID2 Token&#8212;Example](#creating-a-uid2-tokenexample).
+
+<table width="100%">
+  <thead>
+    <tr>
+      <th width="5%">Step</th>
+      <th width="35%">Action</th>
+      <th width="30%">Who Does It?</th>
+      <th width="35%">Documentation</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1</td>
+      <td><Link href="../ref-info/glossary-uid#gl-normalize">Normalize.</Link></td>
+      <td>**Email**: Publisher or UID2 Operator<br/>**Phone number**: Publisher must normalize</td>
+      <td>[Email Address Normalization](../getting-started/gs-normalization-encoding.md#email-address-normalization)<br/>[Phone Number Normalization](../getting-started/gs-normalization-encoding.md#phone-number-normalization)</td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td>Apply <Link href="../ref-info/glossary-uid#gl-sha-256">SHA-256</Link> hashing to the normalized email address.</td>
+      <td>Publisher or UID2 Operator</td>
+      <td>[Email Address Hash Encoding](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding)<br/>[Phone Number Hash Encoding](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding)</td>
+    </tr>
+    <tr>
+      <td>3</td>
+      <td>Apply Base64 encoding to the SHA-256 hash.</td>
+      <td>Publisher or UID2 Operator</td>
+      <td>[Email Address Hash Encoding](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding)<br/>[Phone Number Hash Encoding](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding)</td>
+    </tr>
+    <tr>
+      <td>4</td>
+      <td>Send value to UID2 Operator via the [POST&nbsp;/token/generate](../endpoints/post-token-generate.md) endpoint, an SDK, Prebid.js, or another supported integration.</td>
+      <td>Publisher</td>
+      <td>Various: for a summary, see [Implementation Resources](../overviews/overview-publishers.md#implementation-resources)</td>
+    </tr>
+     <tr>
+      <td>5</td>
+      <td>Perform multiple steps including hashing and adding the secret <Link href="../ref-info/glossary-uid#gl-salt">salt</Link> value to create a raw UID2.</td>
+      <td>UID2 Operator</td>
+      <td>Not applicable: these steps are all performed by the UID2 Operator.</td>
+    </tr>
+     <tr>
+      <td>6</td>
+      <td>Encrypt the raw UID2 to create a UID2 token.</td>
+      <td>UID2 Operator</td>
+      <td>Not applicable: performed by the UID2 Operator.</td>
+    </tr>
+ </tbody>
+</table>
+
+## Creating a UID2 Token&#8212;Example
+
+The following diagram shows the high-level steps for creating a [raw UID2](../ref-info/glossary-uid.md#gl-raw-uid2) (first column, second column) and then a [UID2 token](../ref-info/glossary-uid.md#gl-uid2-token) (third column).
+
+The publisher can send a request to the [POST&nbsp;/token/generate](../endpoints/post-token-generate.md) endpoint or use one of the other integration options, such as an SDK or Prebid. Whatever the integration option, the result is a UID2 token&#8212;an encrypted value that the publisher can send in the bidstream for targeted advertising.
+
+![Sequential steps for creating a UID2](images/HowUID2Created_UID2ImplementationPlaybook.jpg)

docs/ref-info/images/resource/HowUID2Created_UID2ImplementationPlaybook.pptx

@@ -28,6 +28,8 @@ Here are some key points about UID2 tokens:
 - Publishers send UID2 tokens in the bidstream.
 - Refreshing a UID2 token does not invalidate/expire the original or previous UID2 token. You can still use the earlier token until it expires.
 
+For more information, see [How the UID2 Token Is Created](ref-how-uid-is-created.md).
+
 ## Refresh Tokens: Key Information
 
 Here are some key points about refresh tokens: