From c72faef5cdcdf0385430d49b0b6ce5a8d916c6aa Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Tue, 8 Oct 2024 16:50:58 -0400 Subject: [PATCH] updates to advertiser/data provider guide, work in progress --- docs/endpoints/post-identity-buckets.md | 2 +- docs/endpoints/post-identity-map.md | 4 +- docs/endpoints/post-optout-status.md | 2 +- docs/getting-started/gs-credentials.md | 2 +- docs/getting-started/gs-faqs.md | 4 +- docs/guides/advertiser-dataprovider-guide.bak | 169 ++++++++++++++++++ docs/guides/advertiser-dataprovider-guide.mdx | 3 + .../advertiser-dataprovider-identity-map.md | 71 ++++++++ ...ration-options-advertiser-dataprovider.md} | 63 +++++-- docs/guides/summary-guides.md | 12 +- docs/overviews/overview-advertisers.md | 2 +- docs/overviews/overview-data-providers.md | 2 +- .../endpoints/post-identity-buckets.md | 2 +- .../current/endpoints/post-identity-map.md | 4 +- .../current/endpoints/post-optout-status.md | 2 +- .../current/getting-started/gs-credentials.md | 2 +- .../current/getting-started/gs-faqs.md | 4 +- ...e.md => advertiser-dataprovider-guide.bak} | 8 +- .../guides/advertiser-dataprovider-guide.mdx | 3 + .../advertiser-dataprovider-identity-map.md | 16 ++ ...gration-options-advertiser-dataprovider.md | 138 ++++++++++++++ .../current/guides/summary-guides.md | 2 +- .../current/overviews/overview-advertisers.md | 2 +- .../overviews/overview-data-providers.md | 2 +- sidebars.js | 11 +- 25 files changed, 481 insertions(+), 51 deletions(-) create mode 100644 docs/guides/advertiser-dataprovider-guide.bak create mode 100644 docs/guides/advertiser-dataprovider-guide.mdx create mode 100644 docs/guides/advertiser-dataprovider-identity-map.md rename docs/guides/{advertiser-dataprovider-guide.md => integration-options-advertiser-dataprovider.md} (63%) rename i18n/ja/docusaurus-plugin-content-docs/current/guides/{advertiser-dataprovider-guide.md => advertiser-dataprovider-guide.bak} (93%) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/guides/advertiser-dataprovider-guide.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/guides/advertiser-dataprovider-identity-map.md create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-options-advertiser-dataprovider.md diff --git a/docs/endpoints/post-identity-buckets.md b/docs/endpoints/post-identity-buckets.md index 66c5045ff..64905b7a8 100644 --- a/docs/endpoints/post-identity-buckets.md +++ b/docs/endpoints/post-identity-buckets.md @@ -11,7 +11,7 @@ import Link from '@docusaurus/Link'; Monitors rotated salt buckets. -Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md). +Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md). ## Request Format diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index eae1ee0e9..c191dbfde 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -11,7 +11,7 @@ import Link from '@docusaurus/Link'; Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s and salt bucket IDs. You can also use this endpoint to check for updates to opt-out information. -Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md). +Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md). ## Batch Size and Request Parallelization Requirements @@ -20,7 +20,7 @@ Here's what you need to know: - The maximum request size is 1MB. - 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. - Unless you are using a Private Operator, do not send batches in parallel. In other words, use a single HTTP connection and map directly identifying information (DII) consecutively. -- Be sure to store mappings of email addresses, phone numbers, or their respective hashes.
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 raw UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). +- Be sure to store mappings of email addresses, phone numbers, or their respective hashes.
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 raw UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). ## Request Format diff --git a/docs/endpoints/post-optout-status.md b/docs/endpoints/post-optout-status.md index da994a9d6..05dc2ae40 100644 --- a/docs/endpoints/post-optout-status.md +++ b/docs/endpoints/post-optout-status.md @@ -15,7 +15,7 @@ Used by: This endpoint is used by advertisers, data providers, DSPs, and sharers For details, refer to the following documentation, depending on your role: -- [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md) +- [Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md) - [DSP Integration Guide](../guides/dsp-guide.md) - [UID2 Sharing: Overview](../sharing/sharing-overview) diff --git a/docs/getting-started/gs-credentials.md b/docs/getting-started/gs-credentials.md index 05ae74d84..bed05258f 100644 --- a/docs/getting-started/gs-credentials.md +++ b/docs/getting-started/gs-credentials.md @@ -15,7 +15,7 @@ Each UID2 participant gets a set of uniqu | :--- | :--- | :--- | | Participants using a client-side implementation | Both of the following: These two, together, are sometimes called client keypair. | Integrations using one of these: | | Participants using a client-server implementation | Both of the following: | Integrations using one of these: | -| Participants using a server-side implementation | Both of the following: | Integrations using one of these: | +| Participants using a server-side implementation | Both of the following: | Integrations using one of these: | If you're using the integration environment as well as the production environment, you'll get a separate set of credentials for each environment. diff --git a/docs/getting-started/gs-faqs.md b/docs/getting-started/gs-faqs.md index 40a972e61..6652487c7 100644 --- a/docs/getting-started/gs-faqs.md +++ b/docs/getting-started/gs-faqs.md @@ -152,7 +152,7 @@ We do not make any promises about when the rotation takes place. To stay as up-t #### 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, [call the mapping function](../guides/advertiser-dataprovider-guide.md#1-retrieve-a-raw-uid2-for-dii-using-the-identity-map-endpoint) and save the returned UID2 and bucket ID again. +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, [call the mapping function](../guides/integration-options-advertiser-dataprovider.md#1-retrieve-a-raw-uid2-from-dii) and save the returned 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. @@ -190,7 +190,7 @@ In general yes, the process of generating a raw UID2 from DII is the same, and r However, there is a variable factor, which is the 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. -For more information, see [Monitor for salt bucket rotations related to your stored raw UID2s](../guides/advertiser-dataprovider-guide.md#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s) in the *Advertiser/Data Provider Integration Guide*. +For more information, see [Monitor for salt bucket rotations related to your stored raw UID2s](../guides/integration-options-advertiser-dataprovider.md#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s) in the *Advertiser/Data Provider Integration Guide*. #### If two operators process the same DII, are the results the same? diff --git a/docs/guides/advertiser-dataprovider-guide.bak b/docs/guides/advertiser-dataprovider-guide.bak new file mode 100644 index 000000000..76daf35b7 --- /dev/null +++ b/docs/guides/advertiser-dataprovider-guide.bak @@ -0,0 +1,169 @@ +--- +title: Advertiser/Data Provider Integration Overview +sidebar_label: Advertiser/Data Provider Integration Overview +description: Overview of UID2 integration options for organizations that collect user data and push it to other participants. +hide_table_of_contents: false +sidebar_position: 07 +displayed_sidebar: sidebarAdvertisers +--- + +import Link from '@docusaurus/Link'; + +# Advertiser/Data Provider Integration Overview + +This guide covers integration steps 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. + +If you are using an Open Operator service hosted in the Snowflake Data Marketplace, see also [Snowflake Integration Guide](snowflake_integration.md). + +## Advertiser/Data Provider Routes to Use UID2 + +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 | Send UID2s via API or pixels | Create audiences. | +| Send | Send UID2s as conversion information | Use conversion information for measurement (attribution) or for retargeting via API or pixels. | +| Receive | Receive UID2s from graph/data providers via API or pixels | Build graph data. | + + + +## Key Integration Steps + +At a high level, to integrate with UID2 as an advertiser or data provider, you'll implement these three key activities: + +1. [Retrieve a raw UID2 for DII](#1-retrieve-a-raw-uid2-from-dii) + + Generate a raw UID2 from directly identifying information (DII), or receive UID2s from another UID2 participant such as a data provider acting on your behalf. + +2. [Send stored raw UID2s to DSPs to create audiences or conversions](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) + + 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. + + As part of this step, you'll also need to [monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s). + +3. Use the raw UID2s for some purpose such as measurement. + +## Integration Options Summary + +The following integration options are available for advertisers and data providers: + +| Integration Option | Link to Documentation | +| :--- | :--- | +| Client-Side JavaScript SDK |[Client-Side Integration Guide for JavaScript](integration-javascript-client-side.md) | +| Snowflake | [Snowflake Integration Guide](snowflake_integration.md) | +| AWS Entity Resolution | [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md) | +| AWS Entity Resolution | [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md) | +| Direct integration (API endpoints ] [xxx TBD](advertiser-dataprovider-identity-map.md) | + +For a summary of the UID2 integration solutions available for advertisers and data providers. + + + + + + +### High-Level Key Integration Steps + +At a high level, the steps for advertisers and data providers integrating with UID2 are as follows: + +1. Generate a raw UID2 from directly identifying information (DII), or receive UID2s from another UID2 participant such as a data provider acting on your behalf. + +1. 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. + +1. Use the raw UID2s for some purpose such as measurement. + +There are several ways you can accomplish these key steps. + + + + +## 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-mermaid.png) + + + +Refer to the following sections for details about the different parts of the diagram: +1. [Retrieve a raw UID2 for DII](#1-retrieve-a-raw-uid2-from-dii) +2. [Send stored raw UID2s to DSPs to create audiences or conversions](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) +3. [Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s) + +### 1: Generate a raw UID2 from DII + +The first step is to retrieve a raw UID2. You can do this by using any of the advertiser/data provider implementation options, summarized in the following table. + +| Integration Method | Link to Instructions | +| :--- | :--- | +| [Client-Side Integration Guide for JavaScript](integration-javascript-client-side.md) | xxx | +| [Snowflake Integration Guide](snowflake_integration.md) | xxx | +| [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md) | xxx | +| [Direct integration (API endpoints)](advertiser-dataprovider-identity-map.md) | xxx TBD | + +### 2: Send stored raw UID2s to DSPs to create audiences or conversions + +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. + +### 3: Monitor for salt bucket rotations related to 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 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. + +:::important +To ensure that your integration has the current raw UID2s, check salt bucket rotation for active users every day. +::: + +| Step | Endpoint | Description | +| --- | --- | --- | +| 3-a | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | Send a request to the bucket status endpoint for all salt buckets that have changed since a specific timestamp. | +| 3-b | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | UID2 service: The bucket status endpoint returns a list of `bucket_id` and `last_updated` timestamps. | +| 3-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 identity mapping service for a new raw UID2. | +| 3-d | [POST /identity/map](../endpoints/post-identity-map.md) | Store the new values returned for `advertising_id` and `bucket_id`. | + +## Use an Incremental Process to Continuously Update Raw UID2s + +To keep your UID2-based audience information accurate and up to date, follow these integration steps every day: + +1. The response from the [UID2 retrieval step](#1-retrieve-a-raw-uid2-from-dii) contains mapping information. Cache the following: + - The mapping between DII (`identifier`), raw UID2 (`advertising_id`), and salt bucket (`bucket_id`). + - The most recent `last_updated` timestamp. +2. Using the results from Step 3, [Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s), remap any raw UID2 for which the salt buckets have been rotated by retrieving new raw UID2 for those IDs, following Step 1, [Retrieve a raw UID2 for DII using the identity map endpoint](#1-retrieve-a-raw-uid2-from-dii). + + Then, use the refreshed UID2s to update audiences or conversions, following Step 2, [send raw UID2 to a DSP](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions). + +## Check Opt-Out Status + +It's important to honor user opt-out status. Here are two ways you can check that you have the latest opt-out information: + +- The UID2 Operator Service distributes opt-out information to advertisers and data providers via the [POST /identity/map](../endpoints/post-identity-map.md) endpoint. + +- Advertisers and data providers can check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. + + +## Implementation Resources + +The following documentation resources are available for advertisers and data providers integrating with UID2. + +| Integration Guide | Content Description | +| :--- | :--- | +| [Advertiser/Data Provider](integration-options-advertiser-dataprovider.md) | This integration guide for advertisers and data providers covers integration workflows for mapping identity for audience-building and targeting. | +| [Client-Side Integration Guide for JavaScript](integration-javascript-client-side.md) | A guide for advertisers and data providers who want to use this SDK for adding a UID2 token to their tracking pixels. | +| [Snowflake Integration Guide](snowflake_integration.md) | Instructions for generating UID2s from emails within Snowflake. | +| [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md) | Instructions for integrating with the UID2 framework using AWS Entity Resolution. | + +## 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). diff --git a/docs/guides/advertiser-dataprovider-guide.mdx b/docs/guides/advertiser-dataprovider-guide.mdx new file mode 100644 index 000000000..ff280aa4f --- /dev/null +++ b/docs/guides/advertiser-dataprovider-guide.mdx @@ -0,0 +1,3 @@ +import { Redirect } from '@docusaurus/router'; + +; diff --git a/docs/guides/advertiser-dataprovider-identity-map.md b/docs/guides/advertiser-dataprovider-identity-map.md new file mode 100644 index 000000000..ef6879801 --- /dev/null +++ b/docs/guides/advertiser-dataprovider-identity-map.md @@ -0,0 +1,71 @@ +--- +title: Advertiser/Data Provider Integration Steps +sidebar_label: Advertiser/Data Provider Integration Steps +description: TBD +hide_table_of_contents: false +sidebar_position: 07 +displayed_sidebar: sidebarAdvertisers +--- + +import Link from '@docusaurus/Link'; + +# Advertiser/Data Provider Integration Steps + +**RENAME TO INTEGRATION-ADVERTISER-DATA-PROVIDER.MD AND MAKE THIS THE INTEGRATION GUIDE AND THE OLD ONE THE OVERVIEW DOC.** + + + + + + + + +### 1: Retrieve a raw UID2 for DII using the identity map endpoint + +| Step | Endpoint | Description | +| --- | --- | --- | +| 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 [3: Monitor for salt bucket rotations](integration-options-advertiser-dataprovider.md#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s).
For ease of maintenance, a recommended approach is to store a user's raw UID2 and `bucket_id` in a mapping table. For guidance on incremental updates, see [Use an incremental process to continuously update raw UID2s](#use-an-incremental-process-to-continuously-update-raw-uid2s). | + +### 2: Send stored raw UID2s to DSPs to create audiences or conversions + +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. + +### 3: Monitor for salt bucket rotations related to 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 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. + +:::important +To ensure that your integration has the current raw UID2s, check salt bucket rotation for active users every day. +::: + +| Step | Endpoint | Description | +| --- | --- | --- | +| 3-a | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | Send a request to the bucket status endpoint for all salt buckets that have changed since a specific timestamp. | +| 3-b | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | UID2 service: The bucket status endpoint returns a list of `bucket_id` and `last_updated` timestamps. | +| 3-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 identity mapping service for a new raw UID2. | +| 3-d | [POST /identity/map](../endpoints/post-identity-map.md) | Store the new values returned for `advertising_id` and `bucket_id`. | + +## Use an Incremental Process to Continuously Update Raw UID2s + +To keep your UID2-based audience information accurate and up to date, follow these integration steps every day: + +1. The response from the [UID2 retrieval step](integration-options-advertiser-dataprovider.md#1-retrieve-a-raw-uid2-from-dii) contains mapping information. Cache the following: + - The mapping between DII (`identifier`), raw UID2 (`advertising_id`), and salt bucket (`bucket_id`). + - The most recent `last_updated` timestamp. +2. Using the results from Step 3, [Monitor for salt bucket rotations related to your stored raw UID2s](integration-options-advertiser-dataprovider.md#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s), remap any raw UID2 for which the salt buckets have been rotated by retrieving new raw UID2 for those IDs, following Step 1, [Retrieve a raw UID2 for DII using the identity map endpoint](integration-options-advertiser-dataprovider.md#1-retrieve-a-raw-uid2-from-dii). + + Then, use the refreshed UID2s to update audiences or conversions, following Step 2, [send raw UID2 to a DSP](integration-options-advertiser-dataprovider.md#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions). + +## Check Opt-Out Status + +It's important to honor user opt-out status. Here are two ways you can check that you have the latest opt-out information: + +- The UID2 Operator Service distributes opt-out information to advertisers and data providers via the [POST /identity/map](../endpoints/post-identity-map.md) endpoint. + +- Advertisers and data providers can check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. + +## 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). diff --git a/docs/guides/advertiser-dataprovider-guide.md b/docs/guides/integration-options-advertiser-dataprovider.md similarity index 63% rename from docs/guides/advertiser-dataprovider-guide.md rename to docs/guides/integration-options-advertiser-dataprovider.md index 31b436f59..95bda0418 100644 --- a/docs/guides/advertiser-dataprovider-guide.md +++ b/docs/guides/integration-options-advertiser-dataprovider.md @@ -1,7 +1,7 @@ --- -title: Advertiser/Data Provider Integration -sidebar_label: Advertiser/Data Provider Integration Guide -description: Integration for organizations that collect user data and push it to other participants. +title: Advertiser/Data Provider Integration Overview +sidebar_label: Advertiser/Data Provider Integration Overview +description: Overview of UID2 integration options for organizations that collect user data and push it to other participants. hide_table_of_contents: false sidebar_position: 07 displayed_sidebar: sidebarAdvertisers @@ -9,9 +9,11 @@ displayed_sidebar: sidebarAdvertisers import Link from '@docusaurus/Link'; -# Advertiser/Data Provider Integration Guide +# Advertiser/Data Provider Integration Overview -This guide covers integration steps 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. +There are many ways for advertisers and data providers to integration with UID2. On this page, you'll find a high-level overview of integration steps and integration options, with links to additional information for each option. + +These integration options apply to any 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. If you are using an Open Operator service hosted in the Snowflake Data Marketplace, see also [Snowflake Integration Guide](snowflake_integration.md). @@ -33,17 +35,36 @@ There are other ways that you can use UID2, outside these use cases. These are j - **Send in conversions**: You can send UID2s as conversion information that can be used for measurement (attribution) or retargeting via API or pixels - **Receive graph data**: You can receive UID2s from graph/data providers via API or pixels. --> -### High-Level Steps +## Key Integration Steps + +At a high level, to integrate with UID2 as an advertiser or data provider, you'll implement these three key activities: -At a high level, the steps for advertisers and data providers integrating with UID2 are as follows: +1. [Retrieve a raw UID2 for DII](#1-retrieve-a-raw-uid2-from-dii) -1. Generate a raw UID2 from directly identifying information (DII), or receive UID2s from another UID2 participant such as a data provider acting on your behalf. + Generate a raw UID2 from directly identifying information (DII), or receive UID2s from another UID2 participant such as a data provider acting on your behalf. + +2. [Send stored raw UID2s to DSPs to create audiences or conversions](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) -1. Use the UID2s you received in Step 1. For example, you might do one or more of the following: + 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. -1. Use the raw UID2s for some purpose such as measurement. + As part of this step, you'll also need to [monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s). + +3. Use the raw UID2s for some purpose such as measurement. + +There are several ways you can accomplish these key steps. + +## Integration Options Summary + +The following integration options are available for advertisers and data providers. + +| Integration Option | Integration Guide | Content Description | +| :--- | :--- | :--- | +| Client-Side JavaScript SDK |[Client-Side Integration Guide for JavaScript](integration-javascript-client-side.md) | A guide for advertisers and data providers who want to use this SDK for adding a UID2 token to their tracking pixels. | +| Snowflake | [Snowflake Integration Guide](snowflake_integration.md) | Instructions for generating UID2s from emails within Snowflake. | +| AWS Entity Resolution | [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md) | Instructions for integrating with the UID2 framework using AWS Entity Resolution. | +| Direct integration (API endpoints) | [xxx TBD](advertiser-dataprovider-identity-map.md) | Information about integrating directly to UID2 endpoints rather than using other integration options. | ## Integration Diagram @@ -56,16 +77,22 @@ DII refers to a user's normalized email address or phone number, or the normaliz Refer to the following sections for details about the different parts of the diagram: -1. [Retrieve a raw UID2 for DII using the identity map endpoints](#1-retrieve-a-raw-uid2-for-dii-using-the-identity-map-endpoint) +1. [Retrieve a raw UID2 for DII](#1-retrieve-a-raw-uid2-from-dii) 2. [Send stored raw UID2s to DSPs to create audiences or conversions](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) 3. [Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s) -### 1: Retrieve a raw UID2 for DII using the identity map endpoint +### 1: Retrieve a raw UID2 from DII -| Step | Endpoint | Description | -| --- | --- | --- | -| 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 [3: Monitor for salt bucket rotations](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s).
For ease of maintenance, a recommended approach is to store a user's raw UID2 and `bucket_id` in a mapping table. For guidance on incremental updates, see [Use an incremental process to continuously update raw UID2s](#use-an-incremental-process-to-continuously-update-raw-uid2s). | +The first step is to retrieve a raw UID2. You can do this by using any of the advertiser/data provider implementation options, summarized in the following table. + +[**GWH_SW all the SDKs support Map DII to Raw UID2s. Should I llist them also?**] + +| Integration Method | Link to Instructions | +| :--- | :--- | +| Client-Side SDK for JavaScript | [**GWH_SW: Now I'm confused because per https://unifiedid.com/docs/sdks/sdk-ref-javascript#functionality the JS SDK doesn't support generating a raw UID2 from DII. Not sure what we're talking about here, sorry**] | +| Snowflake | Snowflake Integration Guide, these sections: | +| AWS Entity Resolution | AWS Integration Guide, this seciton: [Integration Summary](integration-aws-entity-resolution.md#integration-summary) | +| [Direct integration (API endpoints)](advertiser-dataprovider-identity-map.md) | xxx TBD | ### 2: Send stored raw UID2s to DSPs to create audiences or conversions @@ -91,10 +118,10 @@ To ensure that your integration has the current raw UID2s, check salt bucket rot To keep your UID2-based audience information accurate and up to date, follow these integration steps every day: -1. The response from the [UID2 retrieval step](#1-retrieve-a-raw-uid2-for-dii-using-the-identity-map-endpoint) contains mapping information. Cache the following: +1. The response from the [UID2 retrieval step](#1-retrieve-a-raw-uid2-from-dii) contains mapping information. Cache the following: - The mapping between DII (`identifier`), raw UID2 (`advertising_id`), and salt bucket (`bucket_id`). - The most recent `last_updated` timestamp. -2. Using the results from Step 3, [Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s), remap any raw UID2 for which the salt buckets have been rotated by retrieving new raw UID2 for those IDs, following Step 1, [Retrieve a raw UID2 for DII using the identity map endpoint](#1-retrieve-a-raw-uid2-for-dii-using-the-identity-map-endpoint). +2. Using the results from Step 3, [Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s), remap any raw UID2 for which the salt buckets have been rotated by retrieving new raw UID2 for those IDs, following Step 1, [Retrieve a raw UID2 for DII using the identity map endpoint](#1-retrieve-a-raw-uid2-from-dii). Then, use the refreshed UID2s to update audiences or conversions, following Step 2, [send raw UID2 to a DSP](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions). diff --git a/docs/guides/summary-guides.md b/docs/guides/summary-guides.md index 89ddb0b83..7e6bb9043 100644 --- a/docs/guides/summary-guides.md +++ b/docs/guides/summary-guides.md @@ -33,7 +33,7 @@ Publisher integrations fall into the following main categories: ### Web Integrations -The following resources are available for publisher web integrations. +The following documentation resources are available for publisher web integrations. :::tip For a detailed summary of web integration options, see [Web Integration Overview](integration-options-publisher-web.md). @@ -52,7 +52,7 @@ For a detailed summary of web integration options, see [Web Integration Overview ### Mobile Integrations -The following resources are available for publishers integrating with Android or iOS devices. +The following documentation resources are available for publishers integrating with Android or iOS devices. | Integration Type| Documentation | Content Description | | :--- | :--- | :--- | @@ -62,7 +62,7 @@ The following resources are available for publishers integrating with Android or ### CTV Integrations -The following resources are available for publisher integrations supporting CTV. +The following documentation resources are available for publisher integrations supporting CTV. | Integration Guide | Content Description | | :--- | :--- | @@ -93,18 +93,18 @@ The following resources are available for publishers integrating with Google Ad ## Advertiser/Data Provider Integrations -The following resources are available for advertisers and data providers integrating with UID2. +The following documentation resources are available for advertisers and data providers integrating with UID2. | Integration Guide | Content Description | | :--- | :--- | -| [Advertiser/Data Provider](advertiser-dataprovider-guide.md) | This integration guide for advertisers and data providers covers integration workflows for mapping identity for audience-building and targeting. | +| [Advertiser/Data Provider](integration-options-advertiser-dataprovider.md) | This integration guide for advertisers and data providers covers integration workflows for mapping identity for audience-building and targeting. | | [Client-Side Integration Guide for JavaScript](integration-javascript-client-side.md) | A guide for advertisers and data providers who want to use this SDK for adding a UID2 token to their tracking pixels. | | [Snowflake Integration Guide](snowflake_integration.md) | Instructions for generating UID2s from emails within Snowflake. | | [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md) | Instructions for integrating with the UID2 framework using AWS Entity Resolution. | ## DSP Integrations -The following resources are available for DSPs integrating with UID2. +The following documentation resources are available for DSPs integrating with UID2. | Integration Guide | Content Description | | :--- | :--- | diff --git a/docs/overviews/overview-advertisers.md b/docs/overviews/overview-advertisers.md index 04360454e..40c014943 100644 --- a/docs/overviews/overview-advertisers.md +++ b/docs/overviews/overview-advertisers.md @@ -69,7 +69,7 @@ The following documentation resources are available for advertisers and data pro | Integration Type| Documentation | Content Description | | :--- | :--- | :--- | -| Integration steps for organizations that collect user data and push it to other UID2 participants | [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md) | This guide covers integration workflows for mapping identity for audience-building and targeting. | +| Integration steps for organizations that collect user data and push it to other UID2 participants | [Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md) | This guide covers integration workflows for mapping identity for audience-building and targeting. | | Integration steps for advertisers and data providers who want to use the client-side JavaScript SDK for adding a UID2 token to their tracking pixels. | [Client-Side Integration Guide for JavaScript](../guides/integration-javascript-client-side.md) | This guide provides instructions for generating UID2 tokens (advertising tokens) using only JavaScript client-side changes. | | Snowflake | [Snowflake Integration Guide](../guides/snowflake_integration.md) | This guide provides instructions for generating UID2s from emails within Snowflake. | | AWS Entity Resolution | [AWS Entity Resolution Integration Guide](../guides/integration-aws-entity-resolution.md) | This guide provides instructions for integrating with the UID2 framework using AWS Entity Resolution. | diff --git a/docs/overviews/overview-data-providers.md b/docs/overviews/overview-data-providers.md index 4b666cd3b..b9597e50e 100644 --- a/docs/overviews/overview-data-providers.md +++ b/docs/overviews/overview-data-providers.md @@ -74,7 +74,7 @@ The following documentation resources are available for advertisers and data pro | Integration Type| Documentation | Content Description | | :--- | :--- | :--- | -| Integration steps for organizations that collect user data and push it to other UID2 participants | [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md) | This guide covers integration workflows for mapping identity for audience-building and targeting. | +| Integration steps for organizations that collect user data and push it to other UID2 participants | [Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md) | This guide covers integration workflows for mapping identity for audience-building and targeting. | | Integration steps for advertisers and data providers who want to use the client-side JavaScript SDK for adding a UID2 token to their tracking pixels. | [Client-Side Integration Guide for JavaScript](../guides/integration-javascript-client-side.md) | This guide provides instructions for generating UID2 tokens (advertising tokens) using only JavaScript client-side changes. | | Snowflake | [Snowflake Integration Guide](../guides/snowflake_integration.md) | This guide provides instructions for generating UID2s from emails within Snowflake. | | AWS Entity Resolution | [AWS Entity Resolution Integration Guide](../guides/integration-aws-entity-resolution.md) | This guide provides instructions for integrating with the UID2 framework using AWS Entity Resolution. | diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-buckets.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-buckets.md index 7fd53d5ba..f983b2133 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-buckets.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-buckets.md @@ -11,7 +11,7 @@ import Link from '@docusaurus/Link'; ソルトバケットのローテーションをモニターします。 -Used by: このエンドポイントは、主に広告主とデータプロバイダーによって使用されます。詳細は [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md) を参照してください。 +Used by: このエンドポイントは、主に広告主とデータプロバイダーによって使用されます。詳細は [Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md) を参照してください。 ## Request Format diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md index 197813e65..ea21f4d42 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md @@ -11,7 +11,7 @@ import Link from '@docusaurus/Link'; 複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 とソルトバケット ID にマッピングします。このエンドポイントを使用して、オプトアウト情報の更新をチェックすることもできます -Used by: このエンドポイントは、主に広告主やデータプロバイダーが使用します。詳細は [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md) を参照してください。 +Used by: このエンドポイントは、主に広告主やデータプロバイダーが使用します。詳細は [Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md) を参照してください。 ## Batch Size and Request Parallelization Requirements @@ -20,7 +20,7 @@ Used by: このエンドポイントは、主に広告主やデータプロバ - リクエストの最大サイズは 1MB です。 - 大量のメールアドレス、電話番号、またはそれぞれのハッシュをマップするには、1 バッチあたり最大 5,000 アイテムのバッチサイズで、それらを *連続した* バッチで送信してください。 - Private Operator を使用している場合を除き、バッチを並行して送信しないでください。つまり、1 つの HTTP 接続を使用して、[directly identifying information (DII)](../ref-info/glossary-uid.md#gl-dii) を連続してマッピングしてください。 -- メールアドレス、電話番号、またはそれぞれのハッシュのマッピングを必ず保存してください。
マッピングを保存しないと、数百万のメールアドレスや電話番号をマッピングする必要がある場合に、処理時間が大幅に増加する可能性があります。しかし、実際に更新が必要なマッピングのみを再計算することで、毎日更新が必要な raw UID2 の数は約 1/365 となり、総処理時間を短縮できます。[Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md) と [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers) も参照してください。 +- メールアドレス、電話番号、またはそれぞれのハッシュのマッピングを必ず保存してください。
マッピングを保存しないと、数百万のメールアドレスや電話番号をマッピングする必要がある場合に、処理時間が大幅に増加する可能性があります。しかし、実際に更新が必要なマッピングのみを再計算することで、毎日更新が必要な raw UID2 の数は約 1/365 となり、総処理時間を短縮できます。[Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md) と [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers) も参照してください。 ## Request Format diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-optout-status.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-optout-status.md index a321f4558..166dc3585 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-optout-status.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-optout-status.md @@ -15,7 +15,7 @@ Used by: このエンドポイントは、主に広告主、データプロバ 詳細については、役割に応じて以下のドキュメントを参照してください: -- [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md) +- [Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md) - [DSP Integration Guide](../guides/dsp-guide.md) - [UID2 Sharing: Overview](../sharing/sharing-overview) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md index 9a67baa31..fd721af19 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md @@ -15,7 +15,7 @@ UID2 参加者はそれぞれ、固有の | :--- | :--- | :--- | | Client-Side 実装を使用する参加者 | 次の両方: これら 2 つをあわせて client keypair と呼ぶこともあります。 | 次のいずれかを使用したインテグレーション: | | Client-Server 実装を使用する参加者 | 次の両方: | 次のいずれかを使用したインテグレーション: | -| Server-Side 実装を使用する参加者 | 次の両方: | 次のいずれかを使用したインテグレーション: | +| Server-Side 実装を使用する参加者 | 次の両方: | 次のいずれかを使用したインテグレーション: | 本番環境だけでなくインテグレーション環境も使用している場合は、それぞれの環境用に別々の認証情報を取得します。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md index 54cae475a..316effee6 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md @@ -155,7 +155,7 @@ UID2 生成リクエストで提供されるメタデータには、UID2 の生 #### Do refreshed emails get assigned to the same bucket with which they were previously associated? 更新されたメールアドレスは、以前関連付けられていたバケットと同じバケットに割り当てられますか？ -必ずしもそうとは限りません。特定のバケット ID に関連付けられたメールアドレスを再マッピングした後、そのメールが異なるバケット ID に割り当てられる可能性があります。バケット ID を確認するには、[マッピング関数を呼び出す](../guides/advertiser-dataprovider-guide.md#1-retrieve-a-raw-uid2-for-dii-using-the-identity-map-endpoint) そして返された UID2 とバケット ID を再び保存してください。 +必ずしもそうとは限りません。特定のバケット ID に関連付けられたメールアドレスを再マッピングした後、そのメールが異なるバケット ID に割り当てられる可能性があります。バケット ID を確認するには、[マッピング関数を呼び出す](../guides/integration-options-advertiser-dataprovider.md#1-retrieve-a-raw-uid2-from-dii) そして返された UID2 とバケット ID を再び保存してください。 :::info メールアドレスのマッピングや再マッピングを行う際には、バケットの数やローテーションする日、メールアドレスが割り当てられる特定のバケットについて、いかなる仮定も行わないようにしてください。 @@ -198,7 +198,7 @@ Private Operator を使用している場合を除き、メールアドレス、 ただし、raw UID2 の生成に使用される [ソルト](../ref-info/glossary-uid.md#gl-salt) 値という可変要素があります。ソルト値は定期的にローテーションされます(詳細は [How often should UID2s be refreshed for incremental updates?](#how-often-should-uid2s-be-refreshed-for-incremental-updates)) を参照してください)。あるリクエストと別のリクエストの間でソルト値が変化する場合、DII が同じであっても、これら 2 つのリクエストは 2 つの異なる raw UID2 になります。 -詳細については、*Advertiser/Data Provider Integration Guide*の [Monitor for salt bucket rotations related to your stored raw UID2s](../guides/advertiser-dataprovider-guide.md#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s) を参照してください。 +詳細については、*Advertiser/Data Provider Integration Guide*の [Monitor for salt bucket rotations related to your stored raw UID2s](../guides/integration-options-advertiser-dataprovider.md#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s) を参照してください。 #### If two operators process the same DII, are the results the same? 2 つの Operator が同じ DII を処理した場合、結果は同じになりますか？ diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/advertiser-dataprovider-guide.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/advertiser-dataprovider-guide.bak similarity index 93% rename from i18n/ja/docusaurus-plugin-content-docs/current/guides/advertiser-dataprovider-guide.md rename to i18n/ja/docusaurus-plugin-content-docs/current/guides/advertiser-dataprovider-guide.bak index ccf8c96a1..cc8c7a22f 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/advertiser-dataprovider-guide.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/advertiser-dataprovider-guide.bak @@ -57,11 +57,11 @@ DII とは、正規化されたメールアドレスや電話番号、あるい 図の各部の詳細については、以下のセクションを参照してください: -1. [Retrieve a raw UID2 for DII using the identity map endpoints](#1-retrieve-a-raw-uid2-for-dii-using-the-identity-map-endpoint) +1. [Retrieve a raw UID2 for DII](#1-retrieve-a-raw-uid2-from-dii) 2. [Send stored raw UID2s to DSPs to create audiences or conversions](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) 3. [Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s) -### 1: Retrieve a raw UID2 for DII using the identity map endpoint +### 1: Retrieve a raw UID2 for DII | Step | Endpoint | Description | | --- | --- | --- | @@ -92,10 +92,10 @@ raw UID2 は、特定の時点のユーザーに対する識別子です。特 UID2 ベースのオーディエンス情報を正確かつ最新の状態に保つために、毎日以下のインテグレーション手順を実行してください: -1. [UID2 retrieval step](#1-retrieve-a-raw-uid2-for-dii-using-the-identity-map-endpoint) のレスポンスにはマッピング情報が含まれています。以下をキャッシュします: +1. [UID2 retrieval step](#1-retrieve-a-raw-uid2-from-dii) のレスポンスにはマッピング情報が含まれています。以下をキャッシュします: - DII (`identifier`) と raw UID2 (`advertising_id`) とソルトバケット (`bucket_id`) のマッピング。 - 最新の `last_updated` タイムスタンプ。 -2. Step 3の結果を使用して、[Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s)、 Step1 の [Retrieve a raw UID2 for DII using the identity map endpoint](#1-retrieve-a-raw-uid2-for-dii-using-the-identity-map-endpoint) に従って、ソルトバケットがローテーションされた ID の新しい raw UID2 を取得して、ソルトバケットの raw UID2 を再マッピングします。 +2. Step 3の結果を使用して、[Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s)、 Step1 の [Retrieve a raw UID2 for DII using the identity map endpoint](#1-retrieve-a-raw-uid2-from-dii) に従って、ソルトバケットがローテーションされた ID の新しい raw UID2 を取得して、ソルトバケットの raw UID2 を再マッピングします。 次に、Step 2 の[send raw UID2 to a DSP](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) に従って、リフレッシュされた UID2 を使ってオーディエンスまたはコンバージョンを更新します。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/advertiser-dataprovider-guide.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/guides/advertiser-dataprovider-guide.mdx new file mode 100644 index 000000000..ff280aa4f --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/advertiser-dataprovider-guide.mdx @@ -0,0 +1,3 @@ +import { Redirect } from '@docusaurus/router'; + +; diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/advertiser-dataprovider-identity-map.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/advertiser-dataprovider-identity-map.md new file mode 100644 index 000000000..3f615cf5f --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/advertiser-dataprovider-identity-map.md @@ -0,0 +1,16 @@ +--- +title: Advertiser/Data Provider Integration Steps +sidebar_label: Advertiser/Data Provider Integration Steps +description: TBD +hide_table_of_contents: false +sidebar_position: 07 +displayed_sidebar: sidebarAdvertisers +--- + +import Link from '@docusaurus/Link'; + +# Advertiser/Data Provider Integration Steps + +COPY XXX TBD UPTOHERE + + diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-options-advertiser-dataprovider.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-options-advertiser-dataprovider.md new file mode 100644 index 000000000..95bda0418 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-options-advertiser-dataprovider.md @@ -0,0 +1,138 @@ +--- +title: Advertiser/Data Provider Integration Overview +sidebar_label: Advertiser/Data Provider Integration Overview +description: Overview of UID2 integration options for organizations that collect user data and push it to other participants. +hide_table_of_contents: false +sidebar_position: 07 +displayed_sidebar: sidebarAdvertisers +--- + +import Link from '@docusaurus/Link'; + +# Advertiser/Data Provider Integration Overview + +There are many ways for advertisers and data providers to integration with UID2. On this page, you'll find a high-level overview of integration steps and integration options, with links to additional information for each option. + +These integration options apply to any 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. + +If you are using an Open Operator service hosted in the Snowflake Data Marketplace, see also [Snowflake Integration Guide](snowflake_integration.md). + +## Advertiser/Data Provider Routes to Use UID2 + +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 | Send UID2s via API or pixels | Create audiences. | +| Send | Send UID2s as conversion information | Use conversion information for measurement (attribution) or for retargeting via API or pixels. | +| Receive | Receive UID2s from graph/data providers via API or pixels | Build graph data. | + + + +## Key Integration Steps + +At a high level, to integrate with UID2 as an advertiser or data provider, you'll implement these three key activities: + +1. [Retrieve a raw UID2 for DII](#1-retrieve-a-raw-uid2-from-dii) + + Generate a raw UID2 from directly identifying information (DII), or receive UID2s from another UID2 participant such as a data provider acting on your behalf. + +2. [Send stored raw UID2s to DSPs to create audiences or conversions](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) + + 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. + + As part of this step, you'll also need to [monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s). + +3. Use the raw UID2s for some purpose such as measurement. + +There are several ways you can accomplish these key steps. + +## Integration Options Summary + +The following integration options are available for advertisers and data providers. + +| Integration Option | Integration Guide | Content Description | +| :--- | :--- | :--- | +| Client-Side JavaScript SDK |[Client-Side Integration Guide for JavaScript](integration-javascript-client-side.md) | A guide for advertisers and data providers who want to use this SDK for adding a UID2 token to their tracking pixels. | +| Snowflake | [Snowflake Integration Guide](snowflake_integration.md) | Instructions for generating UID2s from emails within Snowflake. | +| AWS Entity Resolution | [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md) | Instructions for integrating with the UID2 framework using AWS Entity Resolution. | +| Direct integration (API endpoints) | [xxx TBD](advertiser-dataprovider-identity-map.md) | Information about integrating directly to UID2 endpoints rather than using other integration options. | + +## 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-mermaid.png) + + + +Refer to the following sections for details about the different parts of the diagram: +1. [Retrieve a raw UID2 for DII](#1-retrieve-a-raw-uid2-from-dii) +2. [Send stored raw UID2s to DSPs to create audiences or conversions](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) +3. [Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s) + +### 1: Retrieve a raw UID2 from DII + +The first step is to retrieve a raw UID2. You can do this by using any of the advertiser/data provider implementation options, summarized in the following table. + +[**GWH_SW all the SDKs support Map DII to Raw UID2s. Should I llist them also?**] + +| Integration Method | Link to Instructions | +| :--- | :--- | +| Client-Side SDK for JavaScript | [**GWH_SW: Now I'm confused because per https://unifiedid.com/docs/sdks/sdk-ref-javascript#functionality the JS SDK doesn't support generating a raw UID2 from DII. Not sure what we're talking about here, sorry**] | +| Snowflake | Snowflake Integration Guide, these sections:
  • [Access the UID2 Shares](snowflake_integration.md#access-the-uid2-shares)
  • [Shared Objects](snowflake_integration.md#shared-objects)
| +| AWS Entity Resolution | AWS Integration Guide, this seciton: [Integration Summary](integration-aws-entity-resolution.md#integration-summary) | +| [Direct integration (API endpoints)](advertiser-dataprovider-identity-map.md) | xxx TBD | + +### 2: Send stored raw UID2s to DSPs to create audiences or conversions + +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. + +### 3: Monitor for salt bucket rotations related to 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 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. + +:::important +To ensure that your integration has the current raw UID2s, check salt bucket rotation for active users every day. +::: + +| Step | Endpoint | Description | +| --- | --- | --- | +| 3-a | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | Send a request to the bucket status endpoint for all salt buckets that have changed since a specific timestamp. | +| 3-b | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | UID2 service: The bucket status endpoint returns a list of `bucket_id` and `last_updated` timestamps. | +| 3-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 identity mapping service for a new raw UID2. | +| 3-d | [POST /identity/map](../endpoints/post-identity-map.md) | Store the new values returned for `advertising_id` and `bucket_id`. | + +## Use an Incremental Process to Continuously Update Raw UID2s + +To keep your UID2-based audience information accurate and up to date, follow these integration steps every day: + +1. The response from the [UID2 retrieval step](#1-retrieve-a-raw-uid2-from-dii) contains mapping information. Cache the following: + - The mapping between DII (`identifier`), raw UID2 (`advertising_id`), and salt bucket (`bucket_id`). + - The most recent `last_updated` timestamp. +2. Using the results from Step 3, [Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s), remap any raw UID2 for which the salt buckets have been rotated by retrieving new raw UID2 for those IDs, following Step 1, [Retrieve a raw UID2 for DII using the identity map endpoint](#1-retrieve-a-raw-uid2-from-dii). + + Then, use the refreshed UID2s to update audiences or conversions, following Step 2, [send raw UID2 to a DSP](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions). + +## Check Opt-Out Status + +It's important to honor user opt-out status. Here are two ways you can check that you have the latest opt-out information: + +- The UID2 Operator Service distributes opt-out information to advertisers and data providers via the [POST /identity/map](../endpoints/post-identity-map.md) endpoint. + +- Advertisers and data providers can check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. + +## 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). diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/summary-guides.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/summary-guides.md index bab51ad44..aa72741d6 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/summary-guides.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/summary-guides.md @@ -97,7 +97,7 @@ UID2 とインテグレーションする広告主やデータプロバイダー | Integration Guide | Content Description | | :--- | :--- | -| [Advertiser/Data Provider](./advertiser-dataprovider-guide.md) | この広告主やデータプロバイダー向けのインテグレーションガイドは、オーディエンスの構築とターゲティングのためのアイデンティティマッピングのためのインテグレーションワークフローをカバーしています。 | +| [Advertiser/Data Provider](./integration-options-advertiser-dataprovider.md) | この広告主やデータプロバイダー向けのインテグレーションガイドは、オーディエンスの構築とターゲティングのためのアイデンティティマッピングのためのインテグレーションワークフローをカバーしています。 | | [Client-Side Integration Guide for JavaScript](integration-javascript-client-side.md) | トラッキングピクセルに UID2 Token を追加するためにこの SDK を使用したい広告主やデータプロバイダー向けのガイドです。 | | [Snowflake Integration Guide](snowflake_integration.md) | Snowflake 内でメールアドレスから UID2 を生成する手順です。| | [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md) | AWS Entity Resolution を使用して UID2 フレームワークとインテグレーションする手順です。 | diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-advertisers.md b/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-advertisers.md index f7657343c..feecb435e 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-advertisers.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-advertisers.md @@ -69,7 +69,7 @@ UID2 のドキュメント一式に左サイドバーからアクセスしたい | Integration Type| Documentation | Content Description | | :--- | :--- | :--- | -| ユーザーデータを収集し、他の UID2 参加者にプッシュする組織のためのインテグレーション手順 | [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md) | このガイドでは、オーディエンスの構築とターゲティングのために ID をマッピングするインテグレーションワークフローについて説明します。 | +| ユーザーデータを収集し、他の UID2 参加者にプッシュする組織のためのインテグレーション手順 | [Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md) | このガイドでは、オーディエンスの構築とターゲティングのために ID をマッピングするインテグレーションワークフローについて説明します。 | | トラッキングピクセルに UID2 Token を追加する広告主およびデータプロバイダー向けのインテグレーション手順 | [Client-Side Integration Guide for JavaScript](../guides/integration-javascript-client-side.md) | このガイドでは、JavaScript クライアントサイドの変更のみを使用して、Advertising Token を追加するための JavaScript SDK を使用する広告主およびデータプロバイダー向けのインテグレーション手順を提供します。 | | Snowflake | [Snowflake Integration Guide](../guides/snowflake_integration.md) | このガイドでは、Snowflake を使ってメールアドレスから UID2 を生成する手順を説明します。 | | AWS Entity Resolution | [AWS Entity Resolution Integration Guide](../guides/integration-aws-entity-resolution.md) | このガイドでは、AWS Entity Resolution を使用して UID2 とインテグレーションする手順を説明します。 | diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-data-providers.md b/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-data-providers.md index 6accea673..4d25550d8 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-data-providers.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/overviews/overview-data-providers.md @@ -74,7 +74,7 @@ UID2 を使用することで、データプロバイダーとして得られる | Integration Type| Documentation | Content Description | | :--- | :--- | :--- | -| ユーザーデータを収集し、他の UID2 参加者にプッシュする組織のためのインテグレーション手順 | [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md) | このガイドでは、オーディエンスの構築とターゲティングのために ID をマッピングするインテグレーションワークフローについて説明します。 | +| ユーザーデータを収集し、他の UID2 参加者にプッシュする組織のためのインテグレーション手順 | [Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md) | このガイドでは、オーディエンスの構築とターゲティングのために ID をマッピングするインテグレーションワークフローについて説明します。 | | トラッキングピクセルに UID2 Token を追加する広告主およびデータプロバイダー向けのインテグレーション手順 | [Client-Side Integration Guide for JavaScript](../guides/integration-javascript-client-side.md) | このガイドでは、JavaScript クライアントサイドの変更のみを使用して、Advertising Token を追加するための JavaScript SDK を使用する広告主およびデータプロバイダー向けのインテグレーション手順を提供します。 | | Snowflake | [Snowflake Integration Guide](../guides/snowflake_integration.md) | このガイドでは、Snowflake を使ってメールアドレスから UID2 を生成する手順を説明します。 | | AWS Entity Resolution | [AWS Entity Resolution Integration Guide](../guides/integration-aws-entity-resolution.md) | このガイドでは、AWS Entity Resolution を使用して UID2 とインテグレーションする手順を説明します。 | diff --git a/sidebars.js b/sidebars.js index dd7572f3e..d7443e53a 100644 --- a/sidebars.js +++ b/sidebars.js @@ -182,14 +182,15 @@ const fullSidebar = [ type: 'category', label: 'Advertiser/Data Provider Integrations', link: { - type: 'generated-index', + type: 'doc', + id: 'guides/integration-options-advertiser-dataprovider', }, collapsed: true, items: [ - 'guides/advertiser-dataprovider-guide', 'guides/integration-javascript-client-side', 'guides/snowflake_integration', 'guides/integration-aws-entity-resolution', + 'guides/advertiser-dataprovider-identity-map', ], }, @@ -323,9 +324,10 @@ const sidebars = { 'overviews/overview-dsps', 'overviews/overview-data-providers', 'Advertiser/Data Provider Integrations', - 'guides/advertiser-dataprovider-guide', + 'guides/integration-options-advertiser-dataprovider', 'guides/snowflake_integration', 'guides/integration-aws-entity-resolution', + 'guides/advertiser-dataprovider-identity-map', 'guides/dsp-guide', 'endpoints/post-identity-buckets', 'endpoints/post-identity-map', @@ -402,9 +404,10 @@ const sidebars = { 'guides/mobile-plugin-gma-ios', 'guides/mobile-plugin-ima-android', 'guides/mobile-plugin-ima-ios', - 'guides/advertiser-dataprovider-guide', + 'guides/integration-options-advertiser-dataprovider', 'guides/snowflake_integration', 'guides/integration-aws-entity-resolution', + 'guides/advertiser-dataprovider-identity-map', 'sharing/sharing-bid-stream' ),