From 37a5be70ac099930a4a61d27f153dd7d59c90275 Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Wed, 27 Aug 2025 13:46:19 -0400 Subject: [PATCH 1/5] 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/5] 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/5] 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', From f6ef93869115dccd263a990b52f27466ed2dd7da Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Fri, 2 Jan 2026 17:18:25 -0500 Subject: [PATCH 4/5] minor edits --- .../ref-preparing-emails-and-phone-numbers-for-processing.md | 4 ++++ .../ref-preparing-emails-and-phone-numbers-for-processing.md | 4 ++++ 2 files changed, 8 insertions(+) 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 index 49b1a0298..1a8289dc8 100644 --- 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 @@ -18,6 +18,8 @@ This is true in all cases, whichever of these solutions you're using to convert - By using any of the UID2 SDK integrations, Prebid.js integration, or Android/iOS integration. - By using Snowflake. +## Processing Steps + 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. @@ -25,6 +27,8 @@ The exact steps for preparing your data to be consumed by the UID2 service are l 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. +## Valid Input + 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. 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 index 49b1a0298..1a8289dc8 100644 --- 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 @@ -18,6 +18,8 @@ This is true in all cases, whichever of these solutions you're using to convert - By using any of the UID2 SDK integrations, Prebid.js integration, or Android/iOS integration. - By using Snowflake. +## Processing Steps + 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. @@ -25,6 +27,8 @@ The exact steps for preparing your data to be consumed by the UID2 service are l 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. +## Valid Input + 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.
From d487e1b8526a1542056fcec65338efe7cb0c3050 Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Fri, 2 Jan 2026 17:32:01 -0500 Subject: [PATCH 5/5] add new section in some additional files --- docs/guides/integration-advertiser-dataprovider-endpoints.md | 5 +++++ docs/guides/integration-options-private-operator.md | 3 --- docs/guides/integration-snowflake.md | 5 +++++ 3 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/guides/integration-advertiser-dataprovider-endpoints.md b/docs/guides/integration-advertiser-dataprovider-endpoints.md index 6a0e92c4f..de8e8e9e7 100644 --- a/docs/guides/integration-advertiser-dataprovider-endpoints.md +++ b/docs/guides/integration-advertiser-dataprovider-endpoints.md @@ -8,6 +8,7 @@ displayed_sidebar: sidebarAdvertisers --- import Link from '@docusaurus/Link'; +import SnptPreparingEmailsAndPhoneNumbers from '../snippets/_snpt-preparing-emails-and-phone-numbers.mdx'; # Advertiser/Data Provider Integration to HTTP Endpoints @@ -48,6 +49,10 @@ At a high level, the steps for advertisers and data providers integrating with U 6. [Monitor for Opt-Out Status](#6-monitor-for-opt-out-status) +## Preparing DII for Processing + + + ## Integration Diagram The following diagram outlines the steps that data collectors must complete to map DII to raw UID2s for audience building and targeting. diff --git a/docs/guides/integration-options-private-operator.md b/docs/guides/integration-options-private-operator.md index 49a5b716b..e7724ddbf 100644 --- a/docs/guides/integration-options-private-operator.md +++ b/docs/guides/integration-options-private-operator.md @@ -101,11 +101,8 @@ 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/guides/integration-snowflake.md b/docs/guides/integration-snowflake.md index 18b83bc52..23fa0f8a9 100644 --- a/docs/guides/integration-snowflake.md +++ b/docs/guides/integration-snowflake.md @@ -9,6 +9,7 @@ displayed_sidebar: docs --- import Link from '@docusaurus/Link'; +import SnptPreparingEmailsAndPhoneNumbers from '../snippets/_snpt-preparing-emails-and-phone-numbers.mdx'; # Snowflake Integration Guide @@ -100,6 +101,10 @@ If you want to try out an integration before using the production environment, s If you did any initial testing (see [Testing in the Integ Environment](#testing-in-the-integ-environment)), be sure to update the functions to reflect the production UID2 share, along with your own relevant table names. ::: +## Preparing DII for Processing + + + ## Testing in the Integ Environment If you'd like to test the mapping share before signing a UID2 POC, you can ask your UID2 contact for access to the Snowflake share in the integ (integration) environment. This environment is for testing only, and has no production data. In the request, be sure to include your account number and region.