From 37a5be70ac099930a4a61d27f153dd7d59c90275 Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Wed, 27 Aug 2025 13:46:19 -0400 Subject: [PATCH 1/3] Guides: add info re prepping data before sending to Operator --- docs/guides/integration-options-private-operator.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/guides/integration-options-private-operator.md b/docs/guides/integration-options-private-operator.md index 40020fcb0..1e953f073 100644 --- a/docs/guides/integration-options-private-operator.md +++ b/docs/guides/integration-options-private-operator.md @@ -110,6 +110,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 processing 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. From 072a7aeeee3de9b0473607fe66031576854a0cd7 Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Wed, 8 Oct 2025 14:37:38 -0400 Subject: [PATCH 2/3] update --- docs/endpoints/post-token-generate.md | 4 ++++ docs/guides/integration-options-private-operator.md | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/endpoints/post-token-generate.md b/docs/endpoints/post-token-generate.md index 59b0caa6e..2df5c9030 100644 --- a/docs/endpoints/post-token-generate.md +++ b/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'` diff --git a/docs/guides/integration-options-private-operator.md b/docs/guides/integration-options-private-operator.md index 1e953f073..3696690f4 100644 --- a/docs/guides/integration-options-private-operator.md +++ b/docs/guides/integration-options-private-operator.md @@ -111,7 +111,7 @@ To get started as a Private Operator, follow these steps: 6. Go live. :::important -Whatever option you use, the data that you send for processing must be normalized, hashed, and encoded before sending. For details, see [Normalization and Encoding](../getting-started/gs-normalization-encoding.md). +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 From 05822a860b08f5a0e3c39cbc09fba2409374dcf3 Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Mon, 29 Dec 2025 17:04:03 -0500 Subject: [PATCH 3/3] new snippet, new article, added into one integration guide --- .../gs-normalization-encoding.md | 2 +- .../integration-options-private-operator.md | 8 +++ ...emails-and-phone-numbers-for-processing.md | 50 +++++++++++++++++++ ...npt-preparing-emails-and-phone-numbers.mdx | 5 ++ ...emails-and-phone-numbers-for-processing.md | 50 +++++++++++++++++++ sidebars.js | 1 + 6 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 docs/ref-info/ref-preparing-emails-and-phone-numbers-for-processing.md create mode 100644 docs/snippets/_snpt-preparing-emails-and-phone-numbers.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/ref-info/ref-preparing-emails-and-phone-numbers-for-processing.md diff --git a/docs/getting-started/gs-normalization-encoding.md b/docs/getting-started/gs-normalization-encoding.md index 05fb08621..2fb516bcd 100644 --- a/docs/getting-started/gs-normalization-encoding.md +++ b/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. diff --git a/docs/guides/integration-options-private-operator.md b/docs/guides/integration-options-private-operator.md index dadeac396..49a5b716b 100644 --- a/docs/guides/integration-options-private-operator.md +++ b/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 +## Preparing DII for Processing + + + + + + ## Getting Started To get started as a Private Operator, follow these steps: diff --git a/docs/ref-info/ref-preparing-emails-and-phone-numbers-for-processing.md b/docs/ref-info/ref-preparing-emails-and-phone-numbers-for-processing.md new file mode 100644 index 000000000..49b1a0298 --- /dev/null +++ b/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. + + + + + + + + + + + + + + + + + + + + + +
Type of DIIInput FormatInstructions
EmailMust be one of the following:
  • Raw email
  • Normalized email
  • Normalized, then hashed, then base64-encoded
[Email Address Normalization](../getting-started/gs-normalization-encoding#email-address-normalization)
[Email Address Hash Encoding](../getting-started/gs-normalization-encoding#email-address-hash-encoding)
Phone NumberMust be one of the following:
  • Normalized, including country code
  • Normalized, then hashed, then base64-encoded
[Phone Number Normalization](../getting-started/gs-normalization-encoding#phone-number-normalization)
[Phone Number Hash Encoding](../getting-started/gs-normalization-encoding#phone-number-hash-encoding)
diff --git a/docs/snippets/_snpt-preparing-emails-and-phone-numbers.mdx b/docs/snippets/_snpt-preparing-emails-and-phone-numbers.mdx new file mode 100644 index 000000000..fcb1e43ec --- /dev/null +++ b/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). \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/ref-preparing-emails-and-phone-numbers-for-processing.md b/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/ref-preparing-emails-and-phone-numbers-for-processing.md new file mode 100644 index 000000000..49b1a0298 --- /dev/null +++ b/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. + + + + + + + + + + + + + + + + + + + + + +
Type of DIIInput FormatInstructions
EmailMust be one of the following:
  • Raw email
  • Normalized email
  • Normalized, then hashed, then base64-encoded
[Email Address Normalization](../getting-started/gs-normalization-encoding#email-address-normalization)
[Email Address Hash Encoding](../getting-started/gs-normalization-encoding#email-address-hash-encoding)
Phone NumberMust be one of the following:
  • Normalized, including country code
  • Normalized, then hashed, then base64-encoded
[Phone Number Normalization](../getting-started/gs-normalization-encoding#phone-number-normalization)
[Phone Number Hash Encoding](../getting-started/gs-normalization-encoding#phone-number-hash-encoding)
diff --git a/sidebars.js b/sidebars.js index bff237bd5..4a5f58d70 100644 --- a/sidebars.js +++ b/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',