Merge pull request #288 from IABTechLab/gwh-APIDOCS-1666-edit-dsp-int…

…eg-guide

Gwh apidocs 1666 edit dsp integ guide

docs/guides/dsp-guide.md

@@ -10,6 +10,12 @@ sidebar_position: 05
 
 This guide is for DSPs who transact on UID2s in the bid stream.
 
+DSPs receive UID2 tokens in bid requests, and decrypt the UID2 tokens to arrive at raw UID2s that they can use for bidding, using one of the server-side SDKs that support this function.
+
+For a summary of available server-side SDKs, see [UID2 SDK for Java (Server-Side) Reference Guide](../sdks/summary-sdks.md#sdk-functionality).
+
+>NOTE: If your back end is written in a language not covered by one of the available server-side SDKs, ask your UID2 contact in case there is additional information available to help you. If you're not sure who to ask, see [Contact Info](../getting-started/gs-account-setup.md#contact-info).
+
 <!-- It includes the following sections:
 
 * [Integration Steps](#integration-steps)
@@ -21,19 +27,19 @@ This guide is for DSPs who transact on UID2s in the bid stream.
 
 The following describes the integration workflow for DSP to support UID2 as part of RTB, which consists of two major steps:
 1. [Honor user opt-outs](#honor-user-opt-outs)
-2. [Decrypt UID2 tokens to use in RTB](#decrypt-uid2-tokens-for-rtb-use)
+2. [Decrypt UID2 tokens for RTB use](#decrypt-uid2-tokens-for-rtb-use)
 
 ![DSP Flow](https://mermaid.ink/svg/eyJjb2RlIjoiICBzZXF1ZW5jZURpYWdyYW1cbiAgICBwYXJ0aWNpcGFudCBVIGFzIFVzZXJcbiAgICBwYXJ0aWNpcGFudCBTU1BcbiAgICBwYXJ0aWNpcGFudCBEU1BcbiAgICBwYXJ0aWNpcGFudCBVSUQyIGFzIFVJRDIgU2VydmljZVxuICAgIHBhcnRpY2lwYW50IFRDIGFzIFRyYW5zcGFyZW5jeSAmIENvbnNlbnQgUG9ydGFsXG4gICAgTm90ZSBvdmVyIFUsVEM6IDEuIEhvbm9yIHVzZXIgb3B0LW91dHMuXG4gICAgVS0-PlRDOiAxLWEuIFVzZXIgb3B0cyBvdXQuXG4gICAgYWN0aXZhdGUgVENcbiAgICBUQy0-PlVJRDI6IDEtYi4gVUlEMiBzZXJ2aWNlIHJlY2VpdmVzIG9wdC1vdXQuXG4gICAgZGVhY3RpdmF0ZSBUQ1xuICAgIGFjdGl2YXRlIFVJRDJcbiAgICBVSUQyLT4-RFNQOiAxLWMuIERTUCByZWNlaXZlcyBvcHQtb3V0LlxuICAgIGRlYWN0aXZhdGUgVUlEMlxuICAgIE5vdGUgb3ZlciBVLFRDOiAyLiBEZWNyeXB0IFVJRDIgdG9rZW5zIHRvIHVzZSBpbiBSVEIuXG4gICAgU1NQLS0-PkRTUDogVGhlIFNTUCBjYWxscyBhIERTUCBmb3IgYmlkLlxuICAgIERTUC0-PkRTUDogMi1hLiBEZWNyeXB0IFVJRDIgdG9rZW5zLlxuICAgIERTUC0-PkRTUDogMi1iLiBFeGVjdXRlIGJpZGRpbmcgbG9naWMsIGhvbm9yaW5nIHVzZXIgb3B0LW91dHMuXG4iLCJtZXJtYWlkIjp7InRoZW1lIjoiZm9yZXN0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)
 
 ### Honor User Opt-Outs
 
-To receive and honor user opt-outs from the UID2 service, DSPs establish a pre-configured interface and provides it to the UID2 service during onboarding. The UID2 service sends the user's UID2 and an opt-out timestamp to the pre-determined interface. Examples of interfaces include webhooks and API endpoints.
+To receive and honor user opt-outs from the UID2 service, the DSP establishes a pre-configured interface (an opt-out webhook/API endpoint) and provides it to the UID2 service during onboarding. When a user opts out, the UID2 service sends the user's raw UID2 and the corresponding opt-out timestamp to the pre-configured interface.
 
-The UID2 service will send the following data within seconds of a user's opt-out, which the DSP records and uses the bidding logic defined in [Decrypt UID2 Tokens for RTB Use](#decrypt-uid2-tokens-for-rtb-use).
+The UID2 service sends the following data within seconds of a user's opt-out, which the DSP records and uses the bidding logic defined in [Decrypt UID2 Tokens for RTB Use](#decrypt-uid2-tokens-for-rtb-use).
 
 | Parameter | Description |
 | :--- | :--- |
-| `identity` | The UID2 for the user who opted out. |
+| `identity` | The raw UID2 for the user who opted out. |
 | `timestamp` | The time when the user opted out. |
 
 
@@ -46,15 +52,15 @@ https://dsp.example.com/optout?user=%%identity%%&optouttime=%%timestamp%%
 
 Use the logic below during bidding (2-b) to honor a user's opt-out.
 
-Leverage one of the server-side SDKs (see [SDKs](../sdks/summary-sdks.md)) to decrypt incoming UID2 tokens. The response contains the UID2 and time the UID2 was created, represented in the psuedocode below as `established_timestamp`. DSPs are required to check the most recent opt-out timestamp for a UID2, represented in the pseudocode below as `optout_timestamp`. 
+Leverage one of the server-side SDKs (see [SDKs](../sdks/summary-sdks.md)) to decrypt incoming UID2 tokens into raw UID2s. The response to the decrypt function contains the raw UID2 and the timestamp (the time that the [POST /token/generate](../endpoints/post-token-generate.md) endpoint was called to create the UID2 token), represented in the pseudocode example below as `established_timestamp`. DSPs are required to check the most recent opt-out timestamp for a UID2, represented in the pseudocode below as `optout_timestamp`. 
 
 The following diagram illustrates opt-out logic.
 
-![DSP Opt-Out Check](https://mermaid.ink/svg/eyJjb2RlIjoiZ3JhcGggTFJcbkFbRGVjcnlwdCBVSUQyIFRva2VuXSAtLT4gQltSZXRyaWV2ZSBPcHQtb3V0IGZvciBVSUQyXVxuICAgIEIgLS0-IEN7Q2hlY2sgT3B0LW91dH1cbiAgICBDIC0tPiB8T3B0ZWQgT3V0fCBEW0JpZCB3aXRob3V0IFVJRDJdXG4gICAgQyAtLT4gfE5vdCBPcHRlZCBPdXR8IEVbQmlkIHdpdGggVUlEMl1cbiIsIm1lcm1haWQiOnsidGhlbWUiOiJmb3Jlc3QifSwidXBkYXRlRWRpdG9yIjpmYWxzZX0)
+![DSP Opt-Out Check](images/dsp-guide-optout.png)
 
-If the `established_timestamp` value is less than the `optout_timestamp` value, the user opted out and the UID2 should not be used for RTB. In these cases, it is up to the DSP whether they want to send an alternate ID for bidding or not bid.
+If the `established_timestamp` value is less than the `optout_timestamp` value, the user has opted out and the UID2 should not be used for RTB. In these cases, the DSP can choose to send an alternate ID for bidding or can choose not to bid.
 
-The logic for the <b>check opt-out</b> step is the following:
+The following pseudocode shows sample logic for the <b>check opt-out</b> step:
 
 ```java
 if (established_timestamp < optout_timestamp) {
@@ -64,6 +70,8 @@ if (established_timestamp < optout_timestamp) {
 
 ### Decrypt UID2 Tokens for RTB Use
 
+The following table provides details for Step 2 of the workflow diagram shown in [Integration Steps](#integration-steps).
+
 | Step | SDK | Description |
 | :--- | :--- | :--- |
 | 2-a | Server-side SDK (see [SDKs](../sdks/summary-sdks.md))  | Leverage the provided SDK to decrypt incoming UID2 tokens. The response contains the `UID2` and the UID2 creation time. |
@@ -72,5 +80,3 @@ if (established_timestamp < optout_timestamp) {
 ## FAQs
 
 For a list of frequently asked questions for DSPs, see [FAQs for Demand-Side Platforms (DSPs)](../getting-started/gs-faqs.md#faqs-for-demand-side-platforms-dsps).
-
-For a full list, see [Frequently Asked Questions](../getting-started/gs-faqs.md).

docs/guides/images/resource/dsp-guide-optout-mermaid.md.bak

@@ -0,0 +1,35 @@
+graph LR
+A[Decrypt UID2 Token] --> B[Retrieve Opt-out for UID2]
+    B --> C{Check Opt-out}
+    C --> |Opted Out| D[Bid without UID2]
+    C --> |Not Opted Out| E[Bid with UID2]
+
+<!-- Edit in Mermaid Live Editor: https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiZ3JhcGggTFJcbkFbRGVjcnlwdCBVSUQyIFRva2VuXSAtLT4gQltSZXRyaWV2ZSBPcHQtb3V0IGZvciBVSUQyXVxuICAgIEIgLS0-IEN7Q2hlY2sgT3B0LW91dH1cbiAgICBDIC0tPiB8T3B0ZWQgT3V0fCBEW0JpZCB3aXRob3V0IFVJRDJdXG4gICAgQyAtLT4gfE5vdCBPcHRlZCBPdXR8IEVbQmlkIHdpdGggVUlEMl1cbiIsIm1lcm1haWQiOnsidGhlbWUiOiJmb3Jlc3QifSwidXBkYXRlRWRpdG9yIjpmYWxzZX0 -->
+
+-------------------- above is legacy --------------------
+
+For the above: link to SVG, in doc, is:
+
+<!-- https://mermaid.ink/svg/eyJjb2RlIjoiICBzZXF1ZW5jZURpYWdyYW1cbiAgICBwYXJ0aWNpcGFudCBVIGFzIFVzZXJcbiAgICBwYXJ0aWNpcGFudCBTU1BcbiAgICBwYXJ0aWNpcGFudCBEU1BcbiAgICBwYXJ0aWNpcGFudCBVSUQyIGFzIFVJRDIgU2VydmljZVxuICAgIHBhcnRpY2lwYW50IFRDIGFzIFRyYW5zcGFyZW5jeSAmIENvbnNlbnQgUG9ydGFsXG4gICAgTm90ZSBvdmVyIFUsVEM6IDEuIEhvbm9yIHVzZXIgb3B0LW91dHMuXG4gICAgVS0-PlRDOiAxLWEuIFVzZXIgb3B0cyBvdXQuXG4gICAgYWN0aXZhdGUgVENcbiAgICBUQy0-PlVJRDI6IDEtYi4gVUlEMiBzZXJ2aWNlIHJlY2VpdmVzIG9wdC1vdXQuXG4gICAgZGVhY3RpdmF0ZSBUQ1xuICAgIGFjdGl2YXRlIFVJRDJcbiAgICBVSUQyLT4-RFNQOiAxLWMuIERTUCByZWNlaXZlcyBvcHQtb3V0LlxuICAgIGRlYWN0aXZhdGUgVUlEMlxuICAgIE5vdGUgb3ZlciBVLFRDOiAyLiBEZWNyeXB0IFVJRDIgdG9rZW5zIHRvIHVzZSBpbiBSVEIuXG4gICAgU1NQLS0-PkRTUDogVGhlIFNTUCBjYWxscyBhIERTUCBmb3IgYmlkLlxuICAgIERTUC0-PkRTUDogMi1hLiBEZWNyeXB0IFVJRDIgdG9rZW5zLlxuICAgIERTUC0-PkRTUDogMi1iLiBFeGVjdXRlIGJpZGRpbmcgbG9naWMsIGhvbm9yaW5nIHVzZXIgb3B0LW91dHMuXG4iLCJtZXJtYWlkIjp7InRoZW1lIjoiZm9yZXN0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9 -->
+
+-------------------- below is update 9/5/23 --------------------
+
+graph LR
+A[Decrypt UID2 token] --> B[Retrieve UID2 opt-out status]
+    B --> C{Check for <br/>opt-out}
+    C --> |Opted out| D[Bid without UID2]
+    C --> |Not opted out| E[Bid with UID2]
+
+Edit link: 
+
+https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNpVkMtugzAQRX_FmjWkPJK4WFWkJmRRqQ8pVTcNWbgwKSgFIzO0pYR_r4EGqbPyXJ-5Y98WYpUgCHjXskzZ_S4qbvchxropib3chR4jdcLiwGx7xdb7HZLO8BPHK1WSrWpiFUmqq0NUMFPrAd20mxTjEzsqzW7e9NXqj-1GaDNA56eSMGFGPrNwv84S9pVR2jv29od_6KOift8F3074hQULctS5zBLzm7afjYBSzDECYY7mIVhRBFHRGVLWpJ6bIgZBukYL6jKRhGEmTQw5iKP8qCZ1m2Sk9CTi0D6MqQ3hWVDK4lWp_OJmWhAtfINw_Znjc-65rjsPgiXnFjQg5ov5zFkE3Fl4ge_yoLPgZxh3ZsFYfOka4Nrj3S-UhoHv
+
+SVG URL -- but the SVG doesn't include the colors so that doesn't work. Need to figure out how to include the CSS in the SVG output: 
+
+https://mermaid.ink/svg/pako:eNpVkM1ugzAQhF_F2jOkYBJCrCpSE3Ko1B8pVS8FDi5sCkrByCxtU8K715AmUnzyzn479k4HqcoQBHxoWefsYRtXd1GIqT7UxF7vQ85I7bFKmG0v2SraIukCv_DUUjXZqiXWkKS2SeKKmbMa0XW3zjHds53S7PZd3yz_2f4ErUfo-FwTZszIRxZGqyJj3wXlg-Ngn1yhT4qG98745oKfWbCgRF3KIjPbdMNsDJRjiTEIczUfwYZiiKvekLIl9XKoUhCkW7SgrTNJGBbSxFBei5usIKVB7ORnY0Qcy8dTaGN2FtSyelPqMmdKEB38gHC9iePN59zxA4d7fuD6FhxATGfTiTNb-AvuBTxw-ay34Hc0cPs_j19-aQ
+
+Exported SVG: dsp-guide-optout.svg but it didn't display, so, not saved.
+
+Summary 9/5/23: still not able to export to SVG with theme applied. Saved PNG in UI instead.
+
+PNG saved from UI display: dsp-guide-optout.png.