Gwh apidocs 2855 how uid2 created

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.

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>

docs/ref-info/ref-how-uid-is-created.md

@@ -0,0 +1,92 @@
+---
+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
+
+When a publisher sends <Link href="../ref-info/glossary-uid#gl-dii">DII</Link> (email or phone number) to UID2, 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 <Link href="../ref-info/glossary-uid#gl-operator">Operator</Link>.
+
+It's very important that the publisher steps are performed in the correct sequence:
+- When steps are performed in sequence, the resulting value **matches** other instances of tokens generated from online activity by the same individual, and therefore the token is **valuable** for targeted advertising.
+- If steps are taken out of sequence, the resulting value **does not match** other instances of tokens generated from online activity by the same individual, and therefore the token is **not valid** 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 showing each step performed on a sample value, see [Creating a UID2 Token&#8212;Example](#creating-a-uid2-tokenexample).
+
+<table width="100%">
+  <thead>
+    <tr>
+      <th width="5%">Step</th>
+      <th width="30%">Action</th>
+      <th width="25%">Who Does It?</th>
+      <th width="25%">Documentation</th>
+      <th width="15%">[Example](#creating-a-uid2-tokenexample)</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1</td>
+      <td>Normalization</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>
+      <td>Not shown. For examples, see [Normalization Examples for Email](../getting-started/gs-normalization-encoding.md#normalization-examples-for-email).</td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td>SHA-256 hashing of 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>
+      <td>Column 1</td>
+    </tr>
+    <tr>
+      <td>3</td>
+      <td>Hex to Base64 encoding of 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>
+      <td>Column 1</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>
+      <td>Not shown</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>
+      <td>Column 2</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>
+      <td>Column 3</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)
+
+The token cannot be reverse engineered to tie back to the advertiser side. The UID2 process operates by passing an email or its hashed equivalent to the UID2 Operator, and the Operator then processes and encrypts the value to create a UID2 token. Demand-Side Platforms (DSPs) decrypt this token to arrive at the underlying raw UID2, and can then align it with UID2 segments predefined by advertisers who have transformed their data into UID2 format. Each participant only has access to their own specific information.

i18n/ja/docusaurus-plugin-content-docs/current/ref-info/ref-how-uid-is-created.md

@@ -0,0 +1,92 @@
+---
+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
+
+When a publisher sends <Link href="../ref-info/glossary-uid#gl-dii">DII</Link> (email or phone number) to UID2, 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 <Link href="../ref-info/glossary-uid#gl-operator">Operator</Link>.
+
+It's very important that the publisher steps are performed in the correct sequence:
+- When steps are performed in sequence, the resulting value **matches** other instances of tokens generated from online activity by the same individual, and therefore the token is **valuable** for targeted advertising.
+- If steps are taken out of sequence, the resulting value **does not match** other instances of tokens generated from online activity by the same individual, and therefore the token is **not valid** 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 showing each step performed on a sample value, see [Creating a UID2 Token&#8212;Example](#creating-a-uid2-tokenexample).
+
+<table width="100%">
+  <thead>
+    <tr>
+      <th width="5%">Step</th>
+      <th width="30%">Action</th>
+      <th width="25%">Who Does It?</th>
+      <th width="25%">Documentation</th>
+      <th width="15%">[Example](#creating-a-uid2-tokenexample)</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1</td>
+      <td>Normalization</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>
+      <td>Not shown. For examples, see [Normalization Examples for Email](../getting-started/gs-normalization-encoding.md#normalization-examples-for-email).</td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td>SHA-256 hashing of 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>
+      <td>Column 1</td>
+    </tr>
+    <tr>
+      <td>3</td>
+      <td>Hex to Base64 encoding of 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>
+      <td>Column 1</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>
+      <td>Not shown</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>
+      <td>Column 2</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>
+      <td>Column 3</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)
+
+The token cannot be reverse engineered to tie back to the advertiser side. The UID2 process operates by passing an email or its hashed equivalent to the UID2 Operator, and the Operator then processes and encrypts the value to create a UID2 token. Demand-Side Platforms (DSPs) decrypt this token to arrive at the underlying raw UID2, and can then align it with UID2 segments predefined by advertisers who have transformed their data into UID2 format. Each participant only has access to their own specific information.

sidebars.js

@@ -341,6 +341,7 @@ const fullSidebar = [
         'ref-info/ref-operators-public-private',
         'ref-info/ref-integration-approaches',
         'ref-info/ref-tokens',
+        'ref-info/ref-how-uid-is-created',
         'ref-info/ref-server-side-token-generation',
         'ref-info/ref-integration-sso-providers',
       ],