diff --git a/docs/endpoints/post-identity-buckets.md b/docs/endpoints/post-identity-buckets.md index b5bd5054a..671914468 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-advertiser-dataprovider-overview.md). ## Request Format diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index 7f9c7bfc9..201d6e9d7 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-advertiser-dataprovider-overview.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). @@ -22,7 +22,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 send batches of hashed or unhashed directly identifying information (DII) values consecutively, without creating multiple parallel connections. -- Be sure to store mappings of email addresses, phone numbers, or their respective hashes.
Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of 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 could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of raw UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Guide](../guides/integration-advertiser-dataprovider-overview.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). ## Request Format @@ -59,7 +59,7 @@ You must include only **one** of the following four conditional parameters as a ### Request Examples -The following are unencrypted JSON request body examples for each parameter, one of which you should include in your identity mapping requests: +The following are unencrypted JSON request body examples for each parameter, one of which you should include in your requests to the `POST /identity/map` endpoint: ```json { @@ -94,7 +94,7 @@ The following are unencrypted JSON request body examples for each parameter, one } ``` -Here's an encrypted identity mapping request example for a phone number: +Here's an encrypted request example to the `POST /identity/map` endpoint for a phone number: ```sh echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/map [Your-Client-API-Key] [Your-Client-Secret] diff --git a/docs/endpoints/post-optout-status.md b/docs/endpoints/post-optout-status.md index 0cd85de07..e6c38d421 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-advertiser-dataprovider-overview.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 ec19025d4..aeb656379 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 unique c | :--- | :--- | :--- | | 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 4b9ee70f5..ddcdafb98 100644 --- a/docs/getting-started/gs-faqs.md +++ b/docs/getting-started/gs-faqs.md @@ -177,7 +177,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, see [Generate Raw UID2s from DII](../guides/integration-advertiser-dataprovider-overview.md#1-generate-raw-uid2s-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. @@ -215,7 +215,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 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*. #### If two operators process the same DII, are the results the same? diff --git a/docs/guides/advertiser-dataprovider-guide.md b/docs/guides/advertiser-dataprovider-guide.md deleted file mode 100644 index f2a975765..000000000 --- a/docs/guides/advertiser-dataprovider-guide.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -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. -hide_table_of_contents: false -sidebar_position: 07 -displayed_sidebar: sidebarAdvertisers ---- - -import Link from '@docusaurus/Link'; - -# Advertiser/Data Provider Integration Guide - -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 a Public 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. The following table shows some examples of how you, as an advertiser or as a data provider acting on behalf of an advertiser, 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. | - - - -### High-Level 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. - -## 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 using the identity map endpoint](#1-retrieve-a-raw-uid2-for-dii-using-the-identity-map-endpoint) -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 - -| 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). | - -### 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-for-dii-using-the-identity-map-endpoint) 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). - - 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. - -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). diff --git a/docs/guides/advertiser-dataprovider-guide.mdx b/docs/guides/advertiser-dataprovider-guide.mdx new file mode 100644 index 000000000..88feabe6d --- /dev/null +++ b/docs/guides/advertiser-dataprovider-guide.mdx @@ -0,0 +1,3 @@ +import { Redirect } from '@docusaurus/router'; + +; diff --git a/docs/guides/images/advertiser-flow-endpoints-mermaid.png b/docs/guides/images/advertiser-flow-endpoints-mermaid.png new file mode 100644 index 000000000..6b9d3ee9d Binary files /dev/null and b/docs/guides/images/advertiser-flow-endpoints-mermaid.png differ diff --git a/docs/guides/images/advertiser-flow-mermaid.png b/docs/guides/images/advertiser-flow-mermaid.png deleted file mode 100644 index 627dc7666..000000000 Binary files a/docs/guides/images/advertiser-flow-mermaid.png and /dev/null differ diff --git a/docs/guides/images/advertiser-flow-overview-mermaid.png b/docs/guides/images/advertiser-flow-overview-mermaid.png new file mode 100644 index 000000000..f1b258069 Binary files /dev/null and b/docs/guides/images/advertiser-flow-overview-mermaid.png differ diff --git a/docs/guides/images/resource/advertiser-flow-endpoints-mermaid.md.bak b/docs/guides/images/resource/advertiser-flow-endpoints-mermaid.md.bak new file mode 100644 index 000000000..6223664e3 --- /dev/null +++ b/docs/guides/images/resource/advertiser-flow-endpoints-mermaid.md.bak @@ -0,0 +1,71 @@ +>DSP: Send stored raw UID2s to DSPs to create audiences and conversions, or use them for measurement. + Note over ADP,DSP: 5. Monitor for salt bucket rotation. + loop + ADP->>UID: 5-a. Monitor salt bucket rotations using the POST /identity/buckets endpoint. + UID->>ADP: 5-b. Return salt buckets rotated since a specified timestamp. + ADP->>UID: 5-c. Compare the rotated salt buckets to the stored UID2 salt buckets.
If rotated, resend DII to the POST /identity/map endpoint for a new raw UID2. + UID->>ADP: 5-d. Store the raw UID2 and the salt bucket ID 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 + +--> + + + + + + + + + sequenceDiagram + participant DP as Data Provider + participant UID2 as UID2 Operator + participant DSP + loop 1. Retrieve a UID2 for DII using the identity map endpoint. + DP->>UID2: 1-a. Send a request containing DII to the identity mapping endpoints. + UID2->>DP: 1-b. Store the raw UID2 and salt bucket returned from the POST /identity/map endpoint. + end + DP-->>DSP: 2. Send stored UID2s to DSPs to create audiences and conversions. + + loop 3. Monitor for salt bucket rotations related to your stored raw UID2s. + DP->>UID2: 3-a. Monitor salt bucket rotations using the bucket service. + UID2->>DP: 3-b. Return salt buckets rotated since a specified timestamp. + DP->>UID2: 3-c. Compare the rotated salt buckets to the stored UID2 salt buckets.
If rotated, resend DII to the POST /identity/map endpoint for a new raw UID2. + UID2->>DP: 3-d. Store the raw UID2 and the salt bucket returned from the POST /identity/map endpoint. + end + + + + + diff --git a/docs/guides/images/resource/advertiser-flow-mermaid.md.bak b/docs/guides/images/resource/advertiser-flow-mermaid.md.bak deleted file mode 100644 index 4b723e330..000000000 --- a/docs/guides/images/resource/advertiser-flow-mermaid.md.bak +++ /dev/null @@ -1,42 +0,0 @@ - - - - - - - - sequenceDiagram - participant DP as Data Provider - participant UID2 as UID2 Operator - participant DSP - loop 1. Retrieve a UID2 for DII using the identity map endpoint. - DP->>UID2: 1-a. Send a request containing DII to the identity mapping endpoints. - UID2->>DP: 1-b. Store the raw UID2 and salt bucket returned from the identity mapping service. - end - DP-->>DSP: 2. Send stored UID2s to DSPs to create audiences and conversions. - - loop 3. Monitor for salt bucket rotations related to your stored raw UID2s. - DP->>UID2: 3-a. Monitor salt bucket rotations using the bucket service. - UID2->>DP: 3-b. Return salt buckets rotated since a specified timestamp. - DP->>UID2: 3-c. Compare the rotated salt buckets to the stored UID2 salt buckets.
If rotated, resend DII to identity mapping service for a new raw UID2. - UID2->>DP: 3-d. Store the raw UID2 and the salt bucket returned from the identity mapping service. - end - - - - - - diff --git a/docs/guides/images/resource/advertiser-flow-overview-mermaid.md.bak b/docs/guides/images/resource/advertiser-flow-overview-mermaid.md.bak new file mode 100644 index 000000000..597c99596 --- /dev/null +++ b/docs/guides/images/resource/advertiser-flow-overview-mermaid.md.bak @@ -0,0 +1,114 @@ +1/2/25: Reworking the ADP diagram for six steps as discussed with AnDe. Sent to her for review but checking in these mods. + +>DSP: Send stored raw UID2s to DSPs to create audiences and conversions, or use them for measurement. + Note over ADP,DSP: 5. Monitor for salt bucket rotation. + loop + ADP->>UID: 5-a. Monitor salt bucket rotations using the Python SDK, Snowflake, or HTTP endpoints. + UID->>ADP: 5-b. Return salt buckets rotated since a specified timestamp. + ADP->>UID: 5-c. Compare the rotated salt buckets to the stored UID2 salt buckets.
If rotated, resend DII to the option you're using in Step 1 to get a new raw UID2. + UID->>ADP: 5-d. Store the raw UID2 and the salt bucket that are returned. + 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 + +--> + + + +>DSP: Send stored raw UID2s to DSPs to create audiences and conversions, or use them for measurement. + Note over ADP,DSP: 5. Monitor for salt bucket rotation. + loop + ADP->>UID: 5-a. Monitor salt bucket rotations using the bucket service. + UID->>ADP: 5-b. Return salt buckets rotated since a specified timestamp. + ADP->>UID: 5-c. Compare the rotated salt buckets to the stored UID2 salt buckets.
If rotated, resend DII to identity mapping service for a new raw UID2. + UID->>ADP: 5-d. Store the raw UID2 and the salt bucket returned from the identity mapping service. + 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 + +--> + + + + + + + + + sequenceDiagram + participant DP as Data Provider + participant UID2 as UID2 Operator + participant DSP + loop 1. Retrieve a UID2 for DII using the identity map endpoint. + DP->>UID2: 1-a. Send a request containing DII to the identity mapping endpoints. + UID2->>DP: 1-b. Store the raw UID2 and salt bucket returned from the identity mapping service. + end + DP-->>DSP: 2. Send stored UID2s to DSPs to create audiences and conversions. + + loop 3. Monitor for salt bucket rotations related to your stored raw UID2s. + DP->>UID2: 3-a. Monitor salt bucket rotations using the bucket service. + UID2->>DP: 3-b. Return salt buckets rotated since a specified timestamp. + DP->>UID2: 3-c. Compare the rotated salt buckets to the stored UID2 salt buckets.
If rotated, resend DII to identity mapping service for a new raw UID2. + UID2->>DP: 3-d. Store the raw UID2 and the salt bucket returned from the identity mapping service. + end + + + + + + diff --git a/docs/guides/integration-advertiser-dataprovider-endpoints.md b/docs/guides/integration-advertiser-dataprovider-endpoints.md new file mode 100644 index 000000000..44eba2142 --- /dev/null +++ b/docs/guides/integration-advertiser-dataprovider-endpoints.md @@ -0,0 +1,118 @@ +--- +title: Advertiser/Data Provider Integration to HTTP Endpoints +sidebar_label: HTTP Endpoints +description: Integration for organizations that collect user data and push it to other participants, coding to HTTP endpoints rather than an SDK or Snowflake. +hide_table_of_contents: false +sidebar_position: 07 +displayed_sidebar: sidebarAdvertisers +--- + +import Link from '@docusaurus/Link'; + +# 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 options 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). +::: + +## 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) + +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) + +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.png) + + + +### 1: Generate Raw UID2s 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 [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 + +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 + +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 + +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 + +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). + +The following table shows the steps for checking for salt bucket rotation. + +| Step | Endpoint | Description | +| --- | --- | --- | +| 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](../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 + +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. + +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 + +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](../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). diff --git a/docs/guides/integration-advertiser-dataprovider-overview.md b/docs/guides/integration-advertiser-dataprovider-overview.md new file mode 100644 index 000000000..062654d53 --- /dev/null +++ b/docs/guides/integration-advertiser-dataprovider-overview.md @@ -0,0 +1,160 @@ +--- +title: Advertiser/Data Provider Integration Overview +sidebar_label: Advertiser/Data Provider Integration Overview +description: Overview of integration options for organizations that collect user data and push it to other participants. +hide_table_of_contents: false +sidebar_position: 07 +--- + +import Link from '@docusaurus/Link'; + +# Advertiser/Data Provider Integration Overview + +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 + +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 + +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) + +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) + +6. [Monitor for Opt-Out Status](#6-monitor-for-opt-out-status) + +## Summary of Implementation Options + +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. | + +## 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. + +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 + +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](snowflake_integration.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 + +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 + +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 + +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 + +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). + +For instructions for monitoring for salt bucket rotations, refer to one of the following: + +- Python SDK: [Monitor Rotated Salt Buckets](../sdks/sdk-ref-python.md#monitor-rotated-salt-buckets). + +- Snowflake: [Monitor for Salt Bucket Rotation and Regenerate Raw UID2s](snowflake_integration.md#monitor-for-salt-bucket-rotation-and-regenerate-raw-uid2s). + +- HTTP endpoints: [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s](integration-advertiser-dataprovider-endpoints.md#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s). + +:::note +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 + +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. + +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 + +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](../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 + +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/integration-aws-entity-resolution.md b/docs/guides/integration-aws-entity-resolution.md index 155f7beea..c70622d9f 100644 --- a/docs/guides/integration-aws-entity-resolution.md +++ b/docs/guides/integration-aws-entity-resolution.md @@ -13,7 +13,7 @@ import Link from '@docusaurus/Link'; [AWS Entity Resolution](https://aws.amazon.com/entity-resolution/) is an identity resolution product from Amazon Web Services that allows AWS customers to integrate with the UID2 framework. Through the integration, you can securely and seamlessly generate UID2s for your data without making direct calls to the UID2 operator or handling sensitive client ID and secret key values. -This service allows you to map DII (email addresses or phone numbers) to raw UID2s swiftly and securely. +This service allows you to map DII (email addresses or phone numbers) to [raw UID2s](../ref-info/glossary-uid.md#gl-raw-uid2) swiftly and securely. :::note If you're not currently part of the UID2 ecosystem, go to the [Request Access to UID2](https://unifiedid.com/request-access) page. @@ -21,6 +21,10 @@ If you're not currently part of the UID2 ecosystem, go to the [Request Access to For a video presentation about integration with UID2 by using AWS Entity Resolution, and a demo, see [Getting Started with AWS Entity Resolution Integration with Unified ID 2.0](https://www.youtube.com/watch?v=ORbSsKMgVj8) on YouTube. +:::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). +::: + ## Functionality The following table summarizes the functionality available with the AWS Entity Resolution integration. diff --git a/docs/guides/integration-prebid-client-side.md b/docs/guides/integration-prebid-client-side.md index 4e2f1c0a6..104861112 100644 --- a/docs/guides/integration-prebid-client-side.md +++ b/docs/guides/integration-prebid-client-side.md @@ -45,7 +45,6 @@ You'll need to complete the following steps: 2. [Add Prebid.js to your site](#add-prebidjs-to-your-site). 3. [Configure the UID2 module](#configure-the-uid2-module). - ### Complete UID2 Account Setup Complete the UID2 account setup by following the steps described in the [Account Setup](../getting-started/gs-account-setup.md) page. As part of the account setup process for a client-side implementation, you'll need to provide a list of **domain names** for the sites that you'll be using with Prebid.js. diff --git a/docs/guides/snowflake_integration.md b/docs/guides/snowflake_integration.md index 54034f79f..b842b42d6 100644 --- a/docs/guides/snowflake_integration.md +++ b/docs/guides/snowflake_integration.md @@ -17,6 +17,10 @@ The following listings for UID2 are available on the Snowflake marketplace: - For advertisers: [Unified ID 2.0: Advertiser Identity Solution](https://app.snowflake.com/marketplace/listing/GZT0ZRYXTMV/unified-id-2-0-unified-id-2-0-advertiser-identity-solution?originTab=provider&providerName=Unified+ID+2.0) - For data providers: [Unified ID 2.0: Data Provider Identity Solution](https://app.snowflake.com/marketplace/listing/GZT0ZRYXTN0/unified-id-2-0-unified-id-2-0-data-provider-identity-solution?originTab=provider&providerName=Unified+ID+2.0) +:::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). +::: + ## Functionality The following table summarizes the functionality available with the UID2 Snowflake integration. @@ -82,7 +86,7 @@ The following functions are deprecated in favor of `FN_T_UID2_IDENTITY_MAP`. You If you are using the deprecated functions, and need help migrating to the newer function, see [Migration Guide](#migration-guide). ::: -To identify the UID2s that you must regenerate, use the `UID2_SALT_BUCKETS` view from the UID2 Share. For details, see [Regenerate UID2s](#regenerate-uid2s). +To identify the UID2s that you must regenerate, use the `UID2_SALT_BUCKETS` view from the UID2 Share. For details, see [Monitor for Salt Bucket Rotation and Regenerate Raw UID2s](#monitor-for-salt-bucket-rotation-and-regenerate-raw-uid2s). The following functions are also available, for UID2 sharing participants: - `FN_T_UID2_ENCRYPT` (See [Encrypt Tokens](#encrypt-tokens)) @@ -404,7 +408,7 @@ The following table identifies each item in the response, including `NULL` value +----+----------------------------------------------+----------------------------------------------+------------+--------------------+ ``` -### Regenerate UID2s +### Monitor for Salt Bucket Rotation and Regenerate Raw UID2s The `UID2_SALT_BUCKETS` view query returns the date and time when the second-level salt buckets were last updated. Second-level salt is used when generating UID2s. When the salt in the bucket is updated, the previously generated UID2 becomes outdated and doesn’t match the UID2 generated by other parties for the same user. diff --git a/docs/guides/summary-guides.md b/docs/guides/summary-guides.md index 89f8fbbf3..0a2a45f20 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 Guide | 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-advertiser-dataprovider-overview.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..6aaddfec9 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-advertiser-dataprovider-overview.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..d0bc36dfa 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-advertiser-dataprovider-overview.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/ref-info/glossary-uid.md b/docs/ref-info/glossary-uid.md index f6fb08b82..fa7c4221e 100644 --- a/docs/ref-info/glossary-uid.md +++ b/docs/ref-info/glossary-uid.md @@ -389,11 +389,11 @@ import Link from '@docusaurus/Link';
Salt
-
A string of characters that is used in the process of transforming an email address or phone number into a secure, opaque value that cannot by itself be traced back to the original value.
+
A string of characters that is used in the process of transforming an email address or phone number into a secure, opaque value that cannot by itself be traced back to the original value (raw UID2 or UID2 token).
The UID2 service uses salt as part of the process, along with hashing and encryption, to secure the original value. Salt is added to the input value before hashing.
Salt bucket
-
A salt bucket is used to manage secret salt values over time. Each bucket contains a single current salt value, which remains active for approximately one year before being rotated to a new value. Buckets can be updated independently of one another.
+
A salt bucket is used to manage secret salt values, used to generate raw UID2s or UID2 tokens, over time. Each bucket contains a single current salt value, which remains active for approximately one year before being rotated to a new value. Buckets can be updated independently of one another.
There are just over one million salt buckets, and each email address or phone number is assigned to a specific bucket in a deterministic manner. However, this assignment is not permanent; it might change when the bucket's current secret salt is rotated to a new value.
Salt bucket ID
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 633bacf23..8301cb42c 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'; salt buckets のローテーションをモニターします。 -Used by: このエンドポイントは、主に広告主とデータプロバイダーによって使用されます。詳細は [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md) を参照してください。 +Used by: このエンドポイントは、主に広告主とデータプロバイダーによって使用されます。詳細は [Advertiser/Data Provider Integration Guide](../guides/integration-advertiser-dataprovider-overview.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 ff5949ef8..7212e6674 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 と salt bucket IDs にマッピングします。このエンドポイントを使用して、オプトアウト情報の更新をチェックすることもできます -Used by: このエンドポイントは、主に広告主やデータプロバイダーが使用します。詳細は [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md) を参照してください。 +Used by: このエンドポイントは、主に広告主やデータプロバイダーが使用します。詳細は [Advertiser/Data Provider Integration Guide](../guides/integration-advertiser-dataprovider-overview.md) を参照してください。 UID2 の Opt-Out ワークフローとユーザーが Opt-Out する方法の詳細については、[User Opt-Out](../getting-started/gs-opt-out.md) を参照してください。 @@ -22,7 +22,7 @@ UID2 の Opt-Out ワークフローとユーザーが Opt-Out する方法の詳 - リクエストの最大サイズは 1MB です。 - 大量のメールアドレス、電話番号、またはそれぞれのハッシュをマップするには、1 バッチあたり最大 5,000 アイテムのバッチサイズで、それらを *連続した* バッチで送信してください。 - Private Operator を使用している場合を除き、バッチを並行して送信しないでください。つまり、単一の 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-advertiser-dataprovider-overview.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 fc5204ab7..15931fc5b 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-advertiser-dataprovider-overview.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 3ec473075..a8575e828 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 2ccc5b3e1..79f6383d0 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 @@ -185,7 +185,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-advertiser-dataprovider-overview.md#1-generate-raw-uid2s-from-dii) そして返された UID2 とバケット ID を再び保存してください。 :::info メールアドレスのマッピングや再マッピングを行う際には、バケットの数やローテーションする日、メールアドレスが割り当てられる特定のバケットについて、いかなる仮定も行わないようにしてください。 @@ -228,7 +228,7 @@ UID2 生成リクエストで提供されるメタデータには、UID2 の生 ただし、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-advertiser-dataprovider-overview.md#5-monitor-for-salt-bucket-rotations-for-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.md deleted file mode 100644 index abab25412..000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/advertiser-dataprovider-guide.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Advertiser/Data Provider Integration -sidebar_label: Advertiser/Data Provider Integration Guide -description: ユーザーデータを収集し、それを他の UID2 参加者にプッシュする組織のためのインテグレーション手順。 -hide_table_of_contents: false -sidebar_position: 07 -displayed_sidebar: sidebarAdvertisers ---- - -import Link from '@docusaurus/Link'; - -# Advertiser/Data Provider Integration Guide - -このガイドでは、ユーザーデータを収集し、DSP にプッシュする組織のためのインテグレーション手順について説明します。データコレクターには、広告主、データオンボーダー、測定プロバイダー、ID グラフプロバイダー、サードパーティデータプロバイダー、および DSP にデータを送信する他の組織が含まれます。 - -Snowflake Data Marketplace でホストされる Public Operator Service を使用する場合は、[Snowflake Integration Guide](../guides/snowflake_integration.md) も参照してください。 - -## Advertiser/Data Provider Routes to Use UID2 - -アドテクノロジー業界では、広告主は ID を使用してオーディエンスを構築し、コンバージョンを追跡し、グラフを生成します。広告主または広告主の代理としてデータプロバイダーが UID2 を使用してこれらの目標を達成する方法の例を以下に示します。 - -:::note -これらのユースケース以外にも、UID2 を使用する方法はあります。これらはいくつかの例です。 -::: - -| Send/Receive? | Action | Advantage/Result | -| --- | --- | --- | -| Send | UID2 を API またはピクセルを介して送信 | オーディエンスを作成します。 | -| Send | UID2 をコンバージョン情報として送信 | コンバージョン情報を使用して測定 (アトリビューション) またはリターゲティングに使用します。 | -| Receive | API またはピクセルを介してグラフ/データプロバイダーから UID2 を受信 | グラフデータを構築します。 | - - - -### High-Level Steps - -広告主およびデータプロバイダーが UID2 とインテグレーションする手順は次のとおりです: - -1. directly identifying information (DII) から UID2 を生成するか、広告主やデータプロバイダーなどの他の UID2 参加者から UID2 を受け取ります。 - -1. Step1 で受け取った UID2 を使用します。たとえば、以下のいずれかを行うかもしれません: - - 何らかの操作を行う: たとえば、DII から生成した UID2 と広告主やデータプロバイダーなどの他の参加者から受け取った UID2 を組み合わせます。 - - 既存のオーディエンスに新しい UID2 を追加します。 - -1. Raw UID2 を計測目的で使用します。 - -## Integration Diagram - -以下の図は、オーディエンスの構築とターゲティングのために DII を raw UID2 にマッピングするためにデータコレクターが完了する必要がある手順を示しています。 - -DII とは、正規化されたメールアドレスや電話番号、あるいは正規化され SHA-256 ハッシュ化されたメールアドレスや電話番号のことです。 - -![Advertiser Flow](images/advertiser-flow-mermaid.png) - - - -図の各部の詳細については、以下のセクションを参照してください: -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. [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 - -| Step | Endpoint | Description | -| --- | --- | --- | -| 1-a | [POST /identity/map](../endpoints/post-identity-map.md)リクエスト | DII を含むリクエストを ID マッピングエンドポイントに送信します。 | -| 1-b | [POST /identity/map](../endpoints/post-identity-map.md) レスポンス | レスポンスで返される `advertising_id` (raw UID2) は、関連する DSP でオーディエンスをターゲティングするために使用できます。
このレスポンスは、ユーザーの raw UID2 と、ソルトバケットに対応する `bucket_id` を返します。バケットに割り当てられたソルトは毎年ローテーションされ、生成される raw UID2 に影響を与えます。ソルトバケットのローテーションをチェックする方法の詳細は [3: Monitor for salt bucket rotations](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s) を参照してください。
メンテナンスを簡単にするために、ユーザの raw UID2 と `bucket_id` をマッピングテーブルに格納することを推奨します。インクリメンタルな更新に関するガイダンスについては、[Use an incremental process to continuous-update raw UID2s](#use-an-incremental-process-to-continuously-update-raw-uid2s) を参照してください。| - -### 2: Send stored raw UID2s to DSPs to create audiences or conversions - -Step 1-b で返された `advertising_id` (raw UID2) を、オーディエンスを構築しながら DSP に送信します。各 DSP はオーディエンスを構築するための独自のインテグレーションプロセスを持っています。raw UID2 を送信してオーディエンスを構築するには、DSP が提供するインテグレーションガイダンスに従ってください。 - -### 3: Monitor for salt bucket rotations related to your stored raw UID2s -raw UID2 は、特定の時点のユーザーに対する識別子です。特定のユーザーの raw UID2 は、ソルトのローテーションの結果、少なくとも 1 年に 1 回は変化します。 - -ソルトバケットの更新は 1 年に 1 回程度ですが、個々のバケットの更新は 1 年に分散しています。全ソルトバケットの約 1/365 を毎日ローテーションしています。 - -:::important -あなたのインテグレーションが最新の raw UID2 を持っていることを確認するために、アクティブなユーザーのソルトバケットのローテーションを毎日チェックしてください。 -::: - -| Step | Endpoint | Description | -| --- | --- | --- | -| 3-a | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | 特定のタイムスタンプ以降に変更されたすべてのソルトバケットについて、バケットステータスエンドポイントにリクエストを送信します。 | -| 3-b | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | UID2 service: バケットステータスエンドポイントは `bucket_id` と `last_updated` のタイムスタンプのリストを返します。 | -| 3-c | [POST /identity/map](../endpoints/post-identity-map.md) | 返された`bucket_id`を、キャッシュしておいた raw UID2 のソルトバケットと比較します。
1 つ以上の raw UID2 についてソルトバケットが更新されていることがわかったら、新しい raw UID2 について ID マッピングサービスに DII を再送信します。 | -| 3-d | [POST /identity/map](../endpoints/post-identity-map.md) | `advertising_id`と`bucket_id`に返された新しい値を保存します。 | - -## Use an Incremental Process to Continuously Update Raw UID2s - -UID2 ベースのオーディエンス情報を正確かつ最新の状態に保つために、毎日以下のインテグレーション手順を実行してください: - -1. [UID2 retrieval step](#1-retrieve-a-raw-uid2-for-dii-using-the-identity-map-endpoint) のレスポンスにはマッピング情報が含まれています。以下をキャッシュします: - - 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 を再マッピングします。 - - 次に、Step 2 の[send raw UID2 to a DSP](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) に従って、リフレッシュされた UID2 を使ってオーディエンスまたはコンバージョンを更新します。 - -## Check Opt-Out Status - -ユーザーのオプトアウトステータスを受け入れることは重要です。最新のオプトアウト情報を確認するために、次の 2 つの方法を使用できます: - -- UID2 Operator Service は、広告主やデータプロバイダーに、[POST /identity/map](../endpoints/post-identity-map.md) エンドポイントを介してオプトアウト情報を配布します。 - -- 広告主やデータプロバイダーは、[POST /optout/status](../endpoints/post-optout-status.md) エンドポイントを使用して、生の UID2 のオプトアウトステータスを確認できます。 - -UID2 の Opt-out ワークフローとユーザーが Opt-out する方法の詳細については、[User Opt-Out](../getting-started/gs-opt-out.md) を参照してください。 - -## FAQs - -UID2 フレームワークを使用する広告主およびデータプロバイダー向けのよくある質問は、[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/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/images/advertiser-flow-endpoints-mermaid.png b/i18n/ja/docusaurus-plugin-content-docs/current/guides/images/advertiser-flow-endpoints-mermaid.png new file mode 100644 index 000000000..6b9d3ee9d Binary files /dev/null and b/i18n/ja/docusaurus-plugin-content-docs/current/guides/images/advertiser-flow-endpoints-mermaid.png differ diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/images/advertiser-flow-overview-mermaid.png b/i18n/ja/docusaurus-plugin-content-docs/current/guides/images/advertiser-flow-overview-mermaid.png new file mode 100644 index 000000000..f1b258069 Binary files /dev/null and b/i18n/ja/docusaurus-plugin-content-docs/current/guides/images/advertiser-flow-overview-mermaid.png differ diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/images/resource/advertiser-flow-endpoints-mermaid.md.bak b/i18n/ja/docusaurus-plugin-content-docs/current/guides/images/resource/advertiser-flow-endpoints-mermaid.md.bak new file mode 100644 index 000000000..6223664e3 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/images/resource/advertiser-flow-endpoints-mermaid.md.bak @@ -0,0 +1,71 @@ +>DSP: Send stored raw UID2s to DSPs to create audiences and conversions, or use them for measurement. + Note over ADP,DSP: 5. Monitor for salt bucket rotation. + loop + ADP->>UID: 5-a. Monitor salt bucket rotations using the POST /identity/buckets endpoint. + UID->>ADP: 5-b. Return salt buckets rotated since a specified timestamp. + ADP->>UID: 5-c. Compare the rotated salt buckets to the stored UID2 salt buckets.
If rotated, resend DII to the POST /identity/map endpoint for a new raw UID2. + UID->>ADP: 5-d. Store the raw UID2 and the salt bucket ID 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 + +--> + + + + + + + + + sequenceDiagram + participant DP as Data Provider + participant UID2 as UID2 Operator + participant DSP + loop 1. Retrieve a UID2 for DII using the identity map endpoint. + DP->>UID2: 1-a. Send a request containing DII to the identity mapping endpoints. + UID2->>DP: 1-b. Store the raw UID2 and salt bucket returned from the POST /identity/map endpoint. + end + DP-->>DSP: 2. Send stored UID2s to DSPs to create audiences and conversions. + + loop 3. Monitor for salt bucket rotations related to your stored raw UID2s. + DP->>UID2: 3-a. Monitor salt bucket rotations using the bucket service. + UID2->>DP: 3-b. Return salt buckets rotated since a specified timestamp. + DP->>UID2: 3-c. Compare the rotated salt buckets to the stored UID2 salt buckets.
If rotated, resend DII to the POST /identity/map endpoint for a new raw UID2. + UID2->>DP: 3-d. Store the raw UID2 and the salt bucket returned from the POST /identity/map endpoint. + end + + + + + diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/images/resource/advertiser-flow-overview-mermaid.md.bak b/i18n/ja/docusaurus-plugin-content-docs/current/guides/images/resource/advertiser-flow-overview-mermaid.md.bak new file mode 100644 index 000000000..597c99596 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/images/resource/advertiser-flow-overview-mermaid.md.bak @@ -0,0 +1,114 @@ +1/2/25: Reworking the ADP diagram for six steps as discussed with AnDe. Sent to her for review but checking in these mods. + +>DSP: Send stored raw UID2s to DSPs to create audiences and conversions, or use them for measurement. + Note over ADP,DSP: 5. Monitor for salt bucket rotation. + loop + ADP->>UID: 5-a. Monitor salt bucket rotations using the Python SDK, Snowflake, or HTTP endpoints. + UID->>ADP: 5-b. Return salt buckets rotated since a specified timestamp. + ADP->>UID: 5-c. Compare the rotated salt buckets to the stored UID2 salt buckets.
If rotated, resend DII to the option you're using in Step 1 to get a new raw UID2. + UID->>ADP: 5-d. Store the raw UID2 and the salt bucket that are returned. + 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 + +--> + + + +>DSP: Send stored raw UID2s to DSPs to create audiences and conversions, or use them for measurement. + Note over ADP,DSP: 5. Monitor for salt bucket rotation. + loop + ADP->>UID: 5-a. Monitor salt bucket rotations using the bucket service. + UID->>ADP: 5-b. Return salt buckets rotated since a specified timestamp. + ADP->>UID: 5-c. Compare the rotated salt buckets to the stored UID2 salt buckets.
If rotated, resend DII to identity mapping service for a new raw UID2. + UID->>ADP: 5-d. Store the raw UID2 and the salt bucket returned from the identity mapping service. + 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 + +--> + + + + + + + + + sequenceDiagram + participant DP as Data Provider + participant UID2 as UID2 Operator + participant DSP + loop 1. Retrieve a UID2 for DII using the identity map endpoint. + DP->>UID2: 1-a. Send a request containing DII to the identity mapping endpoints. + UID2->>DP: 1-b. Store the raw UID2 and salt bucket returned from the identity mapping service. + end + DP-->>DSP: 2. Send stored UID2s to DSPs to create audiences and conversions. + + loop 3. Monitor for salt bucket rotations related to your stored raw UID2s. + DP->>UID2: 3-a. Monitor salt bucket rotations using the bucket service. + UID2->>DP: 3-b. Return salt buckets rotated since a specified timestamp. + DP->>UID2: 3-c. Compare the rotated salt buckets to the stored UID2 salt buckets.
If rotated, resend DII to identity mapping service for a new raw UID2. + UID2->>DP: 3-d. Store the raw UID2 and the salt bucket returned from the identity mapping service. + end + + + + + + diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-endpoints.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-endpoints.md new file mode 100644 index 000000000..44eba2142 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-endpoints.md @@ -0,0 +1,118 @@ +--- +title: Advertiser/Data Provider Integration to HTTP Endpoints +sidebar_label: HTTP Endpoints +description: Integration for organizations that collect user data and push it to other participants, coding to HTTP endpoints rather than an SDK or Snowflake. +hide_table_of_contents: false +sidebar_position: 07 +displayed_sidebar: sidebarAdvertisers +--- + +import Link from '@docusaurus/Link'; + +# 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 options 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). +::: + +## 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) + +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) + +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.png) + + + +### 1: Generate Raw UID2s 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 [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 + +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 + +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 + +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 + +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). + +The following table shows the steps for checking for salt bucket rotation. + +| Step | Endpoint | Description | +| --- | --- | --- | +| 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](../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 + +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. + +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 + +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](../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). diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-overview.md new file mode 100644 index 000000000..062654d53 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-overview.md @@ -0,0 +1,160 @@ +--- +title: Advertiser/Data Provider Integration Overview +sidebar_label: Advertiser/Data Provider Integration Overview +description: Overview of integration options for organizations that collect user data and push it to other participants. +hide_table_of_contents: false +sidebar_position: 07 +--- + +import Link from '@docusaurus/Link'; + +# Advertiser/Data Provider Integration Overview + +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 + +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 + +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) + +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) + +6. [Monitor for Opt-Out Status](#6-monitor-for-opt-out-status) + +## Summary of Implementation Options + +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:
  • One of these UID2 SDKs:
    • Python SDK: [Map DII to Raw UID2s](../sdks/sdk-ref-python.md#map-dii-to-raw-uid2s)
    • Java SDK: [Usage for Advertisers/Data Providers](../sdks/sdk-ref-java.md#usage-for-advertisersdata-providers)
  • Snowflake: [Map DII](snowflake_integration.md#map-dii)
  • AWS Entity Resolution: [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md)
  • HTTP endpoints: [POST /identity/map](../endpoints/post-identity-map.md)
| +| [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:
  • Python SDK: see SDK for Python Reference Guide
  • Snowflake: see Snowflake Integration Guide, section titled Monitor for Salt Bucket Rotation and Regenerate Raw UID2s
  • Raw HTTP endpoint: POST /identity/buckets
| +| [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 + +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 + +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](snowflake_integration.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 + +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 + +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 + +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 + +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). + +For instructions for monitoring for salt bucket rotations, refer to one of the following: + +- Python SDK: [Monitor Rotated Salt Buckets](../sdks/sdk-ref-python.md#monitor-rotated-salt-buckets). + +- Snowflake: [Monitor for Salt Bucket Rotation and Regenerate Raw UID2s](snowflake_integration.md#monitor-for-salt-bucket-rotation-and-regenerate-raw-uid2s). + +- HTTP endpoints: [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s](integration-advertiser-dataprovider-endpoints.md#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s). + +:::note +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 + +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. + +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 + +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](../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 + +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/integration-prebid-client-side.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-prebid-client-side.md index 485994068..3ec102e7e 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-prebid-client-side.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-prebid-client-side.md @@ -40,7 +40,6 @@ UID2 Prebid.js Client-Side インテグレーション例は、以下のリン 2. [Add Prebid.js to your site](#add-prebidjs-to-your-site). 3. [Configure the UID2 module](#configure-the-uid2-module). - ### Complete UID2 Account Setup [Account Setup](../getting-started/gs-account-setup.md) ページに記載されている手順に従って、UID2 アカウントのセットアップを完了します。Client-Side 実装のアカウント設定プロセスの一環として、Prebid.js で使用するサイトのドメイン名のリストを提供する必要があります。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/snowflake_integration.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/snowflake_integration.md index bcb0904cb..7fee58483 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/snowflake_integration.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/snowflake_integration.md @@ -82,7 +82,7 @@ UID2 Share へのアクセスを要求するには、次の手順を実行しま 非推奨の関数を使用していて、新しい関数への移行の手助けが必要な場合は、[Migration Guide](#migration-guide) を参照してください。 ::: -再生成が必要な UID2 を特定するには、UID Share から `UID2_SALT_BUCKETS` ビューを使用します。詳しくは、[Regenerate UID2s](#regenerate-uid2s) を参照してください。 +再生成が必要な UID2 を特定するには、UID Share から `UID2_SALT_BUCKETS` ビューを使用します。詳しくは、[Monitor for Salt Bucket Rotation and Regenerate Raw UID2s](#monitor-for-salt-bucket-rotation-and-regenerate-raw-uid2s) を参照してください。 UID2 Sharing 参加者には、以下の機能も利用できます: - `FN_T_UID2_ENCRYPT` (See [Encrypt Tokens](#encrypt-tokens)) @@ -404,7 +404,7 @@ select a.ID, a.PHONE_HASH, m.UID2, m.BUCKET_ID, m.UNMAPPED from AUDIENCE a LEFT +----+----------------------------------------------+----------------------------------------------+------------+--------------------+ ``` -### Regenerate UID2s +### Monitor for Salt Bucket Rotation and Regenerate Raw UID2s `UID2_SALT_BUCKETS` ビュークエリは、セカンドレベルのソルトバケットが最後に更新された日時を返します。セカンドレベルのソルトは UID2 を生成する際に使用されます。バケット内のソルトが更新されると、それまで生成されていた UID2 が古くなり、同じユーザーに対して他者が生成した UID2 とは一致しなくなります。 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 c930e508a..18e4be25f 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-advertiser-dataprovider-overview.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..1ad3094ed 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-advertiser-dataprovider-overview.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..97f52bad8 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-advertiser-dataprovider-overview.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 eaa5a89c6..df999c0bf 100644 --- a/sidebars.js +++ b/sidebars.js @@ -86,31 +86,31 @@ const fullSidebar = [ link: { type: 'generated-index', }, - collapsed: false, + collapsed: true, items: [ - { - type: 'category', - label: 'Web', - link: { - type: 'doc', - id: 'guides/integration-options-publisher-web', - }, - collapsed: true, - items: [ - { - type: 'category', - label: 'Prebid', - link: { - type: 'doc', - id: 'guides/integration-prebid', - }, - collapsed: true, - items: [ - 'guides/integration-prebid-client-side', - 'guides/integration-prebid-client-server', - ], + { + type: 'category', + label: 'Web', + link: { + type: 'doc', + id: 'guides/integration-options-publisher-web', }, + collapsed: true, + items: [ + { + type: 'category', + label: 'Prebid', + link: { + type: 'doc', + id: 'guides/integration-prebid', + }, + collapsed: true, + items: [ + 'guides/integration-prebid-client-side', + 'guides/integration-prebid-client-server', + ], + }, { type: 'category', @@ -177,26 +177,40 @@ const fullSidebar = [ ], }, - 'guides/integration-liveramp-tips', ], - }, + }, - { - type: 'category', - label: 'Advertiser/Data Provider Integrations', - link: { - type: 'generated-index', - }, - collapsed: true, - items: [ - 'guides/advertiser-dataprovider-guide', - 'guides/integration-javascript-client-side', - 'guides/snowflake_integration', - 'guides/integration-aws-entity-resolution', - ], - }, + +{ + type: 'category', + label: 'Advertiser/Data Provider Integrations', + link: { + type: 'generated-index', + }, + collapsed: true, + + items: [ + { + type: 'category', + label: 'Integration Overview', + link: { + type: 'doc', + id: 'guides/integration-advertiser-dataprovider-overview', + }, + collapsed: true, + items: [ + 'guides/snowflake_integration', + 'guides/integration-aws-entity-resolution', + 'guides/integration-advertiser-dataprovider-endpoints', + ], + }, + + 'guides/integration-javascript-client-side', + +], +}, { type: 'category', @@ -329,9 +343,11 @@ const sidebars = { 'overviews/overview-dsps', 'overviews/overview-data-providers', 'Advertiser/Data Provider Integrations', - 'guides/advertiser-dataprovider-guide', + 'guides/integration-advertiser-dataprovider-overview', 'guides/snowflake_integration', 'guides/integration-aws-entity-resolution', + 'guides/advertiser-dataprovider-endpoints', + 'DSP Integrations', 'guides/dsp-guide', 'endpoints/post-identity-buckets', 'endpoints/post-identity-map', @@ -369,6 +385,7 @@ const sidebars = { 'guides/mobile-plugin-gma-ios', 'guides/mobile-plugin-ima-android', 'guides/mobile-plugin-ima-ios', + 'DSP Integrations', 'guides/dsp-guide', 'endpoints/post-token-generate', 'endpoints/post-token-validate', @@ -408,9 +425,11 @@ const sidebars = { 'guides/mobile-plugin-gma-ios', 'guides/mobile-plugin-ima-android', 'guides/mobile-plugin-ima-ios', - 'guides/advertiser-dataprovider-guide', + 'Advertiser/Data Provider Integrations', + 'guides/integration-advertiser-dataprovider-overview', 'guides/snowflake_integration', 'guides/integration-aws-entity-resolution', + 'guides/advertiser-dataprovider-endpoints', 'sharing/sharing-bid-stream' ), @@ -445,6 +464,7 @@ const sidebars = { 'guides/mobile-plugin-gma-ios', 'guides/mobile-plugin-ima-android', 'guides/mobile-plugin-ima-ios', + 'DSP Integrations', 'guides/dsp-guide', 'endpoints/post-token-generate', 'endpoints/post-token-validate',