Skip to content

Commit 62adee8

Browse files
aulmeaulme
committed
Copy the English Identity Map content into Japanese until translation is available
1 parent 2f74875 commit 62adee8

File tree

1 file changed

+293
-1
lines changed

1 file changed

+293
-1
lines changed

‎i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md‎

Lines changed: 293 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,298 @@ import Link from '@docusaurus/Link';
1212
このページには、近日中に翻訳される新しいコンテンツが含まれています。
1313
:::
1414

15+
# POST /identity/map
1516

16-
TODO: I will add a copy of the English language text here instead this todo once content is finalized.
17+
Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to check for updates to opt-out information, check when a raw UID2 can be refreshed, or view the previous UID2 if the current UID2 is less than 90 days old.
1718

19+
Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md).
20+
21+
For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md).
22+
23+
## Version
24+
25+
This documentation is for the latest version of this endpoint, version 3.
26+
27+
If needed, documentation is also available for the previous version: see [POST /identity/map (v2)](post-identity-map-v2.md).
28+
29+
## Batch Size and Request Parallelization Requirements
30+
31+
Here's what you need to know:
32+
33+
- The maximum request size is 1MB.
34+
- To map a large number of email addresses, phone numbers, or their respective hashes, send them in *sequential* batches with a maximum batch size of 5,000 items per batch.
35+
- Unless you are using a <Link href="../ref-info/glossary-uid#gl-private-operator">Private Operator</Link>, do not send batches in parallel. In other words, use a single HTTP connection and send batches of hashed or unhashed <Link href="../ref-info/glossary-uid#gl-dii">directly identifying information (DII)</Link> values consecutively, without creating multiple parallel connections.
36+
- Be sure to store mappings of email addresses, phone numbers, or their respective hashes.<br/>Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers).
37+
38+
## Request Format
39+
40+
`POST '{environment}/v3/identity/map'`
41+
42+
For authentication details, see [Authentication and Authorization](../getting-started/gs-auth.md).
43+
44+
:::important
45+
You must encrypt all requests using your secret. For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).
46+
:::
47+
48+
### Path Parameters
49+
50+
| Path Parameter | Data Type | Attribute | Description |
51+
| :--- | :--- | :--- | :--- |
52+
| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). |
53+
54+
:::note
55+
The integration environment and the production environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>. For information about getting credentials for each environment, see [Getting Your Credentials](../getting-started/gs-credentials.md#getting-your-credentials).
56+
:::
57+
58+
### Unencrypted JSON Body Parameters
59+
60+
:::important
61+
Include one or more of the following four parameters as key-value pairs in the JSON body of the request when encrypting it.
62+
:::
63+
64+
| Body Parameter | Data Type | Attribute | Description |
65+
|:---------------|:----------------------------|:-----------------------| :--- |
66+
| `email` | string array | Conditionally Required | The list of email addresses to be mapped. |
67+
| `email_hash` | string array | Conditionally Required | The list of [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hashes of [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email addresses to be mapped. |
68+
| `phone` | string array | Conditionally Required | The list of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. |
69+
| `phone_hash` | string array | Conditionally Required | The list of [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) hashes of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. |
70+
71+
72+
### Request Examples
73+
74+
The following are unencrypted JSON request body examples to the `POST /identity/map` endpoint:
75+
76+
```json
77+
{
78+
"email":[
79+
"[email protected]",
80+
"[email protected]"
81+
],
82+
"phone":[
83+
"+12345678901",
84+
"+441234567890"
85+
]
86+
}
87+
```
88+
89+
```json
90+
{
91+
"email_hash":[
92+
"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
93+
"KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU="
94+
],
95+
"phone_hash":[
96+
"EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
97+
"Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ="
98+
]
99+
}
100+
```
101+
102+
Here's an encrypted request example to the `POST /identity/map` endpoint for phone numbers:
103+
104+
```sh
105+
echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v3/identity/map [YOUR_CLIENT_API_KEY] [YOUR_CLIENT_SECRET]
106+
```
107+
108+
For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).
109+
110+
## Decrypted JSON Response Format
111+
112+
:::note
113+
The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted.
114+
:::
115+
116+
A successful decrypted response returns the current raw UID2s, previous raw UID2s, and refresh timestamps for the specified email addresses, phone numbers, or their respective hashes.
117+
118+
The response arrays preserve the order of input arrays. Each element in the response array maps directly to the element at the same index in the corresponding request array. This ensures that you can reliably associate results with their corresponding inputs based on array position.
119+
120+
Input values that cannot be mapped to a raw UID2 are mapped to an error object with the reason for unsuccessful mapping. An unsuccessful mapping occurs if the DII is invalid or has been opted out from the UID2 ecosystem. In these cases, the response status is `success` but no raw UID2 is returned.
121+
122+
The following example shows the input and corresponding response.
123+
124+
Input:
125+
126+
```json
127+
{
128+
"email": [
129+
"[email protected]", // Corresponding UID2 rotated in the last 90 days
130+
"[email protected]", // Corresponding UID2 rotated more than 90 days ago
131+
"invalid email string", // Invalid identifier
132+
"[email protected]" // DII is opted out
133+
]
134+
}
135+
```
136+
137+
Response:
138+
139+
```json
140+
{
141+
"body":{
142+
"email": [
143+
{
144+
"u": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
145+
"p": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
146+
"r": 1735689600000
147+
},
148+
{
149+
"u": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=",
150+
"p": null,
151+
"r": 1735862400000
152+
},
153+
{ "e": "invalid identifier" },
154+
{ "e": "optout" }
155+
],
156+
"email_hash": [],
157+
"phone": [],
158+
"phone_hash": []
159+
},
160+
"status": "success"
161+
}
162+
```
163+
164+
### Response Body Properties
165+
166+
The response body includes one or more of the properties shown in the following table.
167+
168+
| Body Parameter | Data Type | Description |
169+
|:---------------|:----------------------------|:------------------------------------------------------------------------------------------------|
170+
| `email` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of emails in the request. |
171+
| `email_hash` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of email hashes in the request. |
172+
| `phone` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of phone numbers in the request. |
173+
| `phone_hash` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of phone number hashes in the request. |
174+
175+
176+
For successfully mapped DII, the mapped object includes the properties shown in the following table.
177+
178+
| Property | Data Type | Description |
179+
|:---------|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------|
180+
| `u` | string | The raw UID2 corresponding to the email or phone number provided in the request. |
181+
| `p` | string | One of the following:<ul><li>If the current raw UID2 has been rotated in the last 90 days: the previous value.</li><li>If the current raw UID2 is older than 90 days: `Null`.</li></ul> |
182+
| `r` | number | The Unix timestamp (in milliseconds) that indicates when the raw UID2 might be refreshed. The raw UID2 is guaranteed to be valid until this timestamp. |
183+
184+
For unsuccessfully mapped input values, the mapped object includes the properties shown in the following table.
185+
186+
| Property | Data Type | Description |
187+
|:---------|:----------|:-----------------------------------------------------------------------------------------------------------------|
188+
| `e` | string | The reason for being unable to map the DII to a raw UID2. One of two possible values:<ul><li>`optout`</li><li>`invalid identifier`</li></ul> |
189+
190+
### Response Status Codes
191+
192+
The following table lists the `status` property values and their HTTP status code equivalents.
193+
194+
| Status | HTTP Status Code | Description |
195+
| :--- | :--- | :--- |
196+
| `success` | 200 | The request was successful. The response will be encrypted. |
197+
| `client_error` | 400 | The request had missing or invalid parameters. |
198+
| `unauthorized` | 401 | The request did not include a bearer token, included an invalid bearer token, or included a bearer token unauthorized to perform the requested operation. |
199+
200+
If the `status` value is anything other than `success`, the `message` field provides additional information about the issue.
201+
202+
## Migration from v2 Identity Map
203+
204+
The following sections provide general information and guidance for migrating to version 3 from earlier versions, including:
205+
206+
- [Version 3 Improvements](#version-3-improvements)
207+
- [Key Differences Between v2 and v3](#key-differences-between-v2-and-v3)
208+
- [Required Changes](#required-changes)
209+
- [Additional Resources](#additional-resources)
210+
211+
### Version 3 Improvements
212+
213+
The v3 Identity Map API provides the following improvements over v2:
214+
215+
- **Simplified Refresh Management**: You can monitor for UID2s reaching `refresh_from` timestamps instead of polling <Link href="../ref-info/glossary-uid#gl-salt-bucket-id">salt buckets</Link> for rotation.
216+
- **Previous UID2 Access**: You have access to previous raw UID2s for 90 days after rotation for campaign measurement.
217+
- **Single Endpoint**: You use only one endpoint, `/v3/identity/map`, instead of both `/v2/identity/map` and `/v2/identity/buckets`.
218+
- **Multiple Identity Types in One Request**: You can process both emails and phone numbers in a single request.
219+
- **Improved Performance**: The updated version uses significantly less bandwidth to process the same amount of DII.
220+
221+
### Key Differences Between v2 and v3
222+
223+
The following table shows key differences between the versions.
224+
225+
| Feature | V2 Implementation | V3 Implementation |
226+
|:-------------------------------|:--------------------------------------------|:-------------------------------------------|
227+
| Endpoints Required | `/v2/identity/map` + `/v2/identity/buckets` | `/v3/identity/map` only |
228+
| Identity Types per Request | Single identity type only | Multiple identity types |
229+
| Refresh Management | Monitor salt bucket rotations via `/identity/buckets` endpoint | Re-map when past `refresh_from` timestamps |
230+
| Previous UID2 Access | Not available | Available for 90 days |
231+
232+
### Required Changes
233+
234+
To upgrade from an earlier version to version 3, follow these steps:
235+
236+
1. [Update Endpoint URL](#1-update-endpoint-url)
237+
2. [Update V3 Response Parsing Logic](#2-update-v3-response-parsing-logic)
238+
3. [Replace Salt Bucket Monitoring with Refresh Timestamp Logic](#3-replace-salt-bucket-monitoring-with-refresh-timestamp-logic)
239+
240+
#### 1. Update Endpoint URL
241+
242+
Update any reference to the endpoint URL so that it references the /v3/ implementation, as shown in the following example.
243+
244+
```python
245+
# Before (v2)
246+
url = '/v2/identity/map'
247+
248+
# After (v3)
249+
url = '/v3/identity/map'
250+
```
251+
252+
#### 2. Update v3 Response Parsing Logic
253+
254+
Update the logic for parsing the response, as shown in the following example.
255+
256+
V2 Response Parsing:
257+
```python
258+
# v2: Process mapped/unmapped objects with identifier lookup
259+
for item in response['body']['mapped']:
260+
raw_uid = item['advertising_id']
261+
bucket_id = item['bucket_id']
262+
original_identifier = item['identifier']
263+
# Store mapping using identifier as key
264+
store_mapping(original_identifier, raw_uid, bucket_id)
265+
```
266+
267+
V3 Response Parsing:
268+
```python
269+
# v3: Process array-indexed responses
270+
for index, item in enumerate(response['body']['email']):
271+
original_email = request_emails[index] # Use array index to correlate
272+
if 'u' in item:
273+
# Successfully mapped
274+
current_uid = item['u']
275+
previous_uid = item.get('p') # Available for 90 days after rotation, otherwise None
276+
refresh_from = item['r']
277+
store_mapping(original_email, current_uid, previous_uid, refresh_from)
278+
elif 'e' in item:
279+
# Handle unmapped with reason
280+
handle_unmapped(original_email, item['e'])
281+
```
282+
283+
#### 3. Replace Salt Bucket Monitoring with Refresh Timestamp Logic
284+
285+
Update your code for salt bucket monitoring, replacing it with code that checks the `refresh_from` timestamp to determine raw UID2s that are due for refresh.
286+
287+
The following example shows an implementation of the v3 approach for checking refresh timestamps:
288+
289+
```python
290+
import time
291+
292+
def is_refresh_needed(mapping):
293+
now = int(time.time() * 1000) # Convert to milliseconds
294+
return now >= mapping['refresh_from']
295+
296+
# Check individual mappings for refresh needs
297+
to_remap = [mapping for mapping in mappings if is_refresh_needed(mapping)]
298+
remap_identities(to_remap)
299+
```
300+
301+
### Additional Resources
302+
- [SDK for Java](../sdks/sdk-ref-java.md) for Java implementations (see Usage for Advertisers/Data Providers section)
303+
304+
<!-- For SDK-specific migration guidance, see:
305+
- [SDK for Python](../sdks/sdk-ref-python.md) for Python implementations -->
306+
307+
<!-- GWH 7/7 Commenting out the above until the SDK docs are available. -->
308+
309+
For general information about identity mapping, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md).

0 commit comments

Comments
 (0)