Refactoring advertiser/data provider doc

docs/endpoints/post-identity-buckets.md

@@ -11,7 +11,7 @@ import Link from '@docusaurus/Link';
 
 Monitors rotated <Link href="../ref-info/glossary-uid#gl-salt-bucket">salt buckets</Link>.
 
-Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md).
+Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md).
 
 ## Request Format
 

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 <Link href="../ref-info/glossary-uid#gl-salt-bucket-id">salt bucket IDs</Link>. You can also use this endpoint to check for updates to opt-out information.
 
-Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md).
+Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md).
 
 ## Batch Size and Request Parallelization Requirements
 
@@ -20,7 +20,7 @@ Here's what you need to know:
 - The maximum request size is 1MB.
 - To map a large number of email addresses, phone numbers, or their respective hashes, send them in *sequential* batches with a maximum batch size of 5,000 items per batch.
 - Unless you are using a <Link href="../ref-info/glossary-uid#gl-private-operator">Private Operator</Link>, do not send batches in parallel. In other words, use a single HTTP connection and send batches of hashed or unhashed <Link href="../ref-info/glossary-uid#gl-dii">directly identifying information (DII)</Link> values consecutively, without creating multiple parallel connections.
-- Be sure to store mappings of email addresses, phone numbers, or their respective hashes.<br/>Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of 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.<br/>Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of raw UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers).
 
 ## Request Format
 

docs/endpoints/post-optout-status.md

@@ -15,7 +15,7 @@ Used by: This endpoint is used by advertisers, data providers, DSPs, and sharers
 
 For details, refer to the following documentation, depending on your role:
 
-- [Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md)
+- [Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md)
 - [DSP Integration Guide](../guides/dsp-guide.md)
 - [UID2 Sharing: Overview](../sharing/sharing-overview)
 

docs/getting-started/gs-credentials.md

@@ -15,7 +15,7 @@ Each UID2 <a href="/docs/intro#participants">participant</a> gets a set of uniqu
 | :--- | :--- | :--- |
 | Participants using a client-side implementation | Both of the following: <ul><li><Link href="../ref-info/glossary-uid#gl-subscription-id">Subscription ID</Link></li><li><Link href="../ref-info/glossary-uid#gl-public-key">Public key</Link></li></ul>These two, together, are sometimes called <Link href="../ref-info/glossary-uid#gl-client-keypair">client keypair</Link>. | Integrations using one of these: <ul><li>[UID2 Client-Side Integration Guide for Prebid.js](../guides/integration-prebid-client-side.md)</li><li>[Client-Side Integration Guide for JavaScript](../guides/integration-javascript-client-side.md)</li><li>[UID2 Client-Side Integration Guide for Mobile](../guides/integration-mobile-client-side.md)</li></ul> |
 | Participants using a client-server implementation | Both of the following:<ul><li><Link href="../ref-info/glossary-uid#gl-api-key">API key</Link>, also called a client key</li><li><Link href="../ref-info/glossary-uid#gl-client-secret">Client secret</Link>, a value known only to the participant and the UID2 service</li></ul> | Integrations using one of these: <ul><li>[Client-Server Integration Guide for JavaScript](../guides/integration-javascript-client-server.md)</li><li>[UID2 Client-Server Integration Guide for Prebid.js](../guides/integration-prebid-client-server.md)</li><li>[UID2 Client-Server Integration Guide for Mobile](../guides/integration-mobile-client-server.md)</li></ul> |
-| Participants using a server-side implementation | Both of the following:<ul><li><Link href="../ref-info/glossary-uid#gl-api-key">API key</Link>, also called a client key</li><li><Link href="../ref-info/glossary-uid#gl-client-secret">Client secret</Link>, a value known only to the participant and the UID2 service</li></ul> | Integrations using one of these: <ul><li>[Publisher Integration Guide, Server-Side](../guides/integration-publisher-server-side.md)</li><li>[Advertiser/Data Provider Integration Guide](../guides/advertiser-dataprovider-guide.md)</li></ul> |
+| Participants using a server-side implementation | Both of the following:<ul><li><Link href="../ref-info/glossary-uid#gl-api-key">API key</Link>, also called a client key</li><li><Link href="../ref-info/glossary-uid#gl-client-secret">Client secret</Link>, a value known only to the participant and the UID2 service</li></ul> | Integrations using one of these: <ul><li>[Publisher Integration Guide, Server-Side](../guides/integration-publisher-server-side.md)</li><li>[Advertiser/Data Provider Integration Guide](../guides/integration-options-advertiser-dataprovider.md)</li></ul> |
 
 If you're using the integration environment as well as the production environment, you'll get a separate set of credentials for each environment.
 

docs/getting-started/gs-faqs.md

@@ -163,7 +163,7 @@ We do not make any promises about when the rotation takes place. To stay as up-t
 
 #### Do refreshed emails get assigned to the same bucket with which they were previously associated?
 
-Not necessarily. After you remap emails associated with a particular bucket ID, the emails might be assigned to a different bucket ID. To check the bucket ID, [call the mapping function](../guides/advertiser-dataprovider-guide.md#1-retrieve-a-raw-uid2-for-dii-using-the-identity-map-endpoint) and save the returned UID2 and bucket ID again.
+Not necessarily. After you remap emails associated with a particular bucket ID, the emails might be assigned to a different bucket ID. To check the bucket ID, [call the mapping function](../guides/integration-options-advertiser-dataprovider.md#1-retrieve-a-raw-uid2-from-dii) and save the returned UID2 and bucket ID again.
 
 :::info
 When mapping and remapping emails, do not make any assumptions about the number of buckets, their rotation dates, or the specific bucket that an email gets assigned to.
@@ -201,7 +201,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 <Link href="../ref-info/glossary-uid#gl-salt">salt</Link> value that's used in generating the raw UID2. The salt values are rotated roughly once per year (for details, see [How often should UID2s be refreshed for incremental updates?](#how-often-should-uid2s-be-refreshed-for-incremental-updates)). If the salt value changes between one request and another, those two requests result in two different raw UID2, even when the DII is the same.
 
-For more information, see [Monitor for salt bucket rotations related to your stored raw UID2s](../guides/advertiser-dataprovider-guide.md#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s) in the *Advertiser/Data Provider Integration Guide*.
+For more information, see [Monitor for salt bucket rotations related to your stored raw UID2s](../guides/integration-options-advertiser-dataprovider.md#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s) in the *Advertiser/Data Provider Integration Guide*.
 
 #### If two operators process the same DII, are the results the same?
 

docs/guides/advertiser-dataprovider-guide.bak

@@ -0,0 +1,169 @@
+---
+title: Advertiser/Data Provider Integration Overview
+sidebar_label: Advertiser/Data Provider Integration Overview
+description: Overview of UID2 integration options for organizations that collect user data and push it to other participants.
+hide_table_of_contents: false
+sidebar_position: 07
+displayed_sidebar: sidebarAdvertisers
+---
+
+import Link from '@docusaurus/Link';
+
+# Advertiser/Data Provider Integration Overview
+
+This guide covers integration steps for organizations that collect user data and push it to other UID2 participants. Data collectors include advertisers, data on-boarders, measurement providers, identity graph providers, third-party data providers, and any other organizations that send data to other participants.
+
+If you are using an Open Operator service hosted in the Snowflake Data Marketplace, see also [Snowflake Integration Guide](snowflake_integration.md).
+
+## Advertiser/Data Provider Routes to Use UID2
+
+Within the ad tech industry, advertisers use identity to build audiences, track conversions, and generate their graphs. As an advertiser, or as a data provider acting on behalf of an advertiser, the following table shows some examples of how you can accomplish some of these goals with UID2.
+
+:::note
+There are other ways that you can use UID2, outside these use cases. These are just some examples.
+:::
+
+| Send/Receive? | Action | Advantage/Result |
+| --- | --- | --- |
+| Send | Send UID2s via API or pixels | Create audiences. |
+| Send | Send UID2s as conversion information | Use conversion information for measurement (attribution) or for retargeting via API or pixels. |
+| Receive | Receive UID2s from graph/data providers via API or pixels | Build graph data. |
+
+<!-- - **Create/send in audiences**: You can send UID2s to create audiences via API or pixels
+- **Send in conversions**: You can send UID2s as conversion information that can be used for measurement (attribution) or retargeting via API or pixels
+- **Receive graph data**: You can receive UID2s from graph/data providers via API or pixels. -->
+
+## Key Integration Steps
+
+At a high level, to integrate with UID2 as an advertiser or data provider, you'll implement these three key activities:
+
+1. [Retrieve a raw UID2 for DII](#1-retrieve-a-raw-uid2-from-dii)
+
+   Generate a raw UID2 from <Link href="../ref-info/glossary-uid#gl-dii">directly identifying information (DII)</Link>, or receive UID2s from another UID2 participant such as a data provider acting on your behalf.
+
+2. [Send stored raw UID2s to DSPs to create audiences or conversions](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions)
+
+   Use the UID2s you received in Step 1. For example, you might do one or more of the following:
+   - Do some manipulation: for example, combine UID2s you generated from DII and UID2s received from another participant such as an advertiser or data provider.
+   - Add new UID2s into an existing audience.
+
+   As part of this step, you'll also need to [monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s).
+
+3.  Use the raw UID2s for some purpose such as measurement.
+
+## Integration Options Summary
+
+The following integration options are available for advertisers and data providers:
+
+| Integration Option | Link to Documentation |
+| :--- | :--- |
+| Client-Side JavaScript SDK |[Client-Side Integration Guide for JavaScript](integration-javascript-client-side.md) <!-- UID2_only: Not applicable for EUID --> |
+| Snowflake | [Snowflake Integration Guide](snowflake_integration.md) |
+| AWS Entity Resolution | [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md) |
+| AWS Entity Resolution | [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md) |
+| Direct integration (API endpoints ] [xxx TBD](advertiser-dataprovider-identity-map.md) |
+
+For a summary of the UID2 integration solutions available for advertisers and data providers.
+
+
+
+
+
+
+### High-Level Key Integration Steps
+
+At a high level, the steps for advertisers and data providers integrating with UID2 are as follows:
+
+1. Generate a raw UID2 from <Link href="../ref-info/glossary-uid#gl-dii">directly identifying information (DII)</Link>, or receive UID2s from another UID2 participant such as a data provider acting on your behalf.
+
+1. Use the UID2s you received in Step 1. For example, you might do one or more of the following:
+   - Do some manipulation: for example, combine UID2s you generated from DII and UID2s received from another participant such as an advertiser or data provider.
+   - Add new UID2s into an existing audience.
+
+1. Use the raw UID2s for some purpose such as measurement.
+
+There are several ways you can accomplish these key steps.
+
+
+
+
+## Integration Diagram
+
+The following diagram outlines the steps that data collectors must complete to map DII to raw UID2s for audience building and targeting.
+
+DII refers to a user's normalized email address or phone number, or the normalized and SHA-256-hashed email address or phone number.
+
+![Advertiser Flow](images/advertiser-flow-mermaid.png)
+
+<!-- diagram source: resource/advertiser-flow-mermaid.md.bak -->
+
+Refer to the following sections for details about the different parts of the diagram:
+1. [Retrieve a raw UID2 for DII](#1-retrieve-a-raw-uid2-from-dii)
+2. [Send stored raw UID2s to DSPs to create audiences or conversions](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions)
+3. [Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s)
+
+### 1: Generate a raw UID2 from DII
+
+The first step is to retrieve a raw UID2. You can do this by using any of the advertiser/data provider implementation options, summarized in the following table.
+
+| Integration Method | Link to Instructions |
+| :--- | :--- |
+| [Client-Side Integration Guide for JavaScript](integration-javascript-client-side.md) | xxx <!-- UID2_only: Not applicable for EUID --> |
+| [Snowflake Integration Guide](snowflake_integration.md) | xxx |
+| [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md) | xxx |
+| [Direct integration (API endpoints)](advertiser-dataprovider-identity-map.md) | xxx TBD |
+
+### 2: Send stored raw UID2s to DSPs to create audiences or conversions
+
+Send the `advertising_id` (raw UID2) returned in Step 1-b to a DSP while building your audiences. Each DSP has a unique integration process for building audiences; follow the integration guidance provided by the DSP for sending raw UID2s to build an audience.
+
+### 3: Monitor for salt bucket rotations related to your stored raw UID2s
+A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes at least once per year, as a result of the salt rotation. 
+
+Even though each salt bucket is updated approximately once per year, individual bucket updates are spread over the year. Approximately 1/365th of all salt buckets are rotated daily.
+
+:::important
+To ensure that your integration has the current raw UID2s, check salt bucket rotation for active users every day.
+:::
+
+| Step | Endpoint | Description |
+| --- | --- | --- |
+| 3-a | [POST&nbsp;/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&nbsp;/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&nbsp;/identity/map](../endpoints/post-identity-map.md) | Compare the returned `bucket_id` to the salt buckets of raw UID2s that you've cached.<br/>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&nbsp;/identity/map](../endpoints/post-identity-map.md) | Store the new values returned for `advertising_id` and `bucket_id`. |
+
+## Use an Incremental Process to Continuously Update Raw UID2s
+
+To keep your UID2-based audience information accurate and up to date, follow these integration steps every day:
+
+1. The response from the [UID2 retrieval step](#1-retrieve-a-raw-uid2-from-dii) contains mapping information. Cache the following:
+   - The mapping between DII (`identifier`), raw UID2 (`advertising_id`), and salt bucket (`bucket_id`).
+   - The most recent `last_updated` timestamp.
+2. Using the results from Step 3, [Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s), remap any raw UID2 for which the salt buckets have been rotated by retrieving new raw UID2 for those IDs, following Step 1, [Retrieve a raw UID2 for DII using the identity map endpoint](#1-retrieve-a-raw-uid2-from-dii).
+
+   Then, use the refreshed UID2s to update audiences or conversions, following Step 2, [send raw UID2 to a DSP](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions).
+
+## Check Opt-Out Status
+
+It's important to honor user opt-out status. Here are two ways you can check that you have the latest opt-out information:
+
+- The UID2 Operator Service distributes opt-out information to advertisers and data providers via the [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) endpoint.
+
+- Advertisers and data providers can check the opt-out status of raw UID2s using the [POST&nbsp;/optout/status](../endpoints/post-optout-status.md) endpoint.
+
+
+## Implementation Resources
+
+The following documentation resources are available for advertisers and data providers integrating with UID2.
+
+| Integration Guide | Content Description |
+| :--- | :--- |
+| [Advertiser/Data Provider](integration-options-advertiser-dataprovider.md) | This integration guide for advertisers and data providers covers integration workflows for mapping identity for audience-building and targeting. |
+| [Client-Side Integration Guide for JavaScript](integration-javascript-client-side.md) | A guide for advertisers and data providers who want to use this SDK for adding a UID2 token to their tracking pixels.<!-- UID2_only: Not applicable for EUID --> |
+| [Snowflake Integration Guide](snowflake_integration.md) | Instructions for generating UID2s from emails within Snowflake. |
+| [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md) | Instructions for integrating with the UID2 framework using AWS Entity Resolution. |
+
+## FAQs
+
+For a list of frequently asked questions for advertisers and data providers using the UID2 framework, see [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers).

docs/guides/advertiser-dataprovider-guide.mdx

@@ -0,0 +1,3 @@
+import { Redirect } from '@docusaurus/router';
+
+<Redirect to="/docs/guides/integration-options-advertiser-dataprovider" />;