gwh-APIDOCS-3410-guides-include-norm-hash-encode

docs/endpoints/post-token-generate.md

@@ -23,6 +23,10 @@ The `optout_check` parameter, required with a value of `1`, checks whether the u
 
 Rather than calling this endpoint directly, you could use one of the SDKs to manage it for you. For a summary of options, see [SDKs: Summary](../sdks/summary-sdks.md).
 
+:::important
+Whatever option you use, the data that you send for generating UID2s must be normalized, hashed, and encoded before sending. For details, see [Normalization and Encoding](../getting-started/gs-normalization-encoding.md).
+:::
+
 ## Request Format 
 
 `POST '{environment}/v2/token/generate'`

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

@@ -192,7 +192,7 @@ You can use this tool to verify that your internal processes are set up to corre
 
 In all scenarios, follow the steps on your side to prepare your DII for processing, and then check your resulting values by using the [UID2 Hashing Tool](#uid2-hashing-tool). If the results don't match, check each step to find the error.
 
-If you're having trouble or getting errors, or even if you just want to be sure you're following the steps correctly, here are some things you can check:
+If you're having trouble or getting errors, or if you just want to be sure you're following the steps correctly, here are some things you can check:
 
 - **Phone numbers**: Make sure you're normalizing—and normalizing correctly—as the first step.
 

docs/guides/integration-options-private-operator.md

@@ -8,6 +8,7 @@ displayed_sidebar: docs
 import Link from '@docusaurus/Link';
 import SnptUpgradePolicy from '../snippets/_snpt-private-operator-upgrade-policy.mdx';
 import SnptRotatingTheKeys from '../snippets/_snpt-private-operator-rotating-the-keys.mdx';
+import SnptPreparingEmailsAndPhoneNumbers from '../snippets/_snpt-preparing-emails-and-phone-numbers.mdx';
 
 # UID2 Private Operator Integration Overview
 
@@ -98,6 +99,13 @@ For information about supported versions and deprecation dates, see [Private Ope
 
 <SnptRotatingTheKeys />
 
+## Preparing DII for Processing
+
+<!-- uptohere need to replicate this section in many places -->
+
+<SnptPreparingEmailsAndPhoneNumbers />
+
+
 ## Getting Started
 
 To get started as a Private Operator, follow these steps:
@@ -115,6 +123,10 @@ To get started as a Private Operator, follow these steps:
 5. Test.
 6. Go live.
 
+:::important
+Whatever option you use, the data that you send for generating UID2s must be normalized, hashed, and encoded before sending. For details, see [Normalization and Encoding](../getting-started/gs-normalization-encoding.md).
+:::
+
 ## Implementation Resources
 
 The following documentation resources are available for Private Operators to implement UID2.

docs/ref-info/ref-preparing-emails-and-phone-numbers-for-processing.md

@@ -0,0 +1,50 @@
+---
+title: Preparing DII for Processing
+description: Summary of key steps to prepare your input data for conversion to UID2s.
+hide_table_of_contents: false
+sidebar_position: 01
+displayed_sidebar: docs
+---
+
+import Link from '@docusaurus/Link';
+
+# Preparing Emails and Phone Numbers for Processing
+
+The input data that you provide to the UID2 Service must be in the correct format so that the data is correctly converted to valid UID2s that you can use for targeted advertising.
+
+This is true in all cases, whichever of these solutions you're using to convert your emails and phone numbers to UID2s:
+- By making direct calls to the UID2 APIs.
+- Via your own Private Operator.
+- By using any of the UID2 SDK integrations, Prebid.js integration, or Android/iOS integration.
+- By using Snowflake.
+
+The exact steps for preparing your data to be consumed by the UID2 service are laid out in the [Normalization and Encoding](../getting-started/gs-normalization-encoding.md) documentation. The steps, in sequence, are as follows:
+1. Normalize the raw data.
+2. Create a 32-byte SHA-256 hash of the normalized raw data.
+3. Apply Base64-encoding to the 32-byte SHA-256 value.
+
+If you're making direct calls to the UID2 APIs, or calling the UID2 APIs via your own Private Operator, you must complete each step, exactly as described and in the correct sequence.
+
+If you're using a UID2 SDK, or other integration solution such as the Prebid.js integration, Android/iOS integration, or Snowflake, the options for your input data are shown in the following table.
+
+<table>
+  <thead>
+    <tr>
+      <th>Type of DII</th>
+      <th>Input Format</th>
+      <th>Instructions</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Email</td>
+      <td>Must be one of the following:<ul><li>Raw email</li><li>Normalized email</li><li>Normalized, then hashed, then base64-encoded</li></ul></td>
+      <td>[Email Address Normalization](../getting-started/gs-normalization-encoding#email-address-normalization)<br/>[Email Address Hash Encoding](../getting-started/gs-normalization-encoding#email-address-hash-encoding)</td>
+    </tr>
+    <tr>
+      <td>Phone Number</td>
+      <td>Must be one of the following:<ul><li>Normalized, including country code</li><li>Normalized, then hashed, then base64-encoded</li></ul></td>
+      <td>[Phone Number Normalization](../getting-started/gs-normalization-encoding#phone-number-normalization)<br/>[Phone Number Hash Encoding](../getting-started/gs-normalization-encoding#phone-number-hash-encoding)</td>
+    </tr>
+ </tbody>
+</table>

docs/snippets/_snpt-preparing-emails-and-phone-numbers.mdx

@@ -0,0 +1,5 @@
+import Link from '@docusaurus/Link';
+
+It's critical that the input data, which you are converting to UID2, is in an acceptable format. If it is not, you will not get the expected results. For example, you must normalize phone numbers to include the country code, as explained in [Phone Number Normalization](../getting-started/gs-normalization-encoding.md#phone-number-normalization).
+
+For details, see [Preparing Emails and Phone Numbers for Processing](../ref-info/ref-preparing-emails-and-phone-numbers-for-processing.md).

i18n/ja/docusaurus-plugin-content-docs/current/ref-info/ref-preparing-emails-and-phone-numbers-for-processing.md

@@ -0,0 +1,50 @@
+---
+title: Preparing DII for Processing
+description: Summary of key steps to prepare your input data for conversion to UID2s.
+hide_table_of_contents: false
+sidebar_position: 01
+displayed_sidebar: docs
+---
+
+import Link from '@docusaurus/Link';
+
+# Preparing Emails and Phone Numbers for Processing
+
+The input data that you provide to the UID2 Service must be in the correct format so that the data is correctly converted to valid UID2s that you can use for targeted advertising.
+
+This is true in all cases, whichever of these solutions you're using to convert your emails and phone numbers to UID2s:
+- By making direct calls to the UID2 APIs.
+- Via your own Private Operator.
+- By using any of the UID2 SDK integrations, Prebid.js integration, or Android/iOS integration.
+- By using Snowflake.
+
+The exact steps for preparing your data to be consumed by the UID2 service are laid out in the [Normalization and Encoding](../getting-started/gs-normalization-encoding.md) documentation. The steps, in sequence, are as follows:
+1. Normalize the raw data.
+2. Create a 32-byte SHA-256 hash of the normalized raw data.
+3. Apply Base64-encoding to the 32-byte SHA-256 value.
+
+If you're making direct calls to the UID2 APIs, or calling the UID2 APIs via your own Private Operator, you must complete each step, exactly as described and in the correct sequence.
+
+If you're using a UID2 SDK, or other integration solution such as the Prebid.js integration, Android/iOS integration, or Snowflake, the options for your input data are shown in the following table.
+
+<table>
+  <thead>
+    <tr>
+      <th>Type of DII</th>
+      <th>Input Format</th>
+      <th>Instructions</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Email</td>
+      <td>Must be one of the following:<ul><li>Raw email</li><li>Normalized email</li><li>Normalized, then hashed, then base64-encoded</li></ul></td>
+      <td>[Email Address Normalization](../getting-started/gs-normalization-encoding#email-address-normalization)<br/>[Email Address Hash Encoding](../getting-started/gs-normalization-encoding#email-address-hash-encoding)</td>
+    </tr>
+    <tr>
+      <td>Phone Number</td>
+      <td>Must be one of the following:<ul><li>Normalized, including country code</li><li>Normalized, then hashed, then base64-encoded</li></ul></td>
+      <td>[Phone Number Normalization](../getting-started/gs-normalization-encoding#phone-number-normalization)<br/>[Phone Number Hash Encoding](../getting-started/gs-normalization-encoding#phone-number-hash-encoding)</td>
+    </tr>
+ </tbody>
+</table>

sidebars.js

@@ -381,6 +381,7 @@ const fullSidebar = [
         'getting-started/gs-environments',
         'getting-started/gs-encryption-decryption',
         'getting-started/gs-normalization-encoding',
+        'ref-info/ref-preparing-emails-and-phone-numbers-for-processing',
         'getting-started/gs-opt-out',
         'ref-info/ref-operators-public-private',
         'ref-info/ref-integration-approaches',