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
+85-10Lines changed: 85 additions & 10 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 phone number, and the result as each step is applied to arrive at a secure, opaque, URL-safe 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,65 @@ 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 |
84
+
:::important
85
+
In working with your own UID2s, always provide the final value, the Base64-encoded value, to the UID2 Operator endpoint.
@@ -113,17 +168,19 @@ A phone number hash is a Base64-encoded SHA-256 hash of a normalized phone numbe
113
168
114
169
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.
115
170
171
+
The final value, the hex to Base64 encoded representation of the SHA-256 hash, is the value to provide to the UID2 Operator endpoint.
172
+
173
+
:::warning
174
+
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.
175
+
:::
176
+
116
177
| Type | Example | Comments and Usage |
117
178
| :--- | :--- | :--- |
118
179
| Raw phone number |`1 (234) 567-8901`| N/A |
119
180
| Normalized phone number |`+12345678901`| Normalization is always the first step. |
120
181
| SHA-256 hash of normalized phone number |`10e6f0b47054a83359477dcb35231db6de5c69fb1816e1a6b98e192de9e5b9ee`|This 64-character string is a hex-encoded representation of the 32-byte SHA-256. |
121
182
| 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
183
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
184
## Example Code
128
185
129
186
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 +208,21 @@ The tool does the following:
151
208
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
209
153
210
You can use this tool to verify that your internal processes are set up to correctly create normalized, hashed, and encoded values for UID2.
211
+
212
+
## Troubleshooting
213
+
214
+
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:
215
+
216
+
-**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.
217
+
218
+
-**Phone numbers**: Make sure you're normalizing—and normalizing correctly—as the first step.
219
+
220
+
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:
221
+
- For instructions, see [Phone Number Normalization](#phone-number-normalization).
222
+
- To cross-check, test using the [UID2 Hashing Tool](#uid2-hashing-tool).
223
+
224
+
-**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.
225
+
226
+
- 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).
227
+
228
+
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