From f8cfffa25c55c40d9448f41cb62a63eb67351999 Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Fri, 21 Nov 2025 17:29:06 -0500 Subject: [PATCH 1/6] clarify using Base64 value for UID2 --- .../gs-normalization-encoding.md | 95 +++++++++++++++++-- .../integration-javascript-client-side.md | 4 + 2 files changed, 89 insertions(+), 10 deletions(-) diff --git a/docs/getting-started/gs-normalization-encoding.md b/docs/getting-started/gs-normalization-encoding.md index bb065b5b4..c194af1bc 100644 --- a/docs/getting-started/gs-normalization-encoding.md +++ b/docs/getting-started/gs-normalization-encoding.md @@ -58,6 +58,14 @@ For examples of various scenarios, see [Normalization Examples for Email](#norma An email hash is a Base64-encoded SHA-256 hash of a normalized email address. The email address is first normalized, then hashed using the SHA-256 hashing algorithm, and then the resulting bytes of the hash value are encoded using Base64 encoding. Note that the Base64 encoding is applied to the bytes of the hash value, not the hex-encoded string representation. +The following table shows an example of a simple input phone number, and the result as each step is applied to arrive at a secure, opaque, URL-safe value. + +The final value, the hex to Base64 encoded representation of the SHA-256 hash, is the value to provide to the UID2 Operator endpoint. + +:::warning +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. If you use a function that takes text as input, the result is a longer string which is invalid for the purposes of UID2. +::: + | Type | Example | Comments and Usage | | :--- | :--- | :--- | | Raw email address | `USER@example.com` | N/A | @@ -65,10 +73,6 @@ An email hash is a Base64-encoded Date: Fri, 21 Nov 2025 17:32:00 -0500 Subject: [PATCH 2/6] edit --- docs/getting-started/gs-normalization-encoding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/gs-normalization-encoding.md b/docs/getting-started/gs-normalization-encoding.md index c194af1bc..299efc892 100644 --- a/docs/getting-started/gs-normalization-encoding.md +++ b/docs/getting-started/gs-normalization-encoding.md @@ -58,7 +58,7 @@ For examples of various scenarios, see [Normalization Examples for Email](#norma An email hash is a Base64-encoded SHA-256 hash of a normalized email address. The email address is first normalized, then hashed using the SHA-256 hashing algorithm, and then the resulting bytes of the hash value are encoded using Base64 encoding. Note that the Base64 encoding is applied to the bytes of the hash value, not the hex-encoded string representation. -The following table shows an example of a simple input phone number, and the result as each step is applied to arrive at a secure, opaque, URL-safe value. +The following table shows an example of a simple input email address, and the result as each step is applied to arrive at a secure, opaque, URL-safe value. The final value, the hex to Base64 encoded representation of the SHA-256 hash, is the value to provide to the UID2 Operator endpoint. From c05af9e8f0a9583dbae45321e144c294a849a3e3 Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Fri, 21 Nov 2025 17:42:56 -0500 Subject: [PATCH 3/6] edits --- docs/getting-started/gs-normalization-encoding.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/getting-started/gs-normalization-encoding.md b/docs/getting-started/gs-normalization-encoding.md index 299efc892..64730a26f 100644 --- a/docs/getting-started/gs-normalization-encoding.md +++ b/docs/getting-started/gs-normalization-encoding.md @@ -211,18 +211,16 @@ You can use this tool to verify that your internal processes are set up to corre ## Troubleshooting -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: +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. -- **Hashing tool**: In all scenarios, follow the steps on your side, and then check 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: - **Phone numbers**: Make sure you're normalizing—and normalizing correctly—as the first step. - If you're processing emails, the service does the normalization; however, with phone numbers, the service cannot normalize. For example, it cannot determine a missing country code. Use these resources: - - For instructions, see [Phone Number Normalization](#phone-number-normalization). - - To cross-check, test using the [UID2 Hashing Tool](#uid2-hashing-tool). + The service normalizes emails, but it can't normalize phone numbers. For example, it can't determine the value for a missing country code. Use these resources: + - Instructions: [Phone Number Normalization](#phone-number-normalization). + - Tool for cross-checking: [UID2 Hashing Tool](#uid2-hashing-tool). - **Use the Base64-encoded value**: The process includes normalizing, then hashing, then Base64-encoding the bytes of the hash value. When generating UID2s, the input is the Base64-encoded value. Make sure you're using this 44-character string value. -- You might see the following error message: "The hashing value must be 44 characters." In this scenario, there is an error with the hashing function you are using. You must use the hex to Base64 encoding of the SHA-256 hash. For details, see [Email Address Hash Encoding](#email-address-hash-encoding) or [Phone Number Hash Encoding](#phone-number-hash-encoding). - - To cross-check, test using the [UID2 Hashing Tool](#uid2-hashing-tool). \ No newline at end of file +- You might see the following error message: "The hashing value must be 44 characters." In this scenario, there is an error with the hashing function you're using. Use the hex to Base64 encoding of the SHA-256 hash. For details, see [Email Address Hash Encoding](#email-address-hash-encoding) or [Phone Number Hash Encoding](#phone-number-hash-encoding). To cross-check, test using the [UID2 Hashing Tool](#uid2-hashing-tool). \ No newline at end of file From 7a531d8280a219e79df30e807ef05caceab29d84 Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Mon, 24 Nov 2025 11:42:36 -0500 Subject: [PATCH 4/6] edits from SW with samples of different table treatments --- .../gs-normalization-encoding.md | 94 ++++++++++++++++++- 1 file changed, 92 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/gs-normalization-encoding.md b/docs/getting-started/gs-normalization-encoding.md index 64730a26f..527065da1 100644 --- a/docs/getting-started/gs-normalization-encoding.md +++ b/docs/getting-started/gs-normalization-encoding.md @@ -58,7 +58,7 @@ For examples of various scenarios, see [Normalization Examples for Email](#norma An email hash is a Base64-encoded SHA-256 hash of a normalized email address. The email address is first normalized, then hashed using the SHA-256 hashing algorithm, and then the resulting bytes of the hash value are encoded using Base64 encoding. Note that the Base64 encoding is applied to the bytes of the hash value, not the hex-encoded string representation. -The following table shows an example of a simple input email address, and the result as each step is applied to arrive at a secure, opaque, URL-safe value. +The following table shows an example of a simple input email address, and the result as each step is applied to arrive at a secure, opaque value. The final value, the hex to Base64 encoded representation of the SHA-256 hash, is the value to provide to the UID2 Operator endpoint. @@ -85,6 +85,96 @@ Some of the examples show email addresses that include the plus sign (+), with d In working with your own UID2s, always provide the final value, the Base64-encoded value, to the UID2 Operator endpoint. ::: +[**GWH__SW Not entirely sure what you're asking, but, trying a couple of different treatments here. Below is #1. I'd tried this before the one I checked in, but felt there was too much separation between the values.**] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Original ValueProcessing StepsResulting Values
`MyEmail@example.com`1. Normalize`myemail@example.com`
2. Hash`16c18d336f0b250f0e2d907452ceb9658a74ecdae8bc94864c23122a72cc27a5`
3. Base64-Encode`FsGNM28LJQ8OLZB0Us65ZYp07NrovJSGTCMSKnLMJ6U=`
`MyEmail@example.com`
`MYEMAIL@example.com`		1. Normalize`myemail@example.com`
2. Hash`16c18d336f0b250f0e2d907452ceb9658a74ecdae8bc94864c23122a72cc27a5`
3. Base64-Encode`4itTvG+HEnTzpiqzejyu1yFPwU1nYhWpaiQvz62hyB8=`
`My.Email@example.com`1. Normalize`my.email@example.com`
2. Hash`e22b53bc6f871274f3a62ab37a3caed7214fc14d676215a96a242fcfada1c81f`
3. Base64-Encode`4itTvG+HEnTzpiqzejyu1yFPwU1nYhWpaiQvz62hyB8=`
+ + +[**GWH__SW here is another. If you don't like either of these, let's discuss in our meeting my Tues your Wed. Note: I could add space between the steps and values, but don't have a way to align them, AFAIK, with our current CSS.But, the above example has the values in separate rows, and the below example combines them. I felt that separate rows were too spread out; but if you feel that combining them is too squashed or otherwise less readable, we can have separate rows of course.**] + + + + + + + + + + + + + + + + + + + + + + + +
Original ValueProcessing Steps and Resulting Values
`MyEmail@example.com`
`MYEMAIL@example.com`		1. Normalize: `myemail@example.com`
2. Hash: `16c18d336f0b250f0e2d907452ceb9658a74ecdae8bc94864c23122a72cc27a5`
3. Base64-Encode: `FsGNM28LJQ8OLZB0Us65ZYp07NrovJSGTCMSKnLMJ6U=`
`MyEmail@example.com`
`MYEMAIL@example.com`		1. Normalize: `myemail@example.com`
2. Hash: `16c18d336f0b250f0e2d907452ceb9658a74ecdae8bc94864c23122a72cc27a5`
3. Base64-Encode: `FsGNM28LJQ8OLZB0Us65ZYp07NrovJSGTCMSKnLMJ6U=`
`My.Email@example.com`1. Normalize: `my.email@example.com`
2. Hash: `e22b53bc6f871274f3a62ab37a3caed7214fc14d676215a96a242fcfada1c81f`
3. Base64-Encode: `4itTvG+HEnTzpiqzejyu1yFPwU1nYhWpaiQvz62hyB8=`
+ + +[**GWH__SW here is the table I checked in, for comparison**] + + @@ -166,7 +256,7 @@ Make sure that the normalized phone number is UTF-8, not another encoding system A phone number hash is a Base64-encoded SHA-256 hash of a normalized phone number. The phone number is first normalized, then hashed using the SHA-256 hashing algorithm, and then the resulting bytes of the hash value are encoded using Base64 encoding. Note that the Base64 encoding is applied to the bytes of the hash value, not the hex-encoded string representation. -The following table shows an example of a simple input phone number, and the result as each step is applied to arrive at a secure, opaque, URL-safe value. +The following table shows an example of a simple input phone number, and the result as each step is applied to arrive at a secure, opaque value. The final value, the hex to Base64 encoded representation of the SHA-256 hash, is the value to provide to the UID2 Operator endpoint. From 6f1dfacf25b860d8faf0e448eb9f9cbc682abf16 Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Mon, 1 Dec 2025 11:47:05 -0500 Subject: [PATCH 5/6] normalization examples, finalize table format --- .../gs-normalization-encoding.md | 121 +----------------- package-lock.json | 6 +- 2 files changed, 8 insertions(+), 119 deletions(-) diff --git a/docs/getting-started/gs-normalization-encoding.md b/docs/getting-started/gs-normalization-encoding.md index 527065da1..8c1507e6b 100644 --- a/docs/getting-started/gs-normalization-encoding.md +++ b/docs/getting-started/gs-normalization-encoding.md @@ -85,70 +85,7 @@ Some of the examples show email addresses that include the plus sign (+), with d In working with your own UID2s, always provide the final value, the Base64-encoded value, to the UID2 Operator endpoint. ::: -[**GWH__SW Not entirely sure what you're asking, but, trying a couple of different treatments here. Below is #1. I'd tried this before the one I checked in, but felt there was too much separation between the values.**] - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Original ValueProcessing StepsResulting Values
`MyEmail@example.com`1. Normalize`myemail@example.com`
2. Hash`16c18d336f0b250f0e2d907452ceb9658a74ecdae8bc94864c23122a72cc27a5`
3. Base64-Encode`FsGNM28LJQ8OLZB0Us65ZYp07NrovJSGTCMSKnLMJ6U=`
`MyEmail@example.com`
`MYEMAIL@example.com`		1. Normalize`myemail@example.com`
2. Hash`16c18d336f0b250f0e2d907452ceb9658a74ecdae8bc94864c23122a72cc27a5`
3. Base64-Encode`4itTvG+HEnTzpiqzejyu1yFPwU1nYhWpaiQvz62hyB8=`
`My.Email@example.com`1. Normalize`my.email@example.com`
2. Hash`e22b53bc6f871274f3a62ab37a3caed7214fc14d676215a96a242fcfada1c81f`
3. Base64-Encode`4itTvG+HEnTzpiqzejyu1yFPwU1nYhWpaiQvz62hyB8=`
- - -[**GWH__SW here is another. If you don't like either of these, let's discuss in our meeting my Tues your Wed. Note: I could add space between the steps and values, but don't have a way to align them, AFAIK, with our current CSS.But, the above example has the values in separate rows, and the below example combines them. I felt that separate rows were too spread out; but if you feel that combining them is too squashed or otherwise less readable, we can have separate rows of course.**] - - - +
@@ -156,10 +93,6 @@ In working with your own UID2s, always provide the final value, the Base64-encod - - - - @@ -168,69 +101,25 @@ In working with your own UID2s, always provide the final value, the Base64-encod - -
Original Value
`MyEmail@example.com`
`MYEMAIL@example.com`		1. Normalize: `myemail@example.com`
2. Hash: `16c18d336f0b250f0e2d907452ceb9658a74ecdae8bc94864c23122a72cc27a5`
3. Base64-Encode: `FsGNM28LJQ8OLZB0Us65ZYp07NrovJSGTCMSKnLMJ6U=`
`MyEmail@example.com`
`MYEMAIL@example.com`		 1. Normalize: `myemail@example.com`
2. Hash: `16c18d336f0b250f0e2d907452ceb9658a74ecdae8bc94864c23122a72cc27a5`
3. Base64-Encode: `FsGNM28LJQ8OLZB0Us65ZYp07NrovJSGTCMSKnLMJ6U=`		`My.Email@example.com` 1. Normalize: `my.email@example.com`
2. Hash: `e22b53bc6f871274f3a62ab37a3caed7214fc14d676215a96a242fcfada1c81f`
3. Base64-Encode: `4itTvG+HEnTzpiqzejyu1yFPwU1nYhWpaiQvz62hyB8=`
- - -[**GWH__SW here is the table I checked in, for comparison**] - - - - - - - - - - - - - - - - - - - - - - - - - - - - + - - + - - + - - +
Original ValueProcessing StepsResulting Values
`MyEmail@example.com`
`MYEMAIL@example.com`		1. Normalize
2. Hash
3. Base64-Encode		`myemail@example.com`
`16c18d336f0b250f0e2d907452ceb9658a74ecdae8bc94864c23122a72cc27a5`
`FsGNM28LJQ8OLZB0Us65ZYp07NrovJSGTCMSKnLMJ6U=`
`MyEmail@example.com`
`MYEMAIL@example.com`		1. Normalize
2. Hash
3. Base64-Encode		`myemail@example.com`
`16c18d336f0b250f0e2d907452ceb9658a74ecdae8bc94864c23122a72cc27a5`
`FsGNM28LJQ8OLZB0Us65ZYp07NrovJSGTCMSKnLMJ6U=`
`My.Email@example.com`1. Normalize
2. Hash
3. Base64-Encode		`my.email@example.com`
`e22b53bc6f871274f3a62ab37a3caed7214fc14d676215a96a242fcfada1c81f`
`4itTvG+HEnTzpiqzejyu1yFPwU1nYhWpaiQvz62hyB8=`
`JANESAOIRSE@example.com`
`JaneSaoirse@example.com`		1. Normalize
2. Hash
3. Base64-Encode		`janesaoirse@example.com`
`d6670e7a92007f1b5ff785f1fc81e53aa6d3d7bd06bdf5c473cdc7286c284b6d`
`1mcOepIAfxtf94Xx/IHlOqbT170GvfXEc83HKGwoS20=`		1. Normalize: `janesaoirse@example.com`
2. Hash: `d6670e7a92007f1b5ff785f1fc81e53aa6d3d7bd06bdf5c473cdc7286c284b6d`
3. Base64-Encode: `1mcOepIAfxtf94Xx/IHlOqbT170GvfXEc83HKGwoS20=`
`jane.saoirse@example.com`
`Jane.Saoirse@example.com`		1. Normalize
2. Hash
3. Base64-Encode		`jane.saoirse@example.com`
`b196432c7b989a2ca91c83799957c515da53e6c13abf20b78fea94f117e90bf8`
`sZZDLHuYmiypHIN5mVfFFdpT5sE6vyC3j+qU8RfpC/g=`		1. Normalize: `jane.saoirse@example.com`
2. Hash: `b196432c7b989a2ca91c83799957c515da53e6c13abf20b78fea94f117e90bf8`
3. Base64-Encode: `sZZDLHuYmiypHIN5mVfFFdpT5sE6vyC3j+qU8RfpC/g=`
`JaneSaoirse+Work@example.com`1. Normalize
2. Hash
3. Base64-Encode		`janesaoirse+work@example.com`
`28aaee4815230cd3b4ebd88c515226550666e91ac019929e3adac3f66c288180`
`KKruSBUjDNO069iMUVImVQZm6RrAGZKeOtrD9mwogYA=`		1. Normalize: `janesaoirse+work@example.com`
2. Hash: `28aaee4815230cd3b4ebd88c515226550666e91ac019929e3adac3f66c288180`
3. Base64-Encode: `KKruSBUjDNO069iMUVImVQZm6RrAGZKeOtrD9mwogYA=`
`JANE.SAOIRSE@gmail.com`
`Jane.Saoirse@gmail.com`
`JaneSaoirse+Work@gmail.com`		1. Normalize
2. Hash
3. Base64-Encode		`janesaoirse@gmail.com`
`92ee26057ed9dea2535d6c8b141d48373932476599196e00352254896db5888f`
`ku4mBX7Z3qJTXWyLFB1INzkyR2WZGW4ANSJUiW21iI8=`		1. Normalize: `janesaoirse@gmail.com`
2. Hash: `92ee26057ed9dea2535d6c8b141d48373932476599196e00352254896db5888f`
3. Base64-Encode: `ku4mBX7Z3qJTXWyLFB1INzkyR2WZGW4ANSJUiW21iI8=`
- - ## Phone Number Normalization :::important diff --git a/package-lock.json b/package-lock.json index 80f7893c5..8dd07bc32 100644 --- a/package-lock.json +++ b/package-lock.json @@ -6055,9 +6055,9 @@ } }, "node_modules/caniuse-lite": { - "version": "1.0.30001723", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001723.tgz", - "integrity": "sha512-1R/elMjtehrFejxwmexeXAtae5UO9iSyFn6G/I806CYC/BLyyBk1EPhrKBkWhy6wM6Xnm47dSJQec+tLJ39WHw==", + "version": "1.0.30001757", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001757.tgz", + "integrity": "sha512-r0nnL/I28Zi/yjk1el6ilj27tKcdjLsNqAOZr0yVjWPrSQyHgKI2INaEWw21bAQSv2LXRt1XuCS/GomNpWOxsQ==", "funding": [ { "type": "opencollective", From 85f12572b184916f38a04bc9850833c740c7c22e Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Mon, 1 Dec 2025 15:03:13 -0500 Subject: [PATCH 6/6] minor edit --- docs/getting-started/gs-normalization-encoding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/gs-normalization-encoding.md b/docs/getting-started/gs-normalization-encoding.md index 8c1507e6b..05fb08621 100644 --- a/docs/getting-started/gs-normalization-encoding.md +++ b/docs/getting-started/gs-normalization-encoding.md @@ -85,7 +85,7 @@ Some of the examples show email addresses that include the plus sign (+), with d In working with your own UID2s, always provide the final value, the Base64-encoded value, to the UID2 Operator endpoint. ::: - +
Original Value