Merge pull request #692 from IABTechLab/mkc-UID2-3807-update-example-…

…tokens Update ad token examples to v4
IABTechLab · Aug 30, 2024 · e9b1eac · e9b1eac
2 parents 76e0615 + 63bb80e
commit e9b1eac
Show file tree

Hide file tree

Showing 25 changed files with 206 additions and 398 deletions.
diff --git a/docs/endpoints/post-token-generate.md b/docs/endpoints/post-token-generate.md
@@ -6,6 +6,7 @@ sidebar_position: 02
 ---
 
 import Link from '@docusaurus/Link';
+import IdentityGenerateResponse from '/docs/snippets/_example-identity-generate-response.mdx';
 
 # POST /token/generate
 
@@ -104,19 +105,7 @@ This section includes the following sample responses:
 
 A successful decrypted response returns the user's advertising and refresh tokens for the specified email address, phone number, or the respective hash. 
 
-```json
-{
-    "body": {
-        "advertising_token": "AdvertisingTokenmZ4dZgeuXXl6DhoXqbRXQbHlHhA96leN94U1uavZVspwKXlfWETZ3b/besPFFvJxNLLySg4QEYHUAiyUrNncgnm7ppu0mi6wU2CW6hssiuEkKfstbo9XWgRUbWNTM+ewMzXXM8G9j8Q=",
-        "refresh_token": "RefreshToken2F8AAAF2cskumF8AAAF2cskumF8AAAADXwFq/90PYmajV0IPrvo51Biqh7/M+JOuhfBY8KGUn//GsmZr9nf+jIWMUO4diOA92kCTF69JdP71Ooo+yF3V5yy70UDP6punSEGmhf5XSKFzjQssCtlHnKrJwqFGKpJkYA==",
-        "identity_expires": 1633643601000,
-        "refresh_from": 1633643001000,
-        "refresh_expires": 1636322000000,
-        "refresh_response_key": "wR5t6HKMfJ2r4J7fEGX9Gw=="
-    },
-    "status": "success"
-}
-```
+<IdentityGenerateResponse />
 
 #### Optout
 

diff --git a/docs/endpoints/post-token-refresh.md b/docs/endpoints/post-token-refresh.md
@@ -6,6 +6,7 @@ sidebar_position: 04
 ---
 
 import Link from '@docusaurus/Link';
+import IdentityGenerateResponse from '/docs/snippets/_example-identity-generate-response.mdx';
 
 # POST /token/refresh
 
@@ -67,19 +68,7 @@ This section includes the following sample responses:
 
 If all values are valid and the user has not opted out, the response is successful and a new UID2 token is returned, with associated values. The following example shows a decrypted successful response with tokens:
 
-```json
-{
-    "body": {
-        "advertising_token": "NewAdvertisingTokenIjb6u6KcMAtd0/4ZIAYkXvFrMdlZVqfb9LNf99B+1ysE/lBzYVt64pxYxjobJMGbh5q/HsKY7KC0Xo5Rb/Vo8HC4dYOoWXyuGUaL7Jmbw4bzh+3pgokelUGyTX19DfArTeIg7n+8cxWQ=",
-        "refresh_token": "NewRefreshTokenAAAF2c8H5dF8AAAF2c8H5dF8AAAADX393Vw94afoVLL6A+qjdSUEisEKx6t42fLgN+2dmTgUavagz0Q6Kp7ghM989hKhZDyAGjHyuAAwm+CX1cO7DWEtMeNUA9vkWDjcIc8yeDZ+jmBtEaw07x/cxoul6fpv2PQ==",
-        "identity_expires": 1633643601000,
-        "refresh_from": 1633643001000,
-        "refresh_expires": 1636322000000,
-        "refresh_response_key": "yptCUTBoZm1ffosgCrmuwg=="
-    },
-    "status": "success"
-}
-```
+<IdentityGenerateResponse />
 
 #### Successful Response With Opt-Out
 

diff --git a/docs/getting-started/gs-encryption-decryption.md b/docs/getting-started/gs-encryption-decryption.md
@@ -8,6 +8,7 @@ sidebar_position: 11
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import Link from '@docusaurus/Link';
+import IdentityGenerateResponse from '/docs/snippets/_example-identity-generate-response.mdx';
 
 # Encrypting Requests and Decrypting Responses
 
@@ -103,20 +104,7 @@ The following table describes the field layout for response decryption code.
 
 For example, a decrypted response to the [POST&nbsp;/token/generate](../endpoints/post-token-generate.md) request for an email address might look like this:
 
-```json
-{
-    "body": {
-        "advertising_token": "AgAAAQFt3aNLXKXEyWS8Tpezcymk1Acv3n+ClOHLdAgqR0kt0Y+pQWSOVaW0tsKZI4FOv9K/rZH9+c4lpm2DBpmFJqjdF6FAaAzva5vxDIX/67UOspsYtiwxH73zU7Fj8PhVf1JcpsxUHRHzuk3vHF+ODrM13A8NAVlO1p0Wkb+cccIIhQ==",
-        "user_token": "AgAAAPpTqz7/Z+40Ue5G3XOM2RiyU6RS9Q5yj1n7Tlg7PN1K1LZWejvo8Er7A+Q8KxdXdj0OrKRf/XEGWsyUJscRNu1bg/MK+5AozvoJKUca8b10eQdYU86ZOHPH7pFnFhD5WHs=",
-        "refresh_token": "AAAAAQLMcnV+YE6/xoPDZBJvJtWyPyhF9QTV4242kFdT+DE/OfKsQ3IEkgCqD5jmP9HuR4O3PNSVnCnzYq2BiDDz8SLsKOo6wZsoMIn95jVWBaA6oLq7uUGY5/g9SUOfFmX5uDXUvO0w2UCKi+j9OQhlMfxTsyUQUzC1VQOx6ed/gZjqH/Sw6Kyk0XH7AlziqSyyXA438JHqyJphGVwsPl2LGCH1K2MPxkLmyzMZ2ghTzrr0IgIOXPsL4lXqSPkl/UJqnO3iqbihd66eLeYNmyd1Xblr3DwYnwWdAUXEufLoJbbxifGYc+fPF+8DpykpyL9neq3oquxQWpyHsftnwYaZT5EBZHQJqAttHUZ4yQ==",
-        "identity_expires": 1654623500142,
-        "refresh_expires": 1657214600142,
-        "refresh_from": 1654622900142,
-        "refresh_response_key": "wR5t6HKMfJ2r4J7fEGX9Gw=="
-    },
-    "status": "success"
-}
-```
+<IdentityGenerateResponse />
 
 ## Encryption and Decryption Code Examples
 

diff --git a/docs/getting-started/gs-faqs.md b/docs/getting-started/gs-faqs.md
@@ -6,6 +6,7 @@ sidebar_position: 20
 ---
 
 import Link from '@docusaurus/Link';
+import ExampleUid2InBidstream from '/docs/snippets/_example-uid2-in-bidstream.mdx';
 
 # Frequently Asked Questions
 
@@ -115,25 +116,7 @@ The UID2 service encrypts UID2 tokens using random initialization vectors. The U
 
 There are many ways to approach UID2 implementation. Here is one example of a code snippet showing how a UID2 token is passed in the <Link href="../ref-info/glossary-uid#gl-bidstream">bidstream</Link>:
 
-```js
-{
-  "user":{
-    "ext":{
-      "eids":[
-        {
-          "source":"uidapi.com",
-          "uids":[
-            {
-              "id":"AgAAAHcy2ka1tSweERARV/wgwM+zM5wK98b9XItZGVgHaU23Eh0XOmAixO6VBcMd3k2ir/TGHLf7O7kQGLyeRPC5/VBSPmugOblMlzgy0B1ZfHQ7ccVurbyzgL1ZZOZ5cBvPDrvfR9MsKqPgWvrIKRkKVTYyUkG5YRAc++xRKfbL/ZSYxQ==",
-              "rtiPartner":"UID2"
-            }
-          ]
-        }
-      ]
-    }
-  }
-}
-```
+<ExampleUid2InBidstream />
 
 ## FAQs for Advertisers and Data Providers
 

diff --git a/docs/guides/integration-javascript-client-server.md b/docs/guides/integration-javascript-client-server.md
@@ -7,9 +7,8 @@ hide_table_of_contents: false
 sidebar_position: 02
 ---
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
 import Link from '@docusaurus/Link';
+import ExampleClientServerSendUid2ToSdk from '/docs/snippets/_example-client-server-send-uid2-to-sdk.mdx'; 
 
 # Client-Server Integration Guide for JavaScript
 
@@ -87,82 +86,7 @@ For security reasons, the API key and secret used in token generation must be ca
 
 The following code examples illustrate steps 1-f and 1-g, in JavaScript and TypeScript.
 
-<Tabs>
-<TabItem value='js' label='JavaScript'>
-
-```js
-  window.__uid2 = window.__uid2 || {};
-  window.__uid2.callbacks = window.__uid2.callbacks || [];
-
-  // Step 1-f
-  window.__uid2.callbacks.push((eventType, payload) => {
-    if (eventType === 'SdkLoaded') {
-      __uid2.init({
-        identity : {
-          "advertising_token": "AgmZ4dZgeuXXl6DhoXqbRXQbHlHhA96leN94U1uavZVspwKXlfWETZ3b/besPFFvJxNLLySg4QEYHUAiyUrNncgnm7ppu0mi6wU2CW6hssiuEkKfstbo9XWgRUbWNTM+ewMzXXM8G9j8Q=",
-          "refresh_token": "Mr2F8AAAF2cskumF8AAAF2cskumF8AAAADXwFq/90PYmajV0IPrvo51Biqh7/M+JOuhfBY8KGUn//GsmZr9nf+jIWMUO4diOA92kCTF69JdP71Ooo+yF3V5yy70UDP6punSEGmhf5XSKFzjQssCtlHnKrJwqFGKpJkYA==",
-          "identity_expires": 1633643601000,
-          "refresh_from": 1633643001000,
-          "refresh_expires": 1636322000000,
-          "refresh_response_key":"dYNTB20edyHJU9mZv11e3OBDlLTlS5Vb97iQVumc7b/8QY/DDxr6FrRfEB/D",
-        }
-      });
-    }
-  });
-
-  // Step 1-g
-  window.__uid2.callbacks.push((eventType, payload) => {
-    if (eventType !== 'SdkLoaded') {
-      if (payload.identity) {
-        const advertisingToken = payload.identity.advertising_token;
-        // Pass advertising_token to your advertising system to use
-      } else {
-        // No identity is available. Trigger a workflow for obtaining email address or phone number if you want to use UID2 for targeted advertising.
-      }
-    }
-  });
-```
-
-</TabItem>
-<TabItem value='ts' label='TypeScript'>
-
-```tsx
-  import { EventType, CallbackPayload } from "./callbackManager";
-
-  window.__uid2 = window.__uid2 || {};
-  window.__uid2.callbacks = window.__uid2.callbacks || [];
-
-  // Step 1-f
-  window.__uid2.callbacks.push((eventType: EventType, payload: CallbackPayload) => {
-    if (eventType === 'SdkLoaded') {
-      __uid2.init({
-        identity : {
-          "advertising_token": "AgmZ4dZgeuXXl6DhoXqbRXQbHlHhA96leN94U1uavZVspwKXlfWETZ3b/besPFFvJxNLLySg4QEYHUAiyUrNncgnm7ppu0mi6wU2CW6hssiuEkKfstbo9XWgRUbWNTM+ewMzXXM8G9j8Q=",
-          "refresh_token": "Mr2F8AAAF2cskumF8AAAF2cskumF8AAAADXwFq/90PYmajV0IPrvo51Biqh7/M+JOuhfBY8KGUn//GsmZr9nf+jIWMUO4diOA92kCTF69JdP71Ooo+yF3V5yy70UDP6punSEGmhf5XSKFzjQssCtlHnKrJwqFGKpJkYA==",
-          "identity_expires": 1633643601000,
-          "refresh_from": 1633643001000,
-          "refresh_expires": 1636322000000,
-          "refresh_response_key":"dYNTB20edyHJU9mZv11e3OBDlLTlS5Vb97iQVumc7b/8QY/DDxr6FrRfEB/D",
-        }
-      });
-    }
-  });
-
-  // Step 1-g
-  window.__uid2.callbacks.push((eventType: EventType, payload: CallbackPayload) => {
-    if (eventType !== 'SdkLoaded') {
-      if (payload.identity) {
-        const advertisingToken = payload.identity.advertising_token;
-        // Pass advertising_token to your advertising system to use
-      } else {
-        // No identity is available. Trigger a workflow for obtaining email address or phone number if you want to use UID2 for targeted advertising.
-      }
-    }
-  });
-```
-
-</TabItem>
-</Tabs>
+<ExampleClientServerSendUid2ToSdk />
 
 The SDK invokes the specified [callback function](../sdks/sdk-ref-javascript.md#callback-function) (which indicates the identity availability) and makes the established identity available client-side for bidding. 
 

diff --git a/docs/guides/integration-mobile-client-server.md b/docs/guides/integration-mobile-client-server.md
@@ -13,6 +13,7 @@ import Link from '@docusaurus/Link';
 import EnableLogging from '/docs/snippets/_mobile-docs-enable-logging.mdx';
 import GMAIMA_Plugins from '/docs/snippets/_mobile_docs_gmaima-plugin-gss.mdx';
 import PrebidMobileSDK from '/docs/snippets/_mobile_docs_prebid-mobile.mdx';
+import ExampleAdvertisingToken from '/docs/snippets/_example-advertising-token.mdx';
 
 # UID2 Client-Server Integration Guide for Mobile
 
@@ -222,9 +223,7 @@ UID2Manager.shared.getAdvertisingToken()
 
 If a successful identity was added into the UID2Manager, this method returns a string such as the following:
 
-```
-AgAAAQFt3aNLXKXEyWS8Tpezcymk1Acv3n+ClOHLdAgqR0kt0Y+pQWSOVaW0tsKZI4FOv9K/rZH9+c4lpm2DBpmFJqjdF6FAaAzva5vxDIX/67UOspsYtiwxH73zU7Fj8PhVf1JcpsxUHRHzuk3vHF+ODrM13A8NAVlO1p0Wkb+cccIIhQ==
-```
+<ExampleAdvertisingToken />
 
 You can use this identity to pass downstream for sending in the RTB bidstream.
 

diff --git a/docs/guides/integration-mobile-client-side.md b/docs/guides/integration-mobile-client-side.md
@@ -13,6 +13,7 @@ import Link from '@docusaurus/Link';
 import EnableLogging from '/docs/snippets/_mobile-docs-enable-logging.mdx';
 import GMAIMA_Plugins from '/docs/snippets/_mobile_docs_gmaima-plugin-gss.mdx';
 import PrebidMobileSDK from '/docs/snippets/_mobile_docs_prebid-mobile.mdx';
+import ExampleAdvertisingToken from '/docs/snippets/_example-advertising-token.mdx';
 
 
 # UID2 Client-Side Integration Guide for Mobile
@@ -562,9 +563,7 @@ UID2Manager.shared.getAdvertisingToken()
 
 If successful, this method call returns the token&#8212;a non-null string object such as the following: 
 
-```js
-AgAAAQFt3aNLXKXEyWS8Tpezcymk1Acv3n+ClOHLdAgqR0kt0Y+pQWSOVaW0tsKZI4FOv9K/rZH9+c4lpm2DBpmFJqjdF6FAaAzva5vxDIX/67UOspsYtiwxH73zU7Fj8PhVf1JcpsxUHRHzuk3vHF+ODrM13A8NAVlO1p0Wkb+cccIIhQ==
-```
+<ExampleAdvertisingToken />
 
 You can use this token to pass downstream for sending in the RTB bidstream.
 

diff --git a/docs/sdks/sdk-ref-javascript-v2.md b/docs/sdks/sdk-ref-javascript-v2.md
@@ -6,6 +6,8 @@ sidebar_position: 02
 ---
 
 import Link from '@docusaurus/Link';
+import ExampleUid2Cookie from '/docs/snippets/_example-uid2-cookie.mdx';
+import ExampleJavaScriptV2Init from '/docs/snippets/_example-javascript-v2-init.mdx';
 
 # SDK for JavaScript Reference Guide (2.x and earlier versions)
 
@@ -155,20 +157,7 @@ The following is a template of an `init()` call with the server-side generated i
 
 For example:
 
-```html
-<script>
- __uid2.init({
-   callback : onUid2IdentityUpdated,
-   identity : {
-        "advertising_token": "AgmZ4dZgeuXXl6DhoXqbRXQbHlHhA96leN94U1uavZVspwKXlfWETZ3b/besPFFvJxNLLySg4QEYHUAiyUrNncgnm7ppu0mi6wU2CW6hssiuEkKfstbo9XWgRUbWNTM+ewMzXXM8G9j8Q=",
-        "refresh_token": "Mr2F8AAAF2cskumF8AAAF2cskumF8AAAADXwFq/90PYmajV0IPrvo51Biqh7/M+JOuhfBY8KGUn//GsmZr9nf+jIWMUO4diOA92kCTF69JdP71Ooo+yF3V5yy70UDP6punSEGmhf5XSKFzjQssCtlHnKrJwqFGKpJkYA==",
-        "identity_expires": 1633643601000,
-        "refresh_from": 1633643001000,
-        "refresh_expires": 1636322000000
-    }
- });
-</script>
-```
+<ExampleJavaScriptV2Init />
 
 The following is an example of an `init()` call that uses identity from a first-party cookie. You can put a script like this on any page that the user might visit after the identity has been established.
 
@@ -344,17 +333,7 @@ The UID2 cookie contents are a URI-encoded string representation of a JSON objec
 
 The following is an example of the UID2 cookie structure:
 
-```json
-{
-   "advertising_token":"AgAAAAVacu1uAxgAxH+HJ8+nWlS2H4uVqr6i+HBDCNREHD8WKsio/x7D8xXFuq1cJycUU86yXfTH9Xe/4C8KkH+7UCiU7uQxhyD7Qxnv251pEs6K8oK+BPLYR+8BLY/sJKesa/koKwx1FHgUzIBum582tSy2Oo+7C6wYUaaV4QcLr/4LPA==",
-   "refresh_token":"AgAAAXxcu2RbAAABfGHhwFsAAAF79zosWwAAAAWeFJRShH8u1AYc9dYNTB20edyHJU9mZv11e3OBDlLTlS5Vb97iQVumc7b/8QY/DDxr6FrRfEB/D85E8GzziB4YH7WUCLusHaXKLxlKBSRANSD66L02H3ss56xo92LMDMA=",
-   "identity_expires":1633643601000,
-   "refresh_from":1633643001000,
-   "refresh_expires":1636322000000,
-   "private":{     
-   }
-}
-```
+<ExampleUid2Cookie />
 
 :::important
 The contents of the `private` object are explicitly unspecified and are left for the SDK to interpret. Do not make any assumptions about the structure, semantics, or compatibility of this object. Any updates to the cookie must retain its structure.

diff --git a/docs/sdks/sdk-ref-javascript.md b/docs/sdks/sdk-ref-javascript.md
@@ -8,6 +8,8 @@ sidebar_position: 02
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import Link from '@docusaurus/Link';
+import ExampleUid2Cookie from '/docs/snippets/_example-uid2-cookie.mdx';
+import ExampleJavaScriptInit from '/docs/snippets/_example-javascript-init.mdx';
 
 # SDK for JavaScript Reference Guide
 
@@ -287,25 +289,7 @@ Here's what you need to know about this function:
 
 The following is an example of an `init()` call made using a callback with the server-side generated identity included.
 
-```html
-<script>
-  window.__uid2 = window.__uid2 || {};
-  window.__uid2.callbacks = window.__uid2.callbacks || [];
-  window.__uid2.callbacks.push((eventType, payload) => {
-    if (eventType === "SdkLoaded") {
-      __uid2.init({
-        identity : { // The `body` property value from the token/generate or token/refresh API response.
-          "advertising_token": "AgmZ4dZgeuXXl6DhoXqbRXQbHlHhA96leN94U1uavZVspwKXlfWETZ3b/besPFFvJxNLLySg4QEYHUAiyUrNncgnm7ppu0mi6wU2CW6hssiuEkKfstbo9XWgRUbWNTM+ewMzXXM8G9j8Q=",
-          "refresh_token": "Mr2F8AAAF2cskumF8AAAF2cskumF8AAAADXwFq/90PYmajV0IPrvo51Biqh7/M+JOuhfBY8KGUn//GsmZr9nf+jIWMUO4diOA92kCTF69JdP71Ooo+yF3V5yy70UDP6punSEGmhf5XSKFzjQssCtlHnKrJwqFGKpJkYA==",
-          "identity_expires": 1633643601000,
-          "refresh_from": 1633643001000,
-          "refresh_expires": 1636322000000
-        }
-      });
-    }
-  });
-</script>
-```
+<ExampleJavaScriptInit />
 
 The following is an example of an `init()` call that loads a previously-provided identity from local storage, if one is available. You can put a script like this on any page that the user might visit after the identity has been established.
 
@@ -490,18 +474,8 @@ The content of the UID2 local storage or cookie is a URI-encoded string represen
 
 The following is an example of the UID2 cookie structure:
 
-```json
-{
-   "advertising_token":"AgAAAAVacu1uAxgAxH+HJ8+nWlS2H4uVqr6i+HBDCNREHD8WKsio/x7D8xXFuq1cJycUU86yXfTH9Xe/4C8KkH+7UCiU7uQxhyD7Qxnv251pEs6K8oK+BPLYR+8BLY/sJKesa/koKwx1FHgUzIBum582tSy2Oo+7C6wYUaaV4QcLr/4LPA==",
-   "refresh_token":"AgAAAXxcu2RbAAABfGHhwFsAAAF79zosWwAAAAWeFJRShH8u1AYc9dYNTB20edyHJU9mZv11e3OBDlLTlS5Vb97iQVumc7b/8QY/DDxr6FrRfEB/D85E8GzziB4YH7WUCLusHaXKLxlKBSRANSD66L02H3ss56xo92LMDMA=",
-   "identity_expires":1633643601000,
-   "refresh_from":1633643001000,
-   "refresh_expires":1636322000000,
-   "refresh_response_key":"dYNTB20edyHJU9mZv11e3OBDlLTlS5Vb97iQVumc7b/8QY/DDxr6FrRfEB/D",
-   "private":{     
-   }
-}
-```
+<ExampleUid2Cookie />
+
 :::warning
 The contents of the `private` object are explicitly unspecified and are left for the SDK to interpret. Do not make any assumptions about the structure, semantics, or compatibility of this object. Any updates to the cookie must retain its structure.
 :::

diff --git a/docs/snippets/_example-advertising-token.mdx b/docs/snippets/_example-advertising-token.mdx
@@ -0,0 +1,3 @@
+```
+A4AAAABlh75XmviGJi-hkLGs96duivRhMd3a3pe7yTIwbAHudfB9wFTj2FtJTdMW5TXXd1KAb-Z3ekQ_KImZ5Mi7xP75jRNeD6Mt6opWwXCCpQxYejP0R6WnCGnWawx9rLu59LsHv6YEA_ARNIUUl9koobfA9pLmnxE3dRedDgCKm4xHXYk01Fr8rOts6iJj2AhYISR3XkyBpqzT-vqBjsHH0g
+```