diff --git a/docs/endpoints/post-identity-map-v3.md b/docs/endpoints/post-identity-map-v3.md index 0d7a977b0..46755e7c2 100644 --- a/docs/endpoints/post-identity-map-v3.md +++ b/docs/endpoints/post-identity-map-v3.md @@ -122,10 +122,10 @@ Input: ```json { "email": [ - "user@example.com" // Corresponding UID2 rotated in the last 90 days - "user2@example.com" // Corresponding UID2 rotated more than 90 days ago - "invalid email string" // Invalid identifier - "optout@example.com" // DII is opted out + "user@example.com", // Corresponding UID2 rotated in the last 90 days + "user2@example.com", // Corresponding UID2 rotated more than 90 days ago + "invalid email string", // Invalid identifier + "optout@example.com" // DII is opted out ] } ``` @@ -175,7 +175,7 @@ For successfully mapped DII, the mapped object includes the properties shown in |:---------|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------| | `u` | string | The raw UID2 corresponding to the email or phone number provided in the request. | | `p` | string | One of the following: | -| `r` | number | The Unix timestamp (in milliseconds) that indicates when the raw UID2 can be refreshed. | +| `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. | For unsuccessfully mapped input values, the mapped object includes the properties shown in the following table. diff --git a/docs/getting-started/gs-faqs.md b/docs/getting-started/gs-faqs.md index 45d310de6..8fd70432b 100644 --- a/docs/getting-started/gs-faqs.md +++ b/docs/getting-started/gs-faqs.md @@ -46,7 +46,7 @@ Yes. Through the [Transparency and Control Portal](https://www.transparentadvert No. None of the components of the UID2 service store any DII. -In addition, in almost all cases, UID2 doesn't store any values at all once the [POST /token/generate](../endpoints/post-token-generate.md), [POST /token/refresh](../endpoints/post-token-refresh.md), or [POST /identity/map](../endpoints/post-identity-map.md) call is complete. A necessary exception is the case where a user has opted out. In this scenario, UID2 stores a hashed, opaque value to indicate the opted-out user. The stored value cannot be reverse engineered back to the original value of the DII, but can be used to identify future requests for a UID2 generated from the same DII, which are therefore denied. +In addition, in almost all cases, UID2 doesn't store any values at all once the [POST /token/generate](../endpoints/post-token-generate.md), [POST /token/refresh](../endpoints/post-token-refresh.md), or [POST /identity/map](../endpoints/post-identity-map-v3.md) call is complete. A necessary exception is the case where a user has opted out. In this scenario, UID2 stores a hashed, opaque value to indicate the opted-out user. The stored value cannot be reverse engineered back to the original value of the DII, but can be used to identify future requests for a UID2 generated from the same DII, which are therefore denied. #### Does UID2 allow the processing of HIPAA-regulated data? @@ -166,36 +166,35 @@ For details, see [Publisher Integration with SSO Providers](/docs/ref-info/ref-i Here are some frequently asked questions for advertisers and data providers using the UID2 framework. -- [How do I know when to refresh the UID2 due to salt bucket rotation?](#how-do-i-know-when-to-refresh-the-uid2-due-to-salt-bucket-rotation) -- [Do refreshed emails get assigned to the same bucket with which they were previously associated?](#do-refreshed-emails-get-assigned-to-the-same-bucket-with-which-they-were-previously-associated) -- [How often should UID2s be refreshed for incremental updates?](#how-often-should-uid2s-be-refreshed-for-incremental-updates) +- [How do I know when to refresh a raw UID2?](#how-do-i-know-when-to-refresh-a-raw-uid2) +- [How often should raw UID2s be refreshed for incremental updates?](#how-often-should-raw-uid2s-be-refreshed-for-incremental-updates) - [How should I generate the SHA-256 of DII for mapping?](#how-should-i-generate-the-sha-256-of-dii-for-mapping) - [Should I store mapping of email addresses, phone numbers, or corresponding hashes to raw UID2s in my own datasets?](#should-i-store-mapping-of-email-addresses-phone-numbers-or-corresponding-hashes-to-raw-uid2s-in-my-own-datasets) - [How should I handle user opt-outs?](#how-should-i-handle-user-opt-outs) - [Does the same DII always result in the same raw UID2?](#does-the-same-dii-always-result-in-the-same-raw-uid2) - [If two operators process the same DII, are the results the same?](#if-two-operators-process-the-same-dii-are-the-results-the-same) +- [How do I know when to refresh the UID2 due to salt bucket rotation?](#how-do-i-know-when-to-refresh-the-uid2-due-to-salt-bucket-rotation) +- [Do refreshed emails get assigned to the same bucket with which they were previously associated?](#do-refreshed-emails-get-assigned-to-the-same-bucket-with-which-they-were-previously-associated) +- [How often should Raw UID2s be refreshed for incremental updates older buckets-based flow?](#how-often-should-raw-uid2s-be-refreshed-for-incremental-updates-older-buckets-based-flow) -#### How do I know when to refresh the UID2 due to salt bucket rotation? - -Metadata supplied with the UID2 generation request indicates the salt bucket used for generating the UID2. Salt buckets persist and correspond to the underlying DII used to generate a UID2. Use the [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoint to return which salt buckets rotated since a given timestamp. The returned rotated salt buckets inform you which UID2s to refresh. +#### How do I know when to refresh a raw UID2? -:::note -We do not make any promises about when the rotation takes place. To stay as up-to-date as possible, we recommend doing the checks once per hour. -::: +The [POST /identity/map](../endpoints/post-identity-map-v3.md) endpoint provides a refresh timestamp in the response (`r` field) that indicates a timestamp, after which each raw UID2 might refresh. Use this timestamp to determine when to regenerate raw UID2s for your stored data. -#### Do refreshed emails get assigned to the same bucket with which they were previously associated? +To determine whether to refresh a raw UID2: -Not necessarily. After you remap emails associated with a particular bucket ID, the emails might be assigned to a different bucket ID. To check the bucket ID, see [Generate Raw UID2s from DII](../guides/integration-advertiser-dataprovider-overview.md#1-generate-raw-uid2s-from-dii) and save the returned raw UID2 and bucket ID again. +1. Compare the current time with the refresh timestamp you stored from the [POST /identity/map](../endpoints/post-identity-map-v3.md) response. +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 DII. -:::info -When mapping and remapping emails, do not make any assumptions about the number of buckets, their rotation dates, or the specific bucket that an email gets assigned to. +:::note +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. ::: -#### How often should UID2s be refreshed for incremental updates? +#### How often should raw UID2s be refreshed for incremental updates? The recommended cadence for updating audiences is daily. -Even though each salt bucket is updated roughly once a year, individual bucket updates are spread over the year. This means that about 1/365th of all buckets are rotated daily. If fidelity is critical, consider calling the [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoint more frequently; for example, hourly. +A raw UID2 for a specific user changes at least once per year. The V3 Identity Map API provides refresh timestamps that indicate a point after which each raw UID2 might refresh. We recommend checking these timestamps daily to ensure your raw UID2s remain current and valid for audience targeting. #### How should I generate the SHA-256 of DII for mapping? @@ -203,7 +202,7 @@ The system should follow the [email normalization rules](gs-normalization-encodi #### Should I store mapping of email addresses, phone numbers, or corresponding hashes to raw UID2s in my own datasets? -Yes. Not storing mappings may 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. +Yes. Not storing mappings might 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 raw UID2s need to be updated daily. :::important Unless you are using a Private Operator, you must map email addresses, phone numbers, or hashes consecutively, using a single HTTP connection, with a maximum batch size of 5,000 items per batch. In other words, do your mapping without creating multiple parallel connections. @@ -211,7 +210,7 @@ Unless you are using a salt value that's used in generating the raw UID2. The salt values are rotated roughly once per year (for details, see [How often should UID2s be refreshed for incremental updates?](#how-often-should-uid2s-be-refreshed-for-incremental-updates)). If the salt value changes between one request and another, those two requests result in two different raw UID2, even when the DII is the same. +However, there is a variable factor that's used in generating the raw UID2. The underlying values are refreshed roughly once per year (for details, see [How often should UID2s be refreshed for incremental updates?](#how-often-should-uid2s-be-refreshed-for-incremental-updates)). If these values change between one request and another, those two requests result in two different raw UID2, even when the DII is the same. -For more information, see [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s](../guides/integration-advertiser-dataprovider-overview.md#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s) in the *Advertiser/Data Provider Integration Guide*. +For more information, see [Monitor for Raw UID2 Refresh](../guides/integration-advertiser-dataprovider-overview.md#5-monitor-for-raw-uid2-refresh) in the *Advertiser/Data Provider Integration Guide*. #### If two operators process the same DII, are the results the same? -Yes, if the request is for a raw UID2. As covered in the previous FAQ, [Does the same DII always result in the same raw UID2?](#does-the-same-dii-always-result-in-the-same-raw-uid2), if an advertiser or data provider sends the same DII to the UID2 Operator, by using an SDK or the [POST /identity/map](../endpoints/post-identity-map.md) endpoint, at the same time, the same raw UID2 is created. +Yes, if the request is for a raw UID2. As covered in the previous FAQ, [Does the same DII always result in the same raw UID2?](#does-the-same-dii-always-result-in-the-same-raw-uid2), if an advertiser or data provider sends the same DII to the UID2 Operator, by using an SDK or the [POST /identity/map](../endpoints/post-identity-map-v3.md) endpoint, at the same time, the same raw UID2 is created. The result is the same, regardless of the Operator and whether it's a Private Operator or a Public Operator. -The timing is important only because of salt bucket rotation. If the salt value changes between one request and another, the result is a different raw UID2. +The timing is important only because of refresh cycles. If the underlying values change between one request and another, the result is a different raw UID2. However, if a publisher sends DII in a request for a UID2 token, via the [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint or via an SDK, the resulting UID2 token contains the same encrypted raw UID2, but the token itself is always unique. +#### How do I know when to refresh the UID2 due to salt bucket rotation? + +Metadata supplied with the UID2 generation request indicates the salt bucket used for generating the UID2. Salt buckets persist and correspond to the underlying DII used to generate a UID2. Use the [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoint to return which salt buckets rotated since a given timestamp. The returned rotated salt buckets inform you which UID2s to refresh. + +:::note +We do not make any promises about when the rotation takes place. To stay as up-to-date as possible, we recommend doing the checks once per hour. +::: + +#### Do refreshed emails get assigned to the same bucket with which they were previously associated? + +Not necessarily. After you remap emails associated with a particular bucket ID, the emails might be assigned to a different bucket ID. To check the bucket ID, see [Generate Raw UID2s from DII](../guides/integration-advertiser-dataprovider-overview.md#1-generate-raw-uid2s-from-dii) and save the returned raw UID2 and bucket ID again. + +:::info +When mapping and remapping emails, do not make any assumptions about the number of buckets, their rotation dates, or the specific bucket that an email gets assigned to. +::: + +#### How often should Raw UID2s be refreshed for incremental updates older buckets-based flow? + +The recommended cadence for updating audiences is daily. + +Even though each salt bucket is updated roughly once a year, individual bucket updates are spread over the year. This means that about 1/365th of all buckets are rotated daily. If fidelity is critical, consider calling the [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoint more frequently; for example, hourly. + + ## FAQs for DSPs Here are some frequently asked questions for demand-side platforms (DSPs). @@ -242,7 +264,7 @@ Here are some frequently asked questions for demand-side platforms (DSPs). - [How do I know which decryption key to apply to a UID2?](#how-do-i-know-which-decryption-key-to-apply-to-a-uid2) - [Where do I get the decryption keys?](#where-do-i-get-the-decryption-keys) - [How many decryption keys may be present in memory at any point?](#how-many-decryption-keys-may-be-present-in-memory-at-any-point) -- [How do I know if/when the salt bucket has rotated?](#how-do-i-know-ifwhen-the-salt-bucket-has-rotated) +- [How do I know when to refresh mapped raw UID2s?](#how-do-i-know-when-to-refresh-mapped-raw-uid2s) - [Should the DSP be concerned with latency?](#should-the-dsp-be-concerned-with-latency) - [How should the DSP maintain proper frequency capping with UID2?](#how-should-the-dsp-maintain-proper-frequency-capping-with-uid2) - [Will all user opt-out traffic be sent to the DSP?](#will-all-user-opt-out-traffic-be-sent-to-the-dsp) @@ -267,9 +289,13 @@ You can use one of the server-side SDKs (see [SDKs: Summary](../sdks/summary-sdk There may be thousands of decryption keys present in the system at any given point. -#### How do I know if/when the salt bucket has rotated? +#### How do I know when to refresh mapped raw UID2s? + +See [Advertisers and Data Providers section](#how-do-i-know-when-to-refresh-a-raw-uid2). + +#### How do I know if/when the raw UID2 has rotated? -The DSP is not privy to when the UID2 salt bucket rotates. This is similar to a DSP being unaware if users cleared their cookies. Salt bucket rotation has no significant impact on the DSP. +The DSP is not privy to when the raw UID2 rotates. This is similar to a DSP being unaware if users cleared their cookies. Raw UID2 rotation has no significant impact on the DSP. #### Should the DSP be concerned with latency? @@ -277,7 +303,7 @@ The UID2 service does not introduce latency into the bidding process. Any latenc #### How should the DSP maintain proper frequency capping with UID2? -The UID2 has the same chance as a cookie of becoming stale. Hence, the DSP can adapt the same infrastructure currently used for cookie or deviceID-based frequency capping for UID2. For details, see [How do I know when to refresh the UID2 due to salt bucket rotation?](#how-do-i-know-when-to-refresh-the-uid2-due-to-salt-bucket-rotation). +The UID2 has the same chance as a cookie of becoming stale. Hence, the DSP can adapt the same infrastructure currently used for cookie or deviceID-based frequency capping for UID2. For details, see [How do I know when to refresh a raw UID2?](#how-do-i-know-when-to-refresh-a-raw-uid2). #### Will all user opt-out traffic be sent to the DSP? diff --git a/docs/guides/images/advertiser-flow-endpoints-mermaid-v3.png b/docs/guides/images/advertiser-flow-endpoints-mermaid-v3.png new file mode 100644 index 000000000..55f704a3e Binary files /dev/null and b/docs/guides/images/advertiser-flow-endpoints-mermaid-v3.png differ diff --git a/docs/guides/images/advertiser-flow-overview-mermaid-v3.png b/docs/guides/images/advertiser-flow-overview-mermaid-v3.png new file mode 100644 index 000000000..f793720f3 Binary files /dev/null and b/docs/guides/images/advertiser-flow-overview-mermaid-v3.png differ diff --git a/docs/guides/images/resource/advertiser-flow-endpoints-mermaid.md.bak b/docs/guides/images/resource/advertiser-flow-endpoints-v2-mermaid.md.bak similarity index 99% rename from docs/guides/images/resource/advertiser-flow-endpoints-mermaid.md.bak rename to docs/guides/images/resource/advertiser-flow-endpoints-v2-mermaid.md.bak index 6223664e3..d26caabf0 100644 --- a/docs/guides/images/resource/advertiser-flow-endpoints-mermaid.md.bak +++ b/docs/guides/images/resource/advertiser-flow-endpoints-v2-mermaid.md.bak @@ -1,4 +1,4 @@ ->DSP: Send stored raw UID2s to DSPs to create audiences and conversions, or use them for measurement. + Note over ADP,DSP: 5. Monitor for raw UID2 refresh. + loop + ADP->>ADP: 5-a. Check current time against stored refresh timestamps. + ADP->>UID: 5-b. If refresh time reached, resend DII to the POST /identity/map endpoint for updated raw UID2. + UID->>ADP: 5-c. Store the new raw UID2 (u), refresh timestamp (r), and optionally previous UID2 (p) returned from the POST /identity/map endpoint. + end + Note over ADP,DSP: 6. Monitor for opt-out status. Remove all opt-outs from local storage and do not use. + loop + ADP->>UID: 6-a. Monitor for optout status using the POST /optout/status endpoint. + UID->>ADP: 6-b. Return optout status. + end + +%%URL: +%%https://mermaid.live/edit#pako:eNrNVU1v2kAQ_SujPSUSGDDYgA-RolBVHNKg0F4qLht7gFXxrrsfSWmU_97ZNeYjASnH-oDZ3Zk3b948rV9ZrgpkGQMw-NuhzHEi-ErzciGBnoprK3JRcWnhdjIDbuC2eEbaNKg7E245zLR6FgXqjwk_phOfQK8YHirU3KozUZP5rN78piyCInBfqUXbGfQi-IrSZyJo_hKgDCy1KmEynYIzQq7ArhGIgLTCbqHkFaAsKiWkjWpc_2yUqqBeEnj75oaQCL7NI5hTOHDQvn1jIVfSciE9sC9hVcCfPcy_Q6ep0jlThQAJlsA97BPBUrMYchvicOWuW1RnqdGswYqSyvGygitN25xIqMoKJflms4VK47NQbifeVXVNedZpiUXd_ec40fKitHFD8aCr5_CBnokuQvQjuOdSVG7j56M0aVc-CXkE2UzgTPJgp_yhPElNJ02OHxMJGmJDoPFsz8T7d67RU-CuEN7CdSs0SapoSFLT8uycCfMoYUmLErlxGkvci3WGY0INKimocMjZD3In0i7Re2vvtNpdwQaJd9fdGvNfkDutqVJQFfiK_EVOaxq6pPipVxNvqunyJJwWPF9j4V1lvEafc2xoxlUFSXbQ81D0yMlJOz92ssSX_9TN6emkqHZbOS8xt85E8IglxQORaY52t8hG5XwTJsFXGGgXCqSy3iyXxxsGkvrxvit6qHl0N9Wd1aed3enHK-pI9dSP-jEodAr6Xojml7XYSouCZVY7bLESdcn9kr36iAXzrscFy-gvEaVBLdhCvlEWXcA_lSqbRK3cas2yJd8YWtUO2X0O9rvcWTXfyrzJqaO-FF6GfRCG5X39aQlfmFCLZa_sD8t6vW6UxINBPOyP416aDvsttmXZoJ9ESTKIR6M0jodJmvTfWuxvoNeNRoNxf9BNe8M0SYfd4YjIkgyo75STlmXjt38Vsi5b \ No newline at end of file diff --git a/docs/guides/images/resource/advertiser-flow-overview-mermaid.md.bak b/docs/guides/images/resource/advertiser-flow-overview-v2-mermaid.md.bak similarity index 100% rename from docs/guides/images/resource/advertiser-flow-overview-mermaid.md.bak rename to docs/guides/images/resource/advertiser-flow-overview-v2-mermaid.md.bak diff --git a/docs/guides/images/resource/advertiser-flow-overview-v3-mermaid.mermaid b/docs/guides/images/resource/advertiser-flow-overview-v3-mermaid.mermaid new file mode 100644 index 000000000..a1e32049c --- /dev/null +++ b/docs/guides/images/resource/advertiser-flow-overview-v3-mermaid.mermaid @@ -0,0 +1,29 @@ +%%26/6/25: V3 API Update - Updated diagram to use V3 identity map API with refresh timestamps instead of salt bucket monitoring. + + sequenceDiagram + participant ADP as Advertiser/Data Provider + participant UID as UID2 Operator + participant DSP + Note over ADP,DSP: 1. Generate raw UID2s from DII. + loop + ADP->>UID: 1-a. Send a request containing DII using an SDK, Snowflake, AWS Entity Resolution, or HTTP endpoint. + UID->>ADP: 1-b. Receive the raw UID2 (u), refresh timestamp (r), and optionally previous UID2 (p). + end + Note over ADP,DSP: 2. Store raw UID2s and refresh timestamps. + Note over ADP,DSP: 3. Manipulate or combine raw UID2s. + Note over ADP,DSP: 4. Send raw UID2s to DSPs. + ADP-->>DSP: Send stored raw UID2s to DSPs to create audiences and conversions, or use them for measurement. + Note over ADP,DSP: 5. Monitor for raw UID2 refresh. + loop + ADP->>ADP: 5-a. Check current time against stored refresh timestamps. + ADP->>UID: 5-b. If refresh time reached, resend DII to get updated raw UID2. + UID->>ADP: 5-c. Store the new raw UID2, refresh timestamp, and optionally previous UID2. + end + Note over ADP,DSP: 6. Monitor for opt-out status. Remove all opt-outs from local storage and do not use. + loop + ADP->>UID: 6-a. Monitor for optout status using the POST optout/status endpoint. + UID->>ADP: 6-b. Return optout status. + end + +%% URL: +%% https://mermaid.live/edit#pako:eNqNVF1v2kAQ_Cure0ok44DBhvghUhSiFlVpUElVqeLlYh9win3n3gcpjfLfu2sbCAlU9Yt9552d3dm5e2GZzgVLGYAVv7xQmRhLvjS8nCvAp-LGyUxWXDm4Hk-BW7jO1wI3rTAXY-44TI1ey1yYj4DvkzEB8BXBfSUMd_pI1Hg2bTa_aidAY3JiCnA7hV4In4QipADDn-tUFhZGlzCeTMIGR0-hdQXNEsGdqyuMRHiHhzATKgcOhtqzDjKtHJdKqiWlAG_piyuYjb8EMFP6eVHwJxHA9Y8Z3Con3Qa-CasL76RWAWgDnx8epoBJKy2Va2tAOiRFaiJ9DBGSCbkW4Fb7wuHMnwdYx8IIuwInSyyHlxWcGdzmWKSuiIMXxQYqI9ZS-1a8s-q85UHak2JF2Csq_FYpyvqB0IYnU_RDuONKVr4gxbHXTJePUr1JudX8CHjQar2nd5qmu8XQYFCkOrYOtFTtkXh6Z0ZQCdznkkzZtIKzQ0aLItl6Et7WCpewwEUpuPVGlGI3lCM1xtigVhKJa8xuNK1ILZDctPNW46d6tDH56WYlsifIvDHIVKsKfImOQm9tGzql-KE7YzLKZHEQjguerUROPrGkEXkU5VgKB77KUZK9Xvukb9wXd7KtDch7Sjzv4o9479---w_PJYd6YqaO9iQEd97SMSgxHjD19ld7egud8aLWiy9FXUSuQWlHIz09hFq2hIbwjnTP2R5o6n16P3tof160P9-d2kPpkubgOm_UYc69DixgSyNzljrjRcBKYUpOS_ZCIXNGZhRzluInVoYaz9lcvSIKb7qfWpdboNF-uWLpghcWV81g23t3t8u907ONyraYJuo2p753QaJe3jV3eH2V11wsfWG_WdrrdcM4GgyiYf8y6iXJsB-wDUsH_TiM40E0GiVRNIyTuP8asD91ed1wNLjsD7pJb5jEybA7HGGx2LgwN9orhyn7r38BOSL5zQ \ No newline at end of file diff --git a/docs/guides/integration-advertiser-dataprovider-endpoints.md b/docs/guides/integration-advertiser-dataprovider-endpoints.md index fc5d2eb30..c600eaf3a 100644 --- a/docs/guides/integration-advertiser-dataprovider-endpoints.md +++ b/docs/guides/integration-advertiser-dataprovider-endpoints.md @@ -38,6 +38,133 @@ At a high level, the steps for advertisers and data providers integrating with U 1. [Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) +2. [Store Raw UID2s and Refresh Timestamps](#2-store-raw-uid2s-and-refresh-timestamps) + +3. [Manipulate or Combine Raw UID2s](#3-manipulate-or-combine-raw-uid2s) + +4. [Send Stored Raw UID2s to DSPs to Create Audiences or Conversions](#4-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) + +5. [Monitor for Raw UID2 Refresh](#5-monitor-for-raw-uid2-refresh) + +6. [Monitor for Opt-Out Status](#6-monitor-for-opt-out-status) + +## Integration Diagram + +The following diagram outlines the steps that data collectors must complete to map DII to raw UID2s for audience building and targeting. + +DII refers to a user's normalized email address or phone number, or the normalized and SHA-256-hashed email address or phone number. + +![Advertiser Flow](images/advertiser-flow-endpoints-mermaid-v3.png) + + + +### 1: Generate Raw UID2s from DII + +| Step | Endpoint | Description | +| --- | --- | --- | +| 1-a | [POST /identity/map](../endpoints/post-identity-map-v3.md) request | Send a request containing DII to the identity mapping endpoint. | +| 1-b | [POST /identity/map](../endpoints/post-identity-map-v3.md) response | The raw UID2 (`u` field) returned in the response can be used to target audiences on relevant DSPs.
The response returns a user's raw UID2 (`u`), refresh timestamp (`r`), and optionally the previous raw UID2 (`p`) if the current UID2 was rotated within the last 90 days. Use the refresh timestamp to determine when to refresh the UID2. For details, see [5: Monitor for Raw UID2 Refresh](#5-monitor-for-raw-uid2-refresh). | + + +### 2: Store Raw UID2s and Refresh Timestamps + +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: + +- Cache the mapping between DII and raw UID2 (`u` field). +- Store the refresh timestamp (`r` field) to know when the raw UID2 could refresh. +- Optionally store the previous raw UID2 (`p` field) if provided for users whose UID2 was refreshed within the last 90 days. + +### 3: Manipulate or Combine Raw UID2s + +Use the UID2s you received in Step 1. For example, you might do one or more of the following: + +- Do some manipulation: for example, combine Raw UID2s you generated from DII and Raw UID2s received from another participant such as an advertiser or data provider. +- Add new Raw UID2s into an existing audience. + +### 4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions + +Use the raw UID2s for some purpose such as: + + - Sending stored raw UID2s to DSPs to create audiences and conversions. + - Using the raw UID2s for measurement. + +For example, you could send the (raw UID2) (`u` field) returned in Step 1-b to a DSP while building your audiences. Each DSP has a unique integration process for building audiences; follow the integration guidance provided by the DSP for sending raw UID2s to build an audience. + +You could also send conversion information via API or pixels for measurement (attribution) or for retargeting. + +### 5: Monitor for Raw UID2 Refresh + +A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes at least once per year as part of the UID2 refresh process. + +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. + +We recommend checking for refresh opportunities daily. The following table shows the steps for monitoring raw UID2 refresh. + +| Step | Action | Description | +| :--- | :--- | :--- | +| 5-a | Local timestamp check | Compare the current time with the refresh timestamp (`r` field) you stored from the [POST /identity/map](../endpoints/post-identity-map-v3.md) response previously. | +| 5-b | [POST /identity/map](../endpoints/post-identity-map-v3.md) | 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 DII. | +| 5-c | Local storage update | Store the new raw UID2 (`u` field), refresh timestamp (`r` field) and optionally previous UID2 (`p` field) returned from the response. | + +#### Determine whether to refresh a raw UID2 + +To determine whether to refresh a raw UID2, follow these steps: + +1. Compare the current time with the refresh timestamp (`r` field) you stored from the [POST /identity/map](../endpoints/post-identity-map-v3.md) response. + +2. If the current time is greater than or equal to the refresh timestamp, regenerate the raw UID2 by calling [POST /identity/map](../endpoints/post-identity-map-v3.md) again with the same DII. + +This approach ensures your Raw UID2s remain current and valid for audience targeting and measurement. + +### 6: Monitor for Opt-Out Status + +It's important to honor user opt-out status. Periodically, monitor for opt-out status, to be sure that you don't continue using Raw UID2s for users that have recently opted out. + +There are two ways that you can check with the UID2 Operator Service to make sure you have the latest opt-out information: + +- Call the [POST /identity/map](../endpoints/post-identity-map-v3.md) endpoint to check for opt-outs. If the DII has been opted out, no raw UID2 is generated. + +- Check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. + +For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md). + +--- + +# For Users of Older SDK/API Version + +:::warning +The following information is relevant to the older integration approach and is provided for reference only. New implementations should use the main approach described above. For current best practices, refer to the [main integration guide](#high-level-steps). +::: + +## Advertiser/Data Provider Integration to HTTP Endpoints + +This guide covers integration steps for advertisers and data providers to integrate with UID2 by writing code to call UID2 HTTP endpoints, rather than using another implementation option such as an SDK, Snowflake, or AWS Entity Resolution. + +:::tip +For a summary of all integration options and steps for advertisers and data providers, see [Advertiser/Data Provider Integration Overview](integration-advertiser-dataprovider-overview.md). +::: + +### Complete UID2 Account Setup and Configure Account + +To integrate with UID2, you'll need to have a UID2 account. If you haven't yet created an account, first follow the steps described on the [Account Setup](../getting-started/gs-account-setup.md) page. + +When initial account setup is complete, you'll receive instructions and a link to access the [UID2 Portal](../portal/portal-overview.md), where you can create your [credentials](../getting-started/gs-credentials.md) for the production environment and configure additional values, if needed. For details, see [Getting Started with the UID2 Portal](../portal/portal-getting-started.md). + +You'll need to set up these values, in the UID2 Portal on the [API Keys](../portal/api-keys.md) page: + +- API key, also called a client key +- Client secret, a value known only to the participant and the UID2 service + +:::important +It's very important that you keep these values secure. For details, see [Security of API Key and Client Secret](../getting-started/gs-credentials.md#security-of-api-key-and-client-secret). +::: + +### High-Level Steps + +At a high level, the steps for advertisers and data providers integrating with UID2 are as follows: + +1. [Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) + 2. [Store Raw UID2s and Salt Bucket IDs](#2-store-raw-uid2s-and-salt-bucket-ids) 3. [Manipulate or Combine Raw UID2s](#3-manipulate-or-combine-raw-uid2s) @@ -48,7 +175,7 @@ At a high level, the steps for advertisers and data providers integrating with U 6. [Monitor for Opt-Out Status](#6-monitor-for-opt-out-status) -## Integration Diagram +### Integration Diagram The following diagram outlines the steps that data collectors must complete to map DII to raw UID2s for audience building and targeting. @@ -56,44 +183,44 @@ DII refers to a user's normalized email address or phone number, or the normaliz ![Advertiser Flow](images/advertiser-flow-endpoints-mermaid.png) - + -### 1: Generate Raw UID2s from DII +#### 1: Generate Raw UID2s from DII | Step | Endpoint | Description | | --- | --- | --- | -| 1-a | [POST /identity/map (v2)](../endpoints/post-identity-map.md) request | Send a request containing DII to the identity mapping endpoint. | -| 1-b | [POST /identity/map (v2)](../endpoints/post-identity-map.md) response | The `advertising_id` (raw UID2) returned in the response can be used to target audiences on relevant DSPs.
The response returns a user's raw UID2 and the corresponding `bucket_id` for the salt bucket. The salt assigned to the bucket rotates annually, which impacts the generated raw UID2. For details on how to check for salt bucket rotation, see [5: Monitor for salt bucket rotations related to your stored raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s). | +| 1-a | [POST /identity/map](../endpoints/post-identity-map.md) request | Send a request containing DII to the identity mapping endpoint. | +| 1-b | [POST /identity/map](../endpoints/post-identity-map.md) response | The `advertising_id` (raw UID2) returned in the response can be used to target audiences on relevant DSPs.
The response returns a user's raw UID2 and the corresponding `bucket_id` for the salt bucket. The salt assigned to the bucket rotates annually, which impacts the generated raw UID2. For details on how to check for salt bucket rotation, see [5: Monitor for salt bucket rotations related to your stored raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s). | -### 2: Store Raw UID2s and Salt Bucket IDs +#### 2: Store Raw UID2s and Salt Bucket IDs 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: - Cache the mapping between DII (`identifier`), raw UID2 (`advertising_id`), and salt bucket (`bucket_id`). - 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](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s). -### 3: Manipulate or Combine Raw UID2s +#### 3: Manipulate or Combine Raw UID2s Use the UID2s you received in Step 1. For example, you might do one or more of the following: - Do some manipulation: for example, combine UID2s you generated from DII and UID2s received from another participant such as an advertiser or data provider. - Add new UID2s into an existing audience. -### 4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions +#### 4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions Use the raw UID2s for some purpose such as: - - Sending stored raw UID2s to DSPs to create audiences and conversions. - - Using the raw UID2s for measurement. +- Sending stored raw UID2s to DSPs to create audiences and conversions. +- Using the raw UID2s for measurement. For example, you could send the `advertising_id` (raw UID2) returned in Step 1-b to a DSP while building your audiences. Each DSP has a unique integration process for building audiences; follow the integration guidance provided by the DSP for sending raw UID2s to build an audience. You could also send conversion information via API or pixels for measurement (attribution) or for retargeting. -### 5: Monitor for Salt Bucket Rotations for Your Stored Raw UID2s +#### 5: Monitor for Salt Bucket Rotations for Your Stored Raw UID2s -A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes at least once per year, as a result of the salt bucket rotation. +A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes at least once per year, as a result of the salt bucket rotation. Even though each salt bucket is updated approximately once per year, individual bucket updates are spread over the year. Approximately 1/365th of all salt buckets are rotated daily. Based on this, we recommend checking salt bucket rotation regularly, on a cadence that aligns with your audience refreshes. For example, if you refresh weekly, check for salt bucket updates weekly. @@ -105,29 +232,29 @@ The following table shows the steps for checking for salt bucket rotation. | --- | --- | --- | | 5-a | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | Send a request to the `POST /identity/buckets` endpoint for all salt buckets that have changed since a specific timestamp. | | 5-b | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | UID2 service: The `POST /identity/buckets` endpoint returns a list of `bucket_id` and `last_updated` timestamps. | -| 5-c | [POST /identity/map (v2)](../endpoints/post-identity-map.md) | Compare the returned `bucket_id` to the salt buckets of raw UID2s that you've cached.
If you find that the salt bucket was updated for one or more raw UID2s, re-send the DII to the `POST /identity/map (v2)` endpoint for a new raw UID2. | -| 5-d | [POST /identity/map (v2)](../endpoints/post-identity-map.md) | Store the new values returned for `advertising_id` and `bucket_id`. | +| 5-c | [POST /identity/map](../endpoints/post-identity-map.md) | Compare the returned `bucket_id` to the salt buckets of raw UID2s that you've cached.
If you find that the salt bucket was updated for one or more raw UID2s, re-send the DII to the `POST /identity/map` endpoint for a new raw UID2. | +| 5-d | [POST /identity/map](../endpoints/post-identity-map.md) | Store the new values returned for `advertising_id` and `bucket_id`. | -#### Determine whether the salt bucket has been rotated +##### Determine whether the salt bucket has been rotated To determine whether the salt bucket ID for a specific raw UID2 has changed, follow these steps. 1. Compare these two values: - - The `last_updated` timestamp of each `bucket_id` returned as part of monitoring the salt bucket rotations. - - - The timestamp of the raw UID2 generation of the same `bucket_id`, which was returned in Step 1 and stored in Step 2. + - The `last_updated` timestamp of each `bucket_id` returned as part of monitoring the salt bucket rotations. + + - The timestamp of the raw UID2 generation of the same `bucket_id`, which was returned in Step 1 and stored in Step 2. 1. If the `last_updated` timestamp is more recent than the timestamp you recorded earlier, the salt bucket has been rotated. As a result, you'll need to regenerate any raw UID2s associated with this `bucket_id`, following Step 1, [Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii). -### 6: Monitor for Opt-Out Status +#### 6: Monitor for Opt-Out Status It's important to honor user opt-out status. Periodically, monitor for opt-out status, to be sure that you don't continue using UID2s for users that have recently opted out. There are two ways that you can check with the UID2 Operator Service to make sure you have the latest opt-out information: -- Call the [POST /identity/map (v2)](../endpoints/post-identity-map.md) endpoint to check for opt-outs. If the DII has been opted out, no raw UID2 is generated. +- Call the [POST /identity/map](../endpoints/post-identity-map.md) endpoint to check for opt-outs. If the DII has been opted out, no raw UID2 is generated. - Check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. -For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md). +For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md). \ No newline at end of file diff --git a/docs/guides/integration-advertiser-dataprovider-overview.md b/docs/guides/integration-advertiser-dataprovider-overview.md index e2536c6c8..4a95871a5 100644 --- a/docs/guides/integration-advertiser-dataprovider-overview.md +++ b/docs/guides/integration-advertiser-dataprovider-overview.md @@ -23,9 +23,9 @@ There are other ways that you can use UID2, outside these use cases. These are j | Send/Receive? | Action | Advantage/Result | | --- | --- | --- | -| Send in audiences | Send UID2s via API or pixels | Create audiences. | -| Send in conversions | Send UID2s as conversion information | Use conversion information for measurement (attribution) or for retargeting via API or pixels. | -| Receive graph data | Receive UID2s from graph/data providers via API or pixels | Build graph data. | +| Send in audiences | Send Raw UID2s via API or pixels | Create audiences. | +| Send in conversions | Send Raw UID2s as conversion information | Use conversion information for measurement (attribution) or for retargeting via API or pixels. | +| Receive graph data | Receive Raw UID2s from graph/data providers via API or pixels | Build graph data. | ## High-Level Steps @@ -33,13 +33,13 @@ At a high level, the steps for advertisers and data providers integrating with U 1. [Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) -2. [Store Raw UID2s and Salt Bucket IDs](#2-store-raw-uid2s-and-salt-bucket-ids) +2. [Store Raw UID2s and Refresh Timestamps](#2-store-raw-uid2s-and-refresh-timestamps) 3. [Manipulate or Combine Raw UID2s](#3-manipulate-or-combine-raw-uid2s) 4. [Send Stored Raw UID2s to DSPs to Create Audiences or Conversions](#4-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) -5. [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s) +5. [Monitor for Raw UID2 Refresh](#5-monitor-for-raw-uid2-refresh) 6. [Monitor for Opt-Out Status](#6-monitor-for-opt-out-status) @@ -47,14 +47,14 @@ At a high level, the steps for advertisers and data providers integrating with U The following table shows the implementation options that are available for advertisers and data providers, for each of the high-level steps. Some steps are managed solely as part of your own custom implementation; some steps can be managed by one or more of the UID2 implementation options available. For details, click the link on each step. -| High-Level Step | Implementation Options | -| --- | --- | -| [1: Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) | Use any of the following options to map DII to raw UID2s: | -| [2: Store Raw UID2s and Salt Bucket IDs](#2-store-raw-uid2s-and-salt-bucket-ids) | Custom (your choice). | -| [3: Manipulate or Combine Raw UID2s](#3-manipulate-or-combine-raw-uid2s) | Custom (your choice). | -| [4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions](#4-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) | Custom (your choice). | -| [5: Monitor for Salt Bucket Rotations for Your Stored Raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s) | Any of the following options: | -| [6: Monitor for Opt-Out Status](#6-monitor-for-opt-out-status) | API call to the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. | +| High-Level Step | Implementation Options | +|-------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [1: Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) | Use any of the following options to map DII to raw UID2s: | +| [2: Store Raw UID2s and Refresh Timestamps](#2-store-raw-uid2s-and-refresh-timestamps) | Custom (your choice). | +| [3: Manipulate or Combine Raw UID2s](#3-manipulate-or-combine-raw-uid2s) | Custom (your choice). | +| [4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions](#4-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) | Custom (your choice). | +| [5: Monitor for Raw UID2 Refresh](#5-monitor-for-raw-uid2-refresh) | Use the refresh timestamp (`r` field) returned from the [POST /identity/map](../endpoints/post-identity-map-v3.md) endpoint to determine when to refresh Raw UID2s. | +| [6: Monitor for Opt-Out Status](#6-monitor-for-opt-out-status) | API call to the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. | ## Integration Diagram @@ -64,9 +64,9 @@ DII refers to a user's normalized email address or phone number, or the normaliz To keep your UID2-based audience information accurate and up to date, follow these integration steps every day. -![Advertiser Flow](images/advertiser-flow-overview-mermaid.png) +![Advertiser Flow](images/advertiser-flow-overview-mermaid-v3.png) - + For details about the different parts of the diagram, refer to the following sections. @@ -85,21 +85,22 @@ To generate raw UID2s, use one of the following options: - AWS Entity Resolution: See [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md). -- HTTP endpoints: [POST /identity/map (v2)](../endpoints/post-identity-map.md). For details, see [Generate Raw UID2s from DII](integration-advertiser-dataprovider-endpoints.md#1-generate-raw-uid2s-from-dii). +- HTTP endpoints: [POST /identity/map](../endpoints/post-identity-map-v3.md). For details, see [Generate Raw UID2s from DII](integration-advertiser-dataprovider-endpoints.md#1-generate-raw-uid2s-from-dii). -### 2: Store Raw UID2s and Salt Bucket IDs +### 2: Store Raw UID2s and Refresh Timestamps 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: -- Cache the mapping between DII (`identifier`), raw UID2 (`advertising_id`), and salt bucket (`bucket_id`). -- 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](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s). +- Cache the mapping between DII and raw UID2 (`u` field). +- Store the refresh timestamp (`r` field) to know when the raw UID2 could refresh. +- Optionally store the previous raw UID2 (`p` field) if provided for users whose UID2 was refreshed within the last 90 days. ### 3: Manipulate or Combine Raw UID2s -Use the UID2s you received in Step 1. For example, you might do one or more of the following: +Use the Raw UID2s you received in Step 1. For example, you might do one or more of the following: -- Do some manipulation: for example, combine UID2s you generated from DII and UID2s received from another participant such as an advertiser or data provider. -- Add new UID2s into an existing audience. +- Do some manipulation: for example, combine Raw UID2s you generated from DII and Raw UID2s received from another participant such as an advertiser or data provider. +- Add new Raw UID2s into an existing audience. ### 4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions @@ -108,17 +109,159 @@ Use the raw UID2s for some purpose such as: - Sending stored raw UID2s to DSPs to create audiences and conversions. - Using the raw UID2s for measurement. +For example, you could send the (raw UID2 (`u` field) returned in Step 1 to a DSP while building your audiences. Each DSP has a unique integration process for building audiences; follow the integration guidance provided by the DSP for sending raw UID2s to build an audience. + +You could also send conversion information via API or pixels for measurement (attribution) or for retargeting. + +### 5: Monitor for Raw UID2 Refresh + +A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes at least once per year as part of the UID2 refresh process. + +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. + +We recommend checking for refresh opportunities daily. To determine whether to refresh a raw UID2: + +1. Compare the current time with the refresh timestamp (`r` field) you stored from the [POST /identity/map](../endpoints/post-identity-map-v3.md) response. + +2. If the current time is greater than or equal to the refresh timestamp, regenerate the raw UID2 by calling [POST /identity/map](../endpoints/post-identity-map-v3.md) again with the same DII. + +This approach ensures your Raw UID2s remain current and valid for audience targeting and measurement. + + +### 6: Monitor for Opt-Out Status + +It's important to honor user opt-out status. Periodically, monitor for opt-out status, to be sure that you don't continue using Raw UID2s for users that have recently opted out. + +There are two ways that you can check with the UID2 Operator Service to make sure you have the latest opt-out information: + +- Call the [POST /identity/map](../endpoints/post-identity-map-v3.md) endpoint to check for opt-outs. If the DII has been opted out, no raw UID2 is generated. + +- Check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. + +For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md). + +## FAQs + +For a list of frequently asked questions for advertisers and data providers using the UID2 framework, see [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). + +--- + +# For Users of V2 Identity Map API + +:::warning +The following information is relevant to the V2 integration approach and is provided for reference only. New implementations should use the main approach described above. For current best practices, refer to the [main integration guide](#high-level-steps).9 +::: + +## Advertiser/Data Provider Integration Overview (V2) + +This guide provides an overview of integration options for organizations that collect user data and push it to other UID2 participants. Data collectors include advertisers, data on-boarders, measurement providers, identity graph providers, third-party data providers, and any other organizations that send data to other participants. + +### Advertiser/Data Provider Routes to Use UID2 (V2) + +Within the ad tech industry, advertisers use identity to build audiences, track conversions, and generate their graphs. As an advertiser, or as a data provider acting on behalf of an advertiser, the following table shows some examples of how you can accomplish some of these goals with UID2. + +:::note +There are other ways that you can use UID2, outside these use cases. These are just some examples. +::: + +| Send/Receive? | Action | Advantage/Result | +| --- | --- | --- | +| Send in audiences | Send UID2s via API or pixels | Create audiences. | +| Send in conversions | Send UID2s as conversion information | Use conversion information for measurement (attribution) or for retargeting via API or pixels. | +| Receive graph data | Receive UID2s from graph/data providers via API or pixels | Build graph data. | + +### High-Level Steps (V2) + +At a high level, the steps for advertisers and data providers integrating with UID2 are as follows: + +1. [Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii-v2) + +2. [Store Raw UID2s and Salt Bucket IDs](#2-store-raw-uid2s-and-salt-bucket-ids-v2) + +3. [Manipulate or Combine Raw UID2s](#3-manipulate-or-combine-raw-uid2s-v2) + +4. [Send Stored Raw UID2s to DSPs to Create Audiences or Conversions](#4-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions-v2) + +5. [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2) + +6. [Monitor for Opt-Out Status](#6-monitor-for-opt-out-status-v2) + +### Summary of Implementation Options (V2) + +The following table shows the implementation options that are available for advertisers and data providers, for each of the high-level steps. Some steps are managed solely as part of your own custom implementation; some steps can be managed by one or more of the UID2 implementation options available. For details, click the link on each step. + +| High-Level Step | Implementation Options | +| --- | --- | +| [1: Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii-v2) | Use any of the following options to map DII to raw UID2s: | +| [2: Store Raw UID2s and Salt Bucket IDs](#2-store-raw-uid2s-and-salt-bucket-ids-v2) | Custom (your choice). | +| [3: Manipulate or Combine Raw UID2s](#3-manipulate-or-combine-raw-uid2s-v2) | Custom (your choice). | +| [4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions](#4-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions-v2) | Custom (your choice). | +| [5: Monitor for Salt Bucket Rotations for Your Stored Raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2) | Any of the following options: | +| [6: Monitor for Opt-Out Status](#6-monitor-for-opt-out-status-v2) | API call to the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. | + +### Integration Diagram (V2) + +The following diagram outlines the steps that data collectors must complete to map DII to raw UID2s for audience building and targeting. + +DII refers to a user's normalized email address or phone number, or the normalized and SHA-256-hashed email address or phone number. + +To keep your UID2-based audience information accurate and up to date, follow these integration steps every day. + +![Advertiser Flow](images/advertiser-flow-overview-mermaid.png) + + + +For details about the different parts of the diagram, refer to the following sections. + +#### 1: Generate Raw UID2s from DII (V2) + +You can generate raw UID2s from directly identifying information (DII), or receive UID2s from another UID2 participant such as a data provider acting on your behalf. + +To generate raw UID2s, use one of the following options: + +- One of the UID2 SDKs: + + - Python SDK: See [Map DII to Raw UID2s](../sdks/sdk-ref-python.md#map-dii-to-raw-uid2s). + - Java SDK: See [Usage for Advertisers/Data Providers](../sdks/sdk-ref-java.md#usage-for-advertisersdata-providers). + +- Snowflake: See [Map DII](integration-snowflake.md#map-dii). + +- AWS Entity Resolution: See [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md). + +- HTTP endpoints: [POST /identity/map](../endpoints/post-identity-map.md). For details, see [Generate Raw UID2s from DII](integration-advertiser-dataprovider-endpoints.md#1-generate-raw-uid2s-from-dii). + +#### 2: Store Raw UID2s and Salt Bucket IDs (V2) + +The response from Step 1, [Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii-v2), contains mapping information. We recommend that you store the following information returned in Step 1: + +- Cache the mapping between DII (`identifier`), raw UID2 (`advertising_id`), and salt bucket (`bucket_id`). +- 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](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2). + +#### 3: Manipulate or Combine Raw UID2s (V2) + +Use the UID2s you received in Step 1. For example, you might do one or more of the following: + +- Do some manipulation: for example, combine UID2s you generated from DII and UID2s received from another participant such as an advertiser or data provider. +- Add new UID2s into an existing audience. + +#### 4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions (V2) + +Use the raw UID2s for some purpose such as: + +- Sending stored raw UID2s to DSPs to create audiences and conversions. +- Using the raw UID2s for measurement. + For example, you could send the `advertising_id` (raw UID2) returned in Step 1-b to a DSP while building your audiences. Each DSP has a unique integration process for building audiences; follow the integration guidance provided by the DSP for sending raw UID2s to build an audience. You could also send conversion information via API or pixels for measurement (attribution) or for retargeting. -### 5: Monitor for Salt Bucket Rotations for Your Stored Raw UID2s +#### 5: Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (V2) -A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes at least once per year, as a result of the salt bucket rotation. +A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes at least once per year, as a result of the salt bucket rotation. Even though each salt bucket is updated approximately once per year, individual bucket updates are spread over the year. Approximately 1/365th of all salt buckets are rotated daily. Based on this, we recommend checking salt bucket rotation regularly, on a cadence that aligns with your audience refreshes. For example, if you refresh weekly, check for salt bucket updates weekly. -If the salt bucket has been rotated, regenerate the raw UID2. For details, see [Determine whether the salt bucket has been rotated](#determine-whether-the-salt-bucket-has-been-rotated). +If the salt bucket has been rotated, regenerate the raw UID2. For details, see [Determine whether the salt bucket has been rotated](#determine-whether-the-salt-bucket-has-been-rotated-v2). For instructions for monitoring for salt bucket rotations, refer to one of the following: @@ -132,30 +275,30 @@ For instructions for monitoring for salt bucket rotations, refer to one of the f 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. ::: -#### Determine whether the salt bucket has been rotated +##### Determine whether the salt bucket has been rotated (V2) To determine whether the salt bucket ID for a specific raw UID2 has changed, follow these steps. 1. Compare these two values: - - The `last_updated` timestamp of each `bucket_id` returned as part of monitoring the salt bucket rotations (whatever option you choose). - - - The timestamp of the raw UID2 generation of the same `bucket_id`, which was returned in Step 1 and stored in Step 2. + - The `last_updated` timestamp of each `bucket_id` returned as part of monitoring the salt bucket rotations (whatever option you choose). -1. If the `last_updated` timestamp is more recent than the timestamp you recorded earlier, the salt bucket has been rotated. As a result, you'll need to regenerate any raw UID2s associated with this `bucket_id`, following Step 1, [Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii). + - The timestamp of the raw UID2 generation of the same `bucket_id`, which was returned in Step 1 and stored in Step 2. -### 6: Monitor for Opt-Out Status +1. If the `last_updated` timestamp is more recent than the timestamp you recorded earlier, the salt bucket has been rotated. As a result, you'll need to regenerate any raw UID2s associated with this `bucket_id`, following Step 1, [Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii-v2). + +#### 6: Monitor for Opt-Out Status (V2) It's important to honor user opt-out status. Periodically, monitor for opt-out status, to be sure that you don't continue using UID2s for users that have recently opted out. There are two ways that you can check with the UID2 Operator Service to make sure you have the latest opt-out information: -- Call the [POST /identity/map (v2)](../endpoints/post-identity-map.md) endpoint to check for opt-outs. If the DII has been opted out, no raw UID2 is generated. +- Call the [POST /identity/map](../endpoints/post-identity-map.md) endpoint to check for opt-outs. If the DII has been opted out, no raw UID2 is generated. - Check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md). -## FAQs +### FAQs (V2) -For a list of frequently asked questions for advertisers and data providers using the UID2 framework, see [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). +For a list of frequently asked questions for advertisers and data providers using the UID2 framework, see [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). \ No newline at end of file diff --git a/docs/overviews/overview-advertisers.md b/docs/overviews/overview-advertisers.md index 11042bba0..bd4b5151d 100644 --- a/docs/overviews/overview-advertisers.md +++ b/docs/overviews/overview-advertisers.md @@ -39,15 +39,15 @@ Here are just some of the intended benefits of using UID2 as part of your advert The following steps provide a high-level outline of the workflow intended for organizations that collect user data and push it to DSPs—for example, advertisers, identity graph providers, and third-party data providers. The following process occurs in the background: -* The advertiser or data provider monitors the UID2 Operator for rotated salt buckets and updates UID2s as needed. +* The advertiser or data provider monitors refresh timestamps and updates UID2s when the current time exceeds the refresh timestamp for each stored UID2. The following steps are an example of how an advertiser can integrate with UID2: 1. The advertiser sends a user’s directly identifying information (DII) to the UID2 Operator. -2. The UID2 Operator generates and returns a raw UID2 and salt bucket ID. -3. The advertiser stores the UID2 and salt bucket ID and sends the UID2-based first-party and third-party audience segments to the DSP. +2. The UID2 Operator generates and returns a raw UID2 and refresh timestamp. +3. The advertiser stores the UID2 and refresh timestamp and sends the UID2-based first-party and third-party audience segments to the DSP. - Server-side: The advertiser stores the UID2 in a mapping table, DMP, data lake, or other server-side application. + Server-side: The advertiser stores the UID2 and refresh timestamp in a mapping table, DMP, data lake, or other server-side application. ![Data Provider Workflow](images/UID2AdvertiserAndThirdPartyDataProviderWorkflow.svg) diff --git a/docs/overviews/overview-data-providers.md b/docs/overviews/overview-data-providers.md index 5c17c580c..9da97cbfa 100644 --- a/docs/overviews/overview-data-providers.md +++ b/docs/overviews/overview-data-providers.md @@ -44,15 +44,15 @@ Here are just some of the intended benefits available to you as a data provider The following steps provide a high-level outline of the workflow intended for organizations that collect user data and push it to DSPs—for example, advertisers, identity graph providers, and third-party data providers. The following process occurs in the background: -* The advertiser or data provider monitors the UID2 Operator for rotated salt buckets, and updates UID2s as needed. +* The advertiser or data provider monitors refresh timestamps and updates UID2s when the current time exceeds the refresh timestamp for each stored UID2. The following steps are an example of how a data provider can integrate with UID2: 1. The data provider sends a user’s directly identifying information (DII) to the UID2 Operator. -2. The UID2 Operator generates and returns a raw UID2 and salt bucket ID. -3. The data provider stores the UID2 and salt bucket ID and sends the UID2-based first-party and third-party audience segments to the DSP. +2. The UID2 Operator generates and returns a raw UID2 and refresh timestamp. +3. The data provider stores the UID2 and refresh timestamp and sends the UID2-based first-party and third-party audience segments to the DSP. - Server-side: The data provider stores the UID2 in a mapping table, DMP, data lake, or other server-side application. + Server-side: The data provider stores the UID2 and refresh timestamp in a mapping table, DMP, data lake, or other server-side application. ![Data Provider Workflow](images/UID2AdvertiserAndThirdPartyDataProviderWorkflow.svg) diff --git a/docs/ref-info/glossary-uid.md b/docs/ref-info/glossary-uid.md index 2869c7e65..5109a4c7b 100644 --- a/docs/ref-info/glossary-uid.md +++ b/docs/ref-info/glossary-uid.md @@ -90,6 +90,7 @@ import Link from '@docusaurus/Link'; **R** Raw UID2 | +Refresh timestamp | Refresh token **S** @@ -371,7 +372,7 @@ import Link from '@docusaurus/Link';
Participant
-
An entity that fulfils a key role in UID2. Participants include the following: Core Administrator, Operator, DSP, data provider, advertiser, publisher, consumer.
+
An entity that fulfils a key role in UID2. Participants include the following: Core Administrator, Operator, DSP, data provider, advertiser, publisher, and consumer.
For details, see participants.
Private Operator
@@ -399,6 +400,10 @@ import Link from '@docusaurus/Link';
An unencrypted alphanumeric identifier created through the UID2 APIs or SDKs with the user's directly identifying information (email address or phone number) as input. The raw UID2 is encrypted to create a UID2 token. The raw UID2 is a unique value; no two raw UID2s are the same. Raw UID2s, and their associated UID2 tokens, are case sensitive.
For details, see UID2 Identifier Types.
+
Refresh timestamp
+
In the context of mapping DII to raw UID2s, a refresh timestamp is a Unix timestamp (in seconds) returned in the r field of the POST /identity/map endpoint response. The raw UID2 is guaranteed to be valid until this timestamp. It is refreshed at some point after this time.
+
Use the refresh timestamp to determine when to regenerate raw UID2s for your stored data. We recommend checking for refresh opportunities daily by comparing the current time with the stored refresh timestamps.
+
Refresh token
A refresh token is an opaque string that is issued along with the UID2 token. It is used to refresh the UID2 token, which has a limited life.
When the UID2 server receives the refresh token with a request for a new UID2 token, it checks for user opt-out. If the user has opted out of UID2, no new UID2 token is generated.