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
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).
16
16
17
17
:::important
18
-
If you're using the latest version of `POST /v3/identity/map`, v3, you don't need to use `POST /identity/buckets` at all. You only need to use it if you're using the earlier version,`POST /v2/identity/map`.
18
+
If you're using the latest version (v3) of `POST /v3/identity/map`, you don't need to use `POST /identity/buckets` at all. You only need to use it if you're using the earlier version (v2) of`POST /v2/identity/map`.
19
19
20
-
If you're using the V2 version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see [Migration from V2 Identity Map](post-identity-map.md#migration-from-v2-identity-map).
20
+
If you're using the v2 version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see [Migration from v2 Identity Map](post-identity-map.md#migration-from-v2-identity-map).
Copy file name to clipboardExpand all lines: docs/endpoints/post-identity-map-v2.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,7 +20,7 @@ For details about the UID2 opt-out workflow and how users can opt out, see [User
20
20
This documentation is for version 2 of this endpoint, which is not the latest version. For the latest version, v3, see [POST /identity/map](post-identity-map.md).
21
21
22
22
:::note
23
-
If you're using the V2 version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see [Migration from V2 Identity Map](post-identity-map.md#migration-from-v2-identity-map).
23
+
If you're using the v2 version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see [Migration from v2 Identity Map](post-identity-map.md#migration-from-v2-identity-map).
24
24
:::
25
25
26
26
## Batch Size and Request Parallelization Requirements
-[Key Differences Between V2 and V3](#key-differences-between-v2-and-v3)
203
+
-[Key Differences Between v2 and v3](#key-differences-between-v2-and-v3)
204
204
-[Required Changes](#required-changes)
205
205
-[Additional Resources](#additional-resources)
206
206
207
207
### Version 3 Improvements
208
208
209
-
The V3 Identity Map API provides the following improvements over V2:
209
+
The v3 Identity Map API provides the following improvements over v2:
210
210
211
211
-**Simplified Refresh Management**: You can monitor for UID2s reaching `refresh_from` timestamps instead of polling <Linkhref="../ref-info/glossary-uid#gl-salt-bucket-id">salt buckets</Link> for rotation.
212
212
-**Previous UID2 Access**: You have access to previous raw UID2s for 90 days after rotation for campaign measurement.
213
213
-**Single Endpoint**: You use only one endpoint, `/v3/identity/map`, instead of both `/v2/identity/map` and `/v2/identity/buckets`.
214
214
-**Multiple Identity Types in One Request**: You can process both emails and phone numbers in a single request.
215
215
-**Improved Performance**: The updated version uses significantly less bandwidth to process the same amount of DII.
216
216
217
-
### Key Differences Between V2 and V3
217
+
### Key Differences Between v2 and v3
218
218
219
219
The following table shows key differences between the versions.
220
220
@@ -238,20 +238,20 @@ To upgrade from an earlier version to version 3, follow these steps:
238
238
Update any reference to the endpoint URL so that it references the /v3/ implementation, as shown in the following example.
239
239
240
240
```python
241
-
# Before (V2)
241
+
# Before (v2)
242
242
url ='/v2/identity/map'
243
243
244
-
# After (V3)
244
+
# After (v3)
245
245
url ='/v3/identity/map'
246
246
```
247
247
248
-
#### 2. Update V3 Response Parsing Logic
248
+
#### 2. Update v3 Response Parsing Logic
249
249
250
250
Update the logic for parsing the response, as shown in the following example.
251
251
252
252
V2 Response Parsing:
253
253
```python
254
-
#V2: Process mapped/unmapped objects with identifier lookup
254
+
#v2: Process mapped/unmapped objects with identifier lookup
255
255
for item in response['body']['mapped']:
256
256
raw_uid = item['advertising_id']
257
257
bucket_id = item['bucket_id']
@@ -262,7 +262,7 @@ for item in response['body']['mapped']:
262
262
263
263
V3 Response Parsing:
264
264
```python
265
-
#V3: Process array-indexed responses
265
+
#v3: Process array-indexed responses
266
266
for index, item inenumerate(response['body']['email']):
267
267
original_email = request_emails[index] # Use array index to correlate
Copy file name to clipboardExpand all lines: docs/endpoints/summary-endpoints.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,7 +26,7 @@ The following endpoints are for retrieving and managing UID2 tokens (identity to
26
26
27
27
The following endpoints are used by advertisers and third-party data providers. Publishers do not need to use these endpoints.
28
28
29
-
### Latest Identity Map Endpoint (V3)
29
+
### Latest Identity Map Endpoint (v3)
30
30
31
31
In the latest identity map integration, you only need to call one endpoint, `POST /identity/map`. The `POST /identity/buckets` endpoint is not part of the workflow.
32
32
@@ -40,7 +40,7 @@ The latest identity map integration uses the following endpoint:
40
40
| :--- | :--- | :--- | :--- |
41
41
|[POST /identity/map](post-identity-map.md)| Maps raw UID2s, previous raw UID2s, and refresh timestamps for one or more email addresses, phone numbers, or their respective hashes. | Required | Required |
42
42
43
-
### Earlier Identity Map Endpoints (V2)
43
+
### Earlier Identity Map Endpoints (v2)
44
44
45
45
The following endpoints are part of the earlier identity map integration (version 2).
Copy file name to clipboardExpand all lines: docs/getting-started/gs-faqs.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -187,7 +187,7 @@ To determine whether to refresh a raw UID2:
187
187
2. If the current time is greater than or equal to the refresh timestamp, regenerate the raw UID2 by calling the identity map endpoint again with the same <Linkhref="../ref-info/glossary-uid#gl-dii">DII</Link>.
188
188
189
189
:::note
190
-
We recommend checking for refresh opportunities daily. It is guaranteed that the raw UID2 won't refresh before the indicated timestamp. At some point after that time, the raw UID2 is refreshed.
190
+
We recommend checking for refresh opportunities daily. It is guaranteed that the raw UID2 won't refresh before the indicated timestamp. At some point on or after that time, the raw UID2 is refreshed.
191
191
:::
192
192
193
193
#### How often should raw UID2s be refreshed for incremental updates?
Copy file name to clipboardExpand all lines: docs/getting-started/gs-permissions.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,4 +27,4 @@ The following table lists the key permissions, the types of participants that co
27
27
| Generator | Publishers | Permission to call the [POST /token/generate](../endpoints/post-token-generate.md), [POST /token/validate](../endpoints/post-token-validate.md), and [POST /token/refresh](../endpoints/post-token-refresh.md) endpoints, to generate UID2 tokens from <Linkhref="../ref-info/glossary-uid#gl-dii">DII</Link> and to refresh them, using one of these integration methods:<ul><li>A Prebid integration</li><li>The SDK for JavaScript</li><li>An integration that directly calls the applicable API endpoints for retrieving and managing UID2 tokens.</li></ul> |
28
28
| Bidder | DSPs | Permission to decrypt UID2 tokens coming in from the <Linkhref="../ref-info/glossary-uid#gl-bidstream">bidstream</Link> from publishers into raw UID2s for bidding purposes. |
29
29
| Sharer | Any participant type that takes part in UID2 sharing. For details, see [UID2 Sharing: Overview](../sharing/sharing-overview.md). | Permission to do both of the following:<ul><li>Encrypt raw UID2s into UID2 tokens for sharing with another authorized sharing participant, using a UID2 SDK or Snowflake</li><li>Decrypt UID2 tokens received from another authorized sharing participant into raw UID2s.</li></ul> |
30
-
| Mapper | Advertisers<br/>Data Providers | Permission to call the following endpoints to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s, previous raw UID2s, and refresh timestamps:<ul><li>[POST /identity/map](../endpoints/post-identity-map.md) (latest version)</li><li>The earlier (version 2) identity mapping endpoints: [POST /identity/map (v2)](../endpoints/post-identity-map.md) and [POST /identity/buckets](../endpoints/post-identity-buckets.md).</li></ul> |
30
+
| Mapper | Advertisers<br/>Data Providers | Permission to call the following endpoints to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s, previous raw UID2s, and refresh timestamps:<ul><li>[POST /identity/map](../endpoints/post-identity-map.md) (latest version)</li><li>The earlier v2 identity mapping endpoints: [POST /identity/map (v2)](../endpoints/post-identity-map.md) and [POST /identity/buckets](../endpoints/post-identity-buckets.md).</li></ul> |
Copy file name to clipboardExpand all lines: docs/guides/integration-advertiser-dataprovider-endpoints.md
+8-8Lines changed: 8 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -95,7 +95,7 @@ You could also send conversion information via API or pixels for measurement (at
95
95
96
96
A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes roughly once per year as part of the UID2 refresh process.
97
97
98
-
The V3 Identity Map API provides a refresh timestamp (`r` field) in the response that indicates when each raw UID2 might refresh. Use this timestamp to determine when to regenerate raw UID2s for your stored data, it is guaranteed that it won't refresh before that time.
98
+
The v3 Identity Map API provides a refresh timestamp (`r` field) in the response that indicates when each raw UID2 might refresh. Use this timestamp to determine when to regenerate raw UID2s for your stored data, it is guaranteed that it won't refresh before that time.
99
99
100
100
We recommend checking for refresh opportunities daily. The following table shows the steps for monitoring raw UID2 refresh.
101
101
@@ -142,21 +142,21 @@ The following sections provide information about implementing an earlier version
142
142
143
143
### Earlier Versions: High-Level Steps
144
144
145
-
At a high level, the steps for advertisers and data providers integrating with UID2 using the `POST /v2/identity/map endpoint` are the same as for the current version, as shown in the following summary of steps. However, Step 2 and Step 5 are significantly different: for details, see [Integration Diagram (V2)](#integration-diagram-v2).
145
+
At a high level, the steps for advertisers and data providers integrating with UID2 using the `POST /v2/identity/map endpoint` are the same as for the current version, as shown in the following summary of steps. However, Step 2 and Step 5 are significantly different: for details, see [Integration Diagram (v2)](#integration-diagram-v2).
146
146
147
147
1.[Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii)
148
148
149
-
2.[Store Raw UID2s and Salt Bucket IDs (V2)](#store-raw-uid2s-and-salt-bucket-ids-v2)
149
+
2.[Store Raw UID2s and Salt Bucket IDs (v2)](#store-raw-uid2s-and-salt-bucket-ids-v2)
150
150
151
151
3.[Manipulate or Combine Raw UID2s](#3-manipulate-or-combine-raw-uid2s)
152
152
153
153
4.[Send Stored Raw UID2s to DSPs to Create Audiences or Conversions](#4-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions)
154
154
155
-
5.[Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (V2)](#monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2)
155
+
5.[Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (v2)](#monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2)
156
156
157
157
6.[Monitor for Opt-Out Status](#6-monitor-for-opt-out-status)
158
158
159
-
### Integration Diagram (V2)
159
+
### Integration Diagram (v2)
160
160
161
161
The following diagram outlines the steps that data collectors must complete to map DII to raw UID2s for audience building and targeting.
162
162
@@ -166,14 +166,14 @@ DII refers to a user's normalized email address or phone number, or the normaliz
The response from Step 1, [Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii), contains mapping information. We recommend that you store the following information returned in Step 1:
172
172
173
173
- Cache the mapping between DII (`identifier`), raw UID2 (`advertising_id`), and salt bucket (`bucket_id`).
174
-
- Store the timestamp for when you received the response data. Later, you can compare this timestamp with the `last_updated` timestamp returned in Step 5, [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (V2)](#monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2).
174
+
- Store the timestamp for when you received the response data. Later, you can compare this timestamp with the `last_updated` timestamp returned in Step 5, [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (v2)](#monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2).
175
175
176
-
### Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (V2)
176
+
### Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (v2)
177
177
178
178
A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes roughly once per year, as a result of the <Linkhref="../ref-info/glossary-uid#gl-salt-bucket">salt bucket</Link> rotation.
Copy file name to clipboardExpand all lines: docs/guides/integration-advertiser-dataprovider-overview.md
+10-10Lines changed: 10 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -121,7 +121,7 @@ You could also send conversion information via API or pixels for measurement (at
121
121
122
122
A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes roughly once per year as part of the UID2 refresh process.
123
123
124
-
The V3 Identity Map API provides a refresh timestamp (`r` field) in the response that indicates when each raw UID2 might refresh. Use this timestamp to determine when to regenerate raw UID2s for your stored data. It is guaranteed that it won't refresh before that time.
124
+
The v3 Identity Map API provides a refresh timestamp (`r` field) in the response that indicates when each raw UID2 might refresh. Use this timestamp to determine when to regenerate raw UID2s for your stored data. It is guaranteed that it won't refresh before that time.
125
125
126
126
We recommend checking for refresh opportunities daily. To determine whether to refresh a raw UID2:
127
127
@@ -173,11 +173,11 @@ At a high level, the steps for advertisers and data providers integrating with U
173
173
174
174
6.[Monitor for Opt-Out Status](#6-monitor-for-opt-out-status)
175
175
176
-
### Implementation Options (V2)
176
+
### Implementation Options (v2)
177
177
178
-
The implementation options that are available for advertisers and data providers are the same regardless of version. For details, see [Summary of Implementation Options](#summary-of-implementation-options). However, if you're using an implementation that uses the `POST /v2/identity/map` endpoint, Step 5 is different, as shown in [Integration Diagram (V2)](#integration-diagram-v2). For instructions for Step 5, see [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (V2)](#monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2).
178
+
The implementation options that are available for advertisers and data providers are the same regardless of version. For details, see [Summary of Implementation Options](#summary-of-implementation-options). However, if you're using an implementation that uses the `POST /v2/identity/map` endpoint, Step 5 is different, as shown in [Integration Diagram (v2)](#integration-diagram-v2). For instructions for Step 5, see [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (v2)](#monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2).
179
179
180
-
### Integration Diagram (V2)
180
+
### Integration Diagram (v2)
181
181
182
182
The following diagram outlines the steps that data collectors must complete to map DII to raw UID2s for audience building and targeting.
183
183
@@ -189,16 +189,16 @@ To keep your UID2-based audience information accurate and up to date, follow the
For details about the different parts of the diagram, refer to [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (V2)](#monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2) for Step 5, or [Summary of Implementation Options](#summary-of-implementation-options) for all other steps.
192
+
For details about the different parts of the diagram, refer to [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (v2)](#monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2) for Step 5, or [Summary of Implementation Options](#summary-of-implementation-options) for all other steps.
193
193
194
-
### Store Raw UID2s and Salt Bucket IDs (V2)
194
+
### Store Raw UID2s and Salt Bucket IDs (v2)
195
195
196
196
The response from Step 1, [Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii), contains mapping information. We recommend that you store the following information returned in Step 1:
197
197
198
198
- Cache the mapping between DII (`identifier`), raw UID2 (`advertising_id`), and salt bucket (`bucket_id`).
199
-
- Store the timestamp for when you received the response data. Later, you can compare this timestamp with the `last_updated` timestamp returned in Step 5, [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (V2)](#monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2).
199
+
- Store the timestamp for when you received the response data. Later, you can compare this timestamp with the `last_updated` timestamp returned in Step 5, [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (v2)](#monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2).
200
200
201
-
### Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (V2)
201
+
### Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (v2)
202
202
203
203
A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes roughly once per year, as a result of the <Linkhref="../ref-info/glossary-uid#gl-salt-bucket">salt bucket</Link> rotation.
204
204
@@ -212,13 +212,13 @@ For instructions for monitoring for salt bucket rotations, refer to one of the f
212
212
213
213
- Snowflake: [Monitor for Salt Bucket Rotation and Regenerate Raw UID2s](integration-snowflake.md#monitor-for-salt-bucket-rotation-and-regenerate-raw-uid2s).
214
214
215
-
- HTTP endpoints: [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (V2)](integration-advertiser-dataprovider-endpoints.md#monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2).
215
+
- HTTP endpoints: [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (v2)](integration-advertiser-dataprovider-endpoints.md#monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2).
216
216
217
217
:::note
218
218
For AWS Entity Resolution, there is no way to do salt bucket monitoring. As an alternative, you could regenerate raw UID2s periodically using the AWS Entity Resolution service.
219
219
:::
220
220
221
-
##### Determine whether the salt bucket has been rotated (V2)
221
+
##### Determine whether the salt bucket has been rotated (v2)
222
222
223
223
To determine whether the salt bucket ID for a specific raw UID2 has changed, follow these steps.
0 commit comments