From 0b1856434c64d344cb1415387fb8d40f55e700d5 Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Thu, 17 Oct 2024 14:10:53 -0400 Subject: [PATCH 1/2] Token refresh, add to glossary + add links --- docs/endpoints/post-token-refresh.md | 2 +- docs/getting-started/gs-faqs.md | 2 +- docs/guides/integration-javascript.md | 2 +- docs/guides/integration-mobile-client-server.md | 2 +- docs/guides/integration-prebid-client-server.md | 2 +- docs/overviews/overview-publishers.md | 2 +- docs/ref-info/glossary-uid.md | 9 ++++++++- docs/ref-info/ref-tokens.md | 2 +- docs/sdks/sdk-ref-javascript-v2.md | 3 +-- 9 files changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/endpoints/post-token-refresh.md b/docs/endpoints/post-token-refresh.md index 45c4ea22d..7f5d7eb51 100644 --- a/docs/endpoints/post-token-refresh.md +++ b/docs/endpoints/post-token-refresh.md @@ -28,7 +28,7 @@ Add the content of the `refresh_token` value, returned in the response from the Here's what you need to know about this endpoint: -- No encryption is required for token refresh requests. +- No encryption is required for requests to the `POST /token/refresh` endpoint. - If the request is successful, with an HTTP status code of 200, a new UID2 token or opt-out information is returned. - Successful responses, whether the response includes a new token or opt-out information, are encrypted. Error responses are not encrypted. - To decrypt responses, use the most recent `refresh_response_key` value for this token. The `refresh_response_key` value is returned in the response to the [POST /token/generate](post-token-generate.md) and `POST /token/refresh` operations. Each time a token is refreshed, a new `refresh_response_key` is returned. Be sure to use the most recent one to decrypt the current response. diff --git a/docs/getting-started/gs-faqs.md b/docs/getting-started/gs-faqs.md index 6a3d4ec47..7bf2fa972 100644 --- a/docs/getting-started/gs-faqs.md +++ b/docs/getting-started/gs-faqs.md @@ -101,7 +101,7 @@ The recommended refresh interval is hourly. To determine when to refresh, you can use the timestamp of the `refresh_from` field in the response to the [POST /token/generate](../endpoints/post-token-generate.md) endpoint (see [Successful Response](../endpoints/post-token-generate.md#successful-response)) or [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint (see [Successful Response With Tokens](../endpoints/post-token-refresh.md#successful-response-with-tokens)). -You could also use one of the SDKs that has a function to check if token refresh is needed. +You could also use one of the SDKs that has a function to check if token refresh is needed. For details, see [Recommended Token Refresh Frequency](../ref-info/ref-tokens.md#recommended-token-refresh-frequency) and [Managing Token Refresh with an SDK](../ref-info/ref-tokens.md#managing-token-refresh-with-an-sdk). diff --git a/docs/guides/integration-javascript.md b/docs/guides/integration-javascript.md index 213fac32e..9573c8dbb 100644 --- a/docs/guides/integration-javascript.md +++ b/docs/guides/integration-javascript.md @@ -42,7 +42,7 @@ From the table in [Client-Side or Client-Server Integration](#client-side-or-cli ## Refreshing the UID2 Token -The SDK for JavaScript includes automated token refresh. +The SDK for JavaScript includes automated token refresh. ## Storing the UID2 Token in the Browser diff --git a/docs/guides/integration-mobile-client-server.md b/docs/guides/integration-mobile-client-server.md index a8c1d2688..a2bc04c37 100644 --- a/docs/guides/integration-mobile-client-server.md +++ b/docs/guides/integration-mobile-client-server.md @@ -85,7 +85,7 @@ For security reasons, the API key and secret used in token generation must be ca ## Server-Side Token Refresh -Token refresh is automatically enabled inside the UID2 mobile SDKs; you don't need to manage it explicitly on the server side. +Token refresh is automatically enabled inside the UID2 mobile SDKs; you don't need to manage it explicitly on the server side. You might decide to do server-side token refresh if you want to keep your changes in the mobile apps as simple as possible. diff --git a/docs/guides/integration-prebid-client-server.md b/docs/guides/integration-prebid-client-server.md index d580438cd..5563e406d 100644 --- a/docs/guides/integration-prebid-client-server.md +++ b/docs/guides/integration-prebid-client-server.md @@ -20,7 +20,7 @@ This is called client-server integration because some integration steps are clie To integrate with UID2 using Prebid.js, you'll need to: - Make changes to the HTML and JavaScript on your site. -- Make server-side changes for token generation (and, optionally, token refresh). +- Make server-side changes for token generation (and, optionally, token refresh). ## Prebid.js Version This implementation requires Prebid.js version 7.53.0 or later. For version information, see [https://github.com/prebid/Prebid.js/releases](https://github.com/prebid/Prebid.js/releases). diff --git a/docs/overviews/overview-publishers.md b/docs/overviews/overview-publishers.md index 5004133b3..50cf82a6f 100644 --- a/docs/overviews/overview-publishers.md +++ b/docs/overviews/overview-publishers.md @@ -105,7 +105,7 @@ For a detailed summary of web integration options, see [Web Integration Overview | Integration Type | Documentation | Content Description | |:-------------------------------------|:----------------------------------------------------------------------------------------------------| :--- | | Prebid (Overview) | [UID2 Integration Overview for Prebid](../guides/integration-prebid.md) | An overview of options for publishers who want to integrate with UID2 and generate UID2 tokens to be passed by Prebid.js or Prebid Mobile SDK in the RTB bidstream. | -| Prebid.js Client-Side Integration | [UID2 Client-Side Integration Guide for Prebid.js](../guides/integration-prebid-client-side.md) | A guide for publishers who want to request UID2 tokens client-side, which is the easiest implementation approach, and choose to have Prebid.js manage the following: | +| Prebid.js Client-Side Integration | [UID2 Client-Side Integration Guide for Prebid.js](../guides/integration-prebid-client-side.md) | A guide for publishers who want to request UID2 tokens client-side, which is the easiest implementation approach, and choose to have Prebid.js manage the following: | | Prebid.js Client-Server Integration | [UID2 Client-Server Integration Guide for Prebid.js](../guides/integration-prebid-client-server.md) | A guide for publishers who want to integrate with UID2 and generate UID2 tokens (advertising tokens) to be passed by Prebid.js in the RTB bidstream, but want to generate tokens server-side: for example, publishers who are using a Private Operator. | | JavaScript (Overview) | [UID2 Integration Overview for JavaScript](../guides/integration-javascript.md) | An overview of options for publishers who want to integrate with UID2 using the JavaScript SDK. | | JavaScript Client-Side Integration | [Client-Side Integration Guide for JavaScript](../guides/integration-javascript-client-side.md) | A guide for publishers who want to integrate with UID2 using only client-side JavaScript changes, which is the easiest implementation approach.
The SDK for JavaScript manages token generation and token refresh automatically. | diff --git a/docs/ref-info/glossary-uid.md b/docs/ref-info/glossary-uid.md index 6e26f1074..b054034b6 100644 --- a/docs/ref-info/glossary-uid.md +++ b/docs/ref-info/glossary-uid.md @@ -99,6 +99,7 @@ import Link from '@docusaurus/Link'; Subscription ID **T** +Tokenrefresh | Tokenized sharing | Transparency and Control Portal @@ -433,6 +434,12 @@ import Link from '@docusaurus/Link';
+
Token refresh
+
When a UID2 participant requests a UID2 token, the token is returned with a set of associated values, including a refresh token and timestamps for the UID2 token and the refresh token. As long as the refresh token has not expired, the publisher can use it to request a fresh UID2 token without having to send DII.
+
Any UID2 participant that requests a UID2 token must have some token refresh mechanism in place, to monitor the refresh period and request a new UID2 token before the refresh token expires. In most cases, token refresh is managed by an SDK or other implementation strategy such as a Prebid.js implementation.
+
If the refresh token expires, the publisher must re-request a UID2 token by sending DII.
+
For details, see UID2 Tokens and Refresh Tokens.
+
Tokenized sharing
Tokenized sharing means encrypting DII or Raw UID2s into UID2 tokens and sharing the tokens with authorized recipients. Using UID2 tokens helps protect raw UID2s end-to-end between the sender and receiver of the data, including when the data passes through unauthorized parties. Tokenized sharing is required for sharing in the bidstream or via pixels, but you can use it in any sharing use case.
For details, see Tokenized Sharing Overview.
@@ -474,7 +481,7 @@ import Link from '@docusaurus/Link';
The token value is opaque: No assumptions should be made about the format or about the length of the string.
The token has a limited life, but can be refreshed in the background using the refresh token.
Publishers send UID2 tokens in the bidstream.
-
For details, see UID2 Identifier Types.
+
For details, see UID2 Identifier Types and UID2 Tokens: Key Information.
Unified ID 2.0
The term UID2 can be used to mean the UID2 framework, the UID2 service, a raw UID2, or a UID2 token (advertising token).
diff --git a/docs/ref-info/ref-tokens.md b/docs/ref-info/ref-tokens.md index 7d5be26ac..98919dd52 100644 --- a/docs/ref-info/ref-tokens.md +++ b/docs/ref-info/ref-tokens.md @@ -37,7 +37,7 @@ Here are some key points about refresh tokens: - The token value is an opaque string: do not make any assumptions about the format or length of the string. - You can use the refresh token to generate a new UID2 token and new refresh token before the current refresh token expires. - Using refresh tokens is optional: you could choose to generate a new token from DII each time rather than refreshing an existing token. -- You can manage token refresh in a variety of ways, such as: +- You can manage token refresh in a variety of ways, such as: - With a UID2 SDK (see [SDK Functionality](../sdks/summary-sdks.md#sdk-functionality)) - By calling the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint - By using the UID2 Prebid.js module (see [UID2 Integration Overview for Prebid.js](../guides/integration-prebid.md)) diff --git a/docs/sdks/sdk-ref-javascript-v2.md b/docs/sdks/sdk-ref-javascript-v2.md index 3c7fcbd45..c521c08c3 100644 --- a/docs/sdks/sdk-ref-javascript-v2.md +++ b/docs/sdks/sdk-ref-javascript-v2.md @@ -103,8 +103,7 @@ As part of the SDK [initialization](#initopts-object-void), a token auto-refresh Here's what you need to know about the token auto-refresh: - -- Only one token refresh call can be active at a time. +- Only one call to the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint call can be active at a time. - If the [POST /token/refresh](../endpoints/post-token-refresh.md) response is unsuccessful because the user has opted out, or because the refresh token has expired, this suspends the background auto-refresh process. To use UID2-based targeted advertising again, you must obtain the email or phone number from the consumer ([isLoginRequired()](#isloginrequired-boolean) returns `true`). In all other cases, auto-refresh attempts continue in the background. - The [callback function](#callback-function) specified during the SDK initialization is invoked in the following cases: - After each successful refresh attempt. From 80816c4c15d0b7320cf85bf7e92d865bdd976d36 Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Fri, 18 Oct 2024 10:04:24 -0400 Subject: [PATCH 2/2] edit from SW --- docs/ref-info/glossary-uid.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/ref-info/glossary-uid.md b/docs/ref-info/glossary-uid.md index b054034b6..0cf8ef86e 100644 --- a/docs/ref-info/glossary-uid.md +++ b/docs/ref-info/glossary-uid.md @@ -436,7 +436,8 @@ import Link from '@docusaurus/Link';
Token refresh
When a UID2 participant requests a UID2 token, the token is returned with a set of associated values, including a refresh token and timestamps for the UID2 token and the refresh token. As long as the refresh token has not expired, the publisher can use it to request a fresh UID2 token without having to send DII.
-
Any UID2 participant that requests a UID2 token must have some token refresh mechanism in place, to monitor the refresh period and request a new UID2 token before the refresh token expires. In most cases, token refresh is managed by an SDK or other implementation strategy such as a Prebid.js implementation.
+
Any UID2 participant that requests a UID2 token must have a process in place for keeping the token valid: either monitoring the refresh period and requesting a new UID2 token before the refresh token expires, or requesting a new UID2 token each time, which requires sending DII.
+
In most cases, token refresh is managed by an SDK or other implementation strategy such as a Prebid.js implementation.
If the refresh token expires, the publisher must re-request a UID2 token by sending DII.
For details, see UID2 Tokens and Refresh Tokens.