Merge pull request #585 from IABTechLab/gwh-APIDOCS-2242-advertisers-…

…add-cstg-js-guide

updates to advertiser/data provider guide, draft

docs/guides/advertiser-dataprovider-guide.md

@@ -15,9 +15,39 @@ This guide covers integration steps for organizations that collect user data and
 
 If you are using an Open Operator service hosted in the Snowflake Data Marketplace, see also [Snowflake Integration Guide](snowflake_integration.md).
 
-## Integration Steps
+## Advertiser/Data Provider Routes to Use UID2
 
-The following diagram outlines the steps that data collectors must complete to map <Link href="../ref-info/glossary-uid#gl-dii">directly identifying information (DII)</Link> to UID2 identifiers for audience building and targeting.
+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. -->
+
+### 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 <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.
+
+## 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.
 
@@ -27,7 +57,7 @@ DII refers to a user's normalized email address or phone number, or the normaliz
 
 Refer to the following sections for details about the different parts of the diagram:
 1. [Retrieve a raw UID2 for DII using the identity map endpoints](#1-retrieve-a-raw-uid2-for-dii-using-the-identity-map-endpoint)
-2. [Send stored raw UID2s to DSPs to create audiences](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences)
+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
@@ -37,7 +67,7 @@ Refer to the following sections for details about the different parts of the dia
 | 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 [3: Monitor for salt bucket rotations](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s).<br/>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
+### 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.
 
@@ -66,7 +96,7 @@ To keep your UID2-based audience information accurate and up to date, follow the
    - 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, following Step 2, [send raw UID2 to a DSP](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences).
+   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
 

docs/guides/images/resource/advertiser-flow-mermaid.md.bak

@@ -1,8 +1,9 @@
 
 
+<!-- 8/30/24: Update "2. Send stored UID2s to DSPs to create audiences." > "2. Send stored UID2s to DSPs to create audiences and conversions." (2242) -->
 <!-- 8/14/24: update to change UID2 Service to UID2 Operator per 2503: -->
 
-<!-- 8/14/24: Code: -->
+<!-- 8/30/24: Code: -->
 
   sequenceDiagram
     participant DP as Data Provider
@@ -12,7 +13,7 @@
     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.
+    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.
@@ -28,7 +29,13 @@
 }
  -->
 
-<!--  8/14/24: URL:
+<!--  8/30/24: URL with "Pan & Zoom" on:
+
+https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNqlVMGO2jAQ_ZWRz9mIhISFqOLS9MBhVbSol4qLiQfWKrFT22FLEf_esZOwoIVTuQRnZt5782biE6u0QFYwAIu_W1QVlpLvDK_XCujXcONkJRuuHJRL4BZK7jgsjT5IgeZz0o9Fmfq08PzeoOFO30krV8vu5V7rBpIYXtEZiQcE3pVutYFysYDWSrUD94ZAfMpJd4SaN4BKNFoqF3co5fJpPvd1BSRPPIYVxQnJ-Jasg0orx6XySB7T6U-AjY8NoLZH9YCEWy496oZQqRUMpYa_950Sj-V7B5u2-oWOGF1rFArYGl3fZ7FoDrLCnoM4Ly14rhWRpX0D1vOJQGS9aAqGZ2WQO3KqFdIPzAYV1OMBjZVaeflX5o5jeNFKElYw9Uatdtz5CtK9J0jh0Y-6NQP10OfgyK3VY2_1gH0f92N8fei2-1uTx97k1-DgNZzt8EgOgVV-Q2yDldxKr1fWNGBeNw8EVjF81TVtXj-3AegavV-HK7dv4vGXjZkvtkNtRF5ZP51-kx7NN5jNQeH7xcUHTYuHmxVk_fd2sYjVaGouBX3nJx9YM6qtcc0K-ks6ycI1W6szZfLW6dVRVaxwpsWIGd3u3lix5XtLp7YR5EF_Qwwp3ctvwq_BJRPD8aW7XMIdEzH68n9qfamjIytO7A8rxvkkTpPseTYZJXmSpHnEjqzI0zifzLJxRqFsNkqm54j9DfWjeJqlWf48nY3yZJTns-T8D5qfkDg
+
+-->
+
+<!--  8/14/24: URL with "Pan & Zoom" on:
 
 https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNqllMGS2jAMhl9F43M2Q0LCQqbDpemBw06ZZXrpcDGxYD0ldmo7bCnDu1c2CSVdODWXxJb1Sfql-MQqLZAVDMDizxZVhaXkO8PrtQJ6Gm6crGTDlYNyCdxCyR2HpdEHKdB8PPRtUab-WHh_bdBwp-8cK1fLy-Ze6waSGF7RGYkHBH5x3WoD5WIBrZVqB-4NgeIpJ90Rat4AKtFoqVx8oZTLp_nc-xWQPPEYVmQnkvElWQeVVo5L5Ume6fQHYONtPdR2VA8kbrn01A1RqRQMroa_d5VSHMv3DjZt9QMdRXStUShga3R9P4pFc5AVdjEo5rUEH2tFwdKuAOvjiRDI-qTJGN6VQe5IqVZI3zCf7o2Y4xhetJLkG0QcZKcdd1IrS3nuCSE87ahb04fq6-oVGEo79tL27Pvcv-3qTMNqh6KOvaivQbFbnL3wKB2CVX4ibIOV3Eqfr6ypobxuHiRYxfBZ1zRpXZ960C29a_-NugN7_Glj5ott7xuRVtZ3o5ucR_0MYnNQ-H5V8UHR4uEkhbT-e5pYxGo0NZeC_uuTN6wZ-da4ZgV9Up4k4Zqt1ZlO8tbp1VFVrHCmxYgZ3e7eWLHle0urthGkQXcj_LP7Rfg5uG5iWL5cbpNwqUSMfvXvWtc9m5asOLFfrBjnkzhNsufZZJTkSZLmETuyIk_jfDLLxhmZstkomZ4j9jv4j-Jplmb583Q2ypNRns-S8x9nnYpX