ADP endpoints guide updates except diagram

Author: genwhittTTD

docs/guides/integration-advertiser-dataprovider-endpoints.md

@@ -17,59 +17,49 @@ This guide covers integration steps for advertisers and data providers to integr
 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).
 :::
 
-## Integration Diagram
-
-The following diagram outlines the steps that data collectors must complete to map DII to raw UID2s for audience building and targeting.
+## High-Level Steps
 
-DII refers to a user's normalized email address or phone number, or the normalized and SHA-256-hashed email address or phone number.
+At a high level, the steps for advertisers and data providers integrating with UID2 are as follows:
 
-![Advertiser Flow](images/advertiser-flow-endpoints-mermaid.png)
-
-<!-- diagram source: resource/advertiser-flow-endpoints-mermaid.md.bak -->
+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)
 
-## Detailed Steps
+3. [Manipulate or Combine Raw UID2s](#3-manipulate-or-combine-raw-uid2s)
 
-The steps for advertisers and data providers integrating with UID2 by calling the HTTP endpoints are given in the following sections:
+4. [Send Stored Raw UID2s to DSPs to Create Audiences or Conversions](#4-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions)
 
-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.
+5. [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s)
 
-    **Instructions**: see [Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii).
+6. [Monitor for Opt-Out Status](#6-monitor-for-opt-out-status)
 
-2. 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.
-
-    **Instructions**: This step is is out of band and entirely up to you.
-
-3. Use the raw UID2s for some purpose such as:
-   - Send stored raw UID2s to DSPs to create audiences and conversions.
-   - Use the raw UID2s for measurement.
-
-    **Instructions**: see [Send stored raw UID2s to DSPs to create audiences or conversions](#4-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions).
-
-4.	Store the raw UID2 and the salt bucket ID returned from the `POST /identity/map` endpoint.
-
-    **Instructions**: This step is is out of band and entirely up to you.
+## Integration Diagram
 
-5.	Monitor for salt bucket rotations related to your stored raw UID2s.
+The following diagram outlines the steps that data collectors must complete to map DII to raw UID2s for audience building and targeting.
 
-    **Instructions**: See [Monitor for salt bucket rotations related to your stored raw UID2s](#5-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s).
+DII refers to a user's normalized email address or phone number, or the normalized and SHA-256-hashed email address or phone number.
 
-6.	Periodically, monitor for opt-out status, to be sure that you don't continue using UID2s for users that have recently opted out.
+![Advertiser Flow](images/advertiser-flow-endpoints-mermaid.png)
 
-    **Instructions**: See [Monitor for Opt-Out Status](#monitor-for-opt-out-status).
+<!-- diagram source: resource/advertiser-flow-endpoints-mermaid.md.bak -->
 
 ### 1: Generate Raw UID2s from DII
 
 | Step | Endpoint | Description |
 | --- | --- | --- |
 | 1-a | [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) request | Send a request containing DII to the identity mapping endpoint. |
-| 1-b | [POST&nbsp;/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.<br/>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-related-to-your-stored-raw-uid2s). |
+| 1-b | [POST&nbsp;/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.<br/>The response returns a user's raw UID2 and the corresponding `bucket_id` for the salt bucket. The salt assigned to the bucket rotates annually, which impacts the generated raw UID2. For details on how to check for salt bucket rotation, see [5: Monitor for salt bucket rotations related to your stored raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s). |
+
+
+### 2: Store Raw UID2s and Salt Bucket IDs
 
-### 2: Send stored raw UID2s to DSPs to create audiences or conversions
+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 raw UID2s and the salt bucket IDs returned in Step 1.
 
-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.
+Cache the mapping between DII (`identifier`), raw UID2 (`advertising_id`), and salt bucket (`bucket_id`).
+
+:::note
+We recommend that you also store the most recent `last_updated` timestamp, returned in a later step, with the mapping information. For details, see [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
 
@@ -80,17 +70,20 @@ Use the UID2s you received in Step 1. For example, you might do one or more of t
 
 ### 4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions
 
-xxx uptohere TODO
+Use the raw UID2s for some purpose such as:
 
-### 5: Monitor for salt bucket rotations related to your stored raw UID2s
+   - Sending stored raw UID2s to DSPs to create audiences and conversions.
+   - Using the raw UID2s for measurement.
 
-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. 
+For example, you could send the `advertising_id` (<Link href="../ref-info/glossary-uid#gl-raw-uid2">raw UID2</Link>) 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.
 
-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.
+You could also send conversion information via API or pixels for measurement (attribution) or for retargeting.
 
-:::important
-To help ensure that your integration has the current raw UID2s, check salt bucket rotation for active users every day.
-:::
+### 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 <Link href="../ref-info/glossary-uid#gl-salt-bucket">salt bucket</Link> 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.
 
 | Step | Endpoint | Description |
 | --- | --- | --- |
@@ -99,12 +92,14 @@ To help ensure that your integration has the current raw UID2s, check salt bucke
 | 5-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 `POST /identity/map` endpoint for a new raw UID2. |
 | 5-d | [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) | Store the new values returned for `advertising_id` and `bucket_id`. |
 
-## Monitor for Opt-Out Status
+### 6: Monitor for Opt-Out Status
+
+It's important to honor user opt-out status. Periodically, monitor for opt-out status, to be sure that you don't continue using UID2s for users that have recently opted out.
 
-It's important to honor user opt-out status. Here are two ways you can check that you have the latest opt-out information:
+There are two ways that you can check with the UID2 <Link href="../ref-info/glossary-uid#gl-operator-service">Operator Service</Link> to make sure you have the latest opt-out information:
 
-- The UID2 <Link href="../ref-info/glossary-uid#gl-operator-service">Operator Service</Link> distributes opt-out information to advertisers and data providers via the [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) endpoint.
+- Call the [POST&nbsp;/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.
 
-- 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.
+- Check the opt-out status of raw UID2s using the [POST&nbsp;/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).

docs/guides/integration-advertiser-dataprovider-overview.md

@@ -23,12 +23,8 @@ There are other ways that you can use UID2, outside these use cases. These are j
 | Send/Receive? | Action | Advantage/Result |
 | --- | --- | --- |
 | Send in audiences | Send UID2s via API or pixels | Create audiences. |
-| Send in conversions | Send UID2s as conversion information | Use conversion information for measurement (attribution) or for retargeting via API or pixels. |
-| Receive graph data | Receive UID2s from graph/data providers via API or pixels | Build graph data. |
-
-<!-- - **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. -->
+| Send&nbsp;in&nbsp;conversions | Send UID2s as conversion information | Use conversion information for measurement (attribution) or for retargeting via API or pixels. |
+| Receive&nbsp;graph&nbsp;data | Receive UID2s from graph/data providers via API or pixels | Build graph data. |
 
 ## High-Level Steps
 
@@ -44,7 +40,7 @@ At a high level, the steps for advertisers and data providers integrating with U
 
 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)
+6. [Monitor for Opt-Out Status](#6-monitor-for-opt-out-status)
 
 ## Summary of Implementation Options
 
@@ -57,7 +53,7 @@ The following table shows the implementation options that are available for adve
 | [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:<ul><li><strong>Python SDK</strong>: see <Link href="../sdks/sdk-ref-python">SDK for Python Reference Guide</Link></li><li><strong>Snowflake</strong>: see <Link href="snowflake_integration">Snowflake Integration Guide</Link>, section titled <Link href="snowflake_integration#monitor-for-salt-bucket-rotation-and-regenerate-raw-uid2s">Monitor for Salt Bucket Rotation and Regenerate Raw UID2s</Link></li><li><strong>Raw HTTP endpoint</strong>: <Link href="../endpoints/post-identity-buckets">POST /identity/buckets</Link></li></ul> |
-| [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. |
+| [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
 
@@ -134,7 +130,7 @@ For instructions for monitoring for salt bucket rotations, refer to one of the f
 
 - 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-related-to-your-stored-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.