You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/getting-started/gs-normalization-encoding.md
+69-17Lines changed: 69 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -58,17 +58,21 @@ For examples of various scenarios, see [Normalization Examples for Email](#norma
58
58
59
59
An email hash is a Base64-encoded <Linkhref="../ref-info/glossary-uid#gl-sha-256">SHA-256</Link> 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.
60
60
61
+
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.
62
+
63
+
The final value, the hex to Base64 encoded representation of the SHA-256 hash, is the value to provide to the UID2 Operator endpoint.
64
+
65
+
:::warning
66
+
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.
| Normalized email address |`[email protected]`| Normalization is always the first step. |
65
73
| SHA-256 hash of normalized email address |`b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514`| This 64-character string is a hex-encoded representation of the 32-byte SHA-256. |
66
74
| 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. |
67
75
68
-
:::important
69
-
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.
70
-
:::
71
-
72
76
For additional examples, see [Normalization Examples for Email](#normalization-examples-for-email).
73
77
74
78
## Normalization Examples for Email
@@ -77,14 +81,44 @@ The following table shows examples of original email addresses and the normalize
77
81
78
82
Some of the examples show email addresses that include the plus sign (+), with different domains. For `gmail` addresses, the plus sign and following characters, up to the `@` sign, are ignored in normalization. For other domains, these characters are included in the normalized value.
79
83
80
-
| Original Value | Normalized | Hashed and Base64-Encoded |
@@ -111,7 +145,13 @@ Make sure that the normalized phone number is UTF-8, not another encoding system
111
145
112
146
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.
113
147
114
-
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.
148
+
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.
149
+
150
+
The final value, the hex to Base64 encoded representation of the SHA-256 hash, is the value to provide to the UID2 Operator endpoint.
151
+
152
+
:::warning
153
+
When applying Base64 encoding, be sure to use a function that takes a hex 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.
154
+
:::
115
155
116
156
| Type | Example | Comments and Usage |
117
157
| :--- | :--- | :--- |
@@ -120,10 +160,6 @@ The following table shows an example of a simple input phone number, and the res
120
160
| SHA-256 hash of normalized phone number |`10e6f0b47054a83359477dcb35231db6de5c69fb1816e1a6b98e192de9e5b9ee`|This 64-character string is a hex-encoded representation of the 32-byte SHA-256. |
121
161
| Hex to Base64 encoding of SHA-256 hash |`EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=`| This 44-character string is a Base64-encoded representation of the 32-byte SHA-256.<br/>NOTE: The SHA-256 hash is a hexadecimal value. You must use a Base64 encoder that takes a hex value as input. Use this encoding for `phone_hash` values sent in the request body. |
122
162
123
-
:::warning
124
-
When applying Base64 encoding, be sure to use a function that takes a hex 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.
125
-
:::
126
-
127
163
## Example Code
128
164
129
165
For an example of how to generate email and phone hashes in JavaScript, see [Example Code: Hashing and Base-64 Encoding](../guides/integration-javascript-client-side#example-code-hashing-and-base-64-encoding).
@@ -151,3 +187,19 @@ The tool does the following:
151
187
If the input data doesn't have a valid email or phone number format, or if the phone number is not normalized, the tool gives an error.
152
188
153
189
You can use this tool to verify that your internal processes are set up to correctly create normalized, hashed, and encoded values for UID2.
190
+
191
+
## Troubleshooting
192
+
193
+
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.
194
+
195
+
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:
196
+
197
+
-**Phone numbers**: Make sure you're normalizing—and normalizing correctly—as the first step.
198
+
199
+
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:
200
+
- Instructions: [Phone Number Normalization](#phone-number-normalization).
201
+
- Tool for cross-checking: [UID2 Hashing Tool](#uid2-hashing-tool).
202
+
203
+
-**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.
204
+
205
+
- 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).
Copy file name to clipboardExpand all lines: docs/guides/integration-javascript-client-side.md
+4Lines changed: 4 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -175,6 +175,10 @@ To configure the SDK, call one of the following methods, with an object containi
175
175
*`__uid2.setIdentityFromPhone`
176
176
*`__uid2.setIdentityFromPhoneHash`
177
177
178
+
:::important
179
+
For `__uid2.setIdentityFromEmailHash` or `__uid2.setIdentityFromPhoneHash`, the `emailHash` or `PhoneHash` argument must be the Base64-encoded value. For details, see [Email Address Hash Encoding](../getting-started/gs-normalization-encoding.md/#email-address-hash-encoding) and [Phone Number Hash Encoding](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding).
180
+
:::
181
+
178
182
The following sections include coding examples for each scenario.
179
183
180
184
Once it's configured, the UID2 SDK takes care of the following:
0 commit comments