diff --git a/docs/getting-started/gs-faqs.md b/docs/getting-started/gs-faqs.md index ec3abb357..24a86130a 100644 --- a/docs/getting-started/gs-faqs.md +++ b/docs/getting-started/gs-faqs.md @@ -52,6 +52,7 @@ Here are some frequently asked questions for publishers using the UID2 framework - [How will I be notified of user opt-out?](#how-will-i-be-notified-of-user-opt-out) - [Where should I make token generation calls—from the server side or the client side?](#where-should-i-make-token-generation-callsfrom-the-server-side-or-the-client-side) - [Can I make token refresh calls from the client side?](#can-i-make-token-refresh-calls-from-the-client-side) + - [If I choose to manually refresh the token, how will I know when to refresh the token?](#if-i-choose-to-manually-refresh-the-token-how-will-i-know-when-to-refresh-the-token) - [How can I test the refresh token workflow?](#how-can-i-test-the-refresh-token-workflow) - [What is the uniqueness and rotation policy for UID2 tokens?](#what-is-the-uniqueness-and-rotation-policy-for-uid2-tokens) - [What does a UID2 token look like in the bidstream?](#what-does-a-uid2-token-look-like-in-the-bidstream) @@ -83,6 +84,16 @@ You can generate UID2 tokens from either the client side or the server side. For Yes. The [POST /token/refresh](../endpoints/post-token-refresh.md) can be called from the client side (for example, a browser or a mobile app) because it does not require using an API key. +#### If I choose to manually refresh the token, how will I know when to refresh the token? + +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. + +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). + #### How can I test the refresh token workflow? You can use the `refresh-optout@example.com` email address or the `+00000000002` phone number to test your token refresh workflow. Using either parameter value in a request always generates an identity response with a `refresh_token` that results in a logout response. diff --git a/docs/guides/integration-mobile-client-server.md b/docs/guides/integration-mobile-client-server.md index f854d8a06..c3e7e121f 100644 --- a/docs/guides/integration-mobile-client-server.md +++ b/docs/guides/integration-mobile-client-server.md @@ -93,7 +93,7 @@ If you want to manage token refresh on the server side and not the client/mobile - Call the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint. - Use one of the Publisher Client classes, in one of the UID2 server-side SDKs. These classes simplify the request into a single method call. - For instructions, see [SDK for Java, Publisher Server-Side Integration section](../sdks/sdk-ref-java.md#server-side-integration) or [SDK for Python, Publisher Server-Side Integration section](../sdks/sdk-ref-python.md#server-side-integration). + For instructions, see [SDK for Java, Usage for Publishers, Basic Usage Server-Side Integration section](../sdks/sdk-ref-java.md#basic-usage-server-side-integration) or [SDK for Python, Usage for Publishers, Server-Side Integration section](../sdks/sdk-ref-python.md#server-side-integration). Then, pass the newly refreshed `Identity` value to the mobile app by following the rest of this guide. diff --git a/docs/ref-info/ref-tokens.md b/docs/ref-info/ref-tokens.md index 258bf4865..337650335 100644 --- a/docs/ref-info/ref-tokens.md +++ b/docs/ref-info/ref-tokens.md @@ -6,6 +6,8 @@ sidebar_position: 06 --- import Link from '@docusaurus/Link'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # UID2 Tokens and Refresh Tokens @@ -49,6 +51,52 @@ 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)). The value of this field is a timestamp in UNIX time, expressed in milliseconds. +### Managing Token Refresh with an SDK + +An easy way to manage token refresh is to use one of the UID2 SDKs that have a function for the purpose: either the Java or Python SDK. + +Each of these SDKs includes a class, `Uid2PublisherClient`, that has a function to determine if a token refresh is needed. + +The following examples show how you could first check if the token can be refreshed and then check if refresh is needed, using one of these SDKs. If it's time to refresh, you can then call the refresh function to refresh the token. + + + + +1. Determine if the identity can be refreshed (that is, the refresh token hasn't expired): + + ```java + if (identity == null || !identity.isRefreshable()) { we must no longer use this identity (for example, remove this identity from the user's session) } + ``` + +1. Determine if a refresh is needed: + + ```java + if (identity.isDueForRefresh()) {..} + ``` + + + + +1. Determine if the identity can be refreshed (that is, the refresh token hasn't expired): + + ```py + if not identity or not identity.is_refreshable(): # we must no longer use this identity (for example, remove this identity from the user's session) + ``` + +1. Determine if a refresh is needed: + + ```py + if identity.is_due_for_refresh()): + ``` + + + + +Before using the code example, check the prerequisites and notes for the language you're using. For details, refer to the doc for the applicable SDK: + +- [SDK for Java, Usage for Publishers, Basic Usage Server-Side Integration section](../sdks/sdk-ref-java.md#basic-usage-server-side-integration) +- [SDK for Python, Usage for Publishers, Server-Side Integration section](../sdks/sdk-ref-python.md#server-side-integration) + ## FAQs There are some frequently asked questions relating to token refresh: see [FAQs for Publishers](../getting-started/gs-faqs.md#faqs-for-publishers). diff --git a/docs/sdks/sdk-ref-java.md b/docs/sdks/sdk-ref-java.md index 8af0f97c7..a88473076 100644 --- a/docs/sdks/sdk-ref-java.md +++ b/docs/sdks/sdk-ref-java.md @@ -155,7 +155,7 @@ If you're using the SDK's HTTP implementation, follow these steps. -#### Client-Server Integration +#### Basic Usage, Client-Server Integration If you're using client-server integration (see [Client-Server Integration Guide for JavaScript](../guides/integration-javascript-client-server.md)), follow this step: @@ -169,7 +169,7 @@ If you're using client-server integration (see [Client-Server Integration Guide If the user has opted out, this method returns `null`, so be sure to handle that case. ::: -#### Server-Side Integration +#### Basic Usage, Server-Side Integration If you're using server-side integration (see [Publisher Integration Guide, Server-Side](../guides/integration-publisher-server-side.md)), follow these steps: @@ -241,7 +241,7 @@ If you're using server-side integration (see [Publisher Integration Guide, Serve TokenGenerateResponse tokenGenerateResponse = publisherUid2Helper.createTokenGenerateResponse({response body}, envelope); ``` -#### Client-Server Integration +#### Advanced Usage, Client-Server Integration If you're using client-server integration (see [Client-Server Integration Guide for JavaScript](../guides/integration-javascript-client-server.md)), follow this step: @@ -255,7 +255,7 @@ If you're using client-server integration (see [Client-Server Integration Guide This method returns null if the user has opted out, so be sure to handle that case. ::: -#### Server-Side Integration +#### Advanced Usage, Server-Side Integration If you're using server-side integration (see [Publisher Integration Guide, Server-Side](../guides/integration-publisher-server-side.md)): diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-mobile-client-server.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-mobile-client-server.md index db140d364..6f2bff821 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-mobile-client-server.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-mobile-client-server.md @@ -93,7 +93,7 @@ Token Refresh を Server-Side で管理し、クライアント/モバイルサ - [POST /token/refresh](../endpoints/post-token-refresh.md) エンドポイントを呼び出します。 - UID2 Server-Side SDK のいずれかの Publisher Client クラスを使用します。これらのクラスは、リクエストを単一のメソッド呼び出しに簡素化します。 - 手順については、[SDK for Java, Publisher Server-Side Integration section](../sdks/sdk-ref-java.md#server-side-integration) または [SDK for Python, Publisher Server-Side Integration section](../sdks/sdk-ref-python.md#server-side-integration) を参照してください。 + 手順については、[SDK for Java, Usage for Publishers, Basic Usage Server-Side Integration section](../sdks/sdk-ref-java.md#basic-usage-server-side-integration) または [SDK for Python, Usage for Publishers, Server-Side Integration section](../sdks/sdk-ref-python.md#server-side-integration) を参照してください。 その後、このガイドの残りの部分に従って、新しくリフレッシュされた `Identity` 値をモバイルアプリに渡します。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/ref-tokens.md b/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/ref-tokens.md index 258bf4865..337650335 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/ref-tokens.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/ref-tokens.md @@ -6,6 +6,8 @@ sidebar_position: 06 --- import Link from '@docusaurus/Link'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # UID2 Tokens and Refresh Tokens @@ -49,6 +51,52 @@ 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)). The value of this field is a timestamp in UNIX time, expressed in milliseconds. +### Managing Token Refresh with an SDK + +An easy way to manage token refresh is to use one of the UID2 SDKs that have a function for the purpose: either the Java or Python SDK. + +Each of these SDKs includes a class, `Uid2PublisherClient`, that has a function to determine if a token refresh is needed. + +The following examples show how you could first check if the token can be refreshed and then check if refresh is needed, using one of these SDKs. If it's time to refresh, you can then call the refresh function to refresh the token. + + + + +1. Determine if the identity can be refreshed (that is, the refresh token hasn't expired): + + ```java + if (identity == null || !identity.isRefreshable()) { we must no longer use this identity (for example, remove this identity from the user's session) } + ``` + +1. Determine if a refresh is needed: + + ```java + if (identity.isDueForRefresh()) {..} + ``` + + + + +1. Determine if the identity can be refreshed (that is, the refresh token hasn't expired): + + ```py + if not identity or not identity.is_refreshable(): # we must no longer use this identity (for example, remove this identity from the user's session) + ``` + +1. Determine if a refresh is needed: + + ```py + if identity.is_due_for_refresh()): + ``` + + + + +Before using the code example, check the prerequisites and notes for the language you're using. For details, refer to the doc for the applicable SDK: + +- [SDK for Java, Usage for Publishers, Basic Usage Server-Side Integration section](../sdks/sdk-ref-java.md#basic-usage-server-side-integration) +- [SDK for Python, Usage for Publishers, Server-Side Integration section](../sdks/sdk-ref-python.md#server-side-integration) + ## FAQs There are some frequently asked questions relating to token refresh: see [FAQs for Publishers](../getting-started/gs-faqs.md#faqs-for-publishers). diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/sdks/sdk-ref-java.md b/i18n/ja/docusaurus-plugin-content-docs/current/sdks/sdk-ref-java.md index 698416f28..2e14d5821 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/sdks/sdk-ref-java.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/sdks/sdk-ref-java.md @@ -155,7 +155,7 @@ SDK の HTTP 実装を使用している場合は、以下の手順に従って -#### Client-Server Integration +#### Basic Usage, Client-Server Integration Standard Integration (Client and Server) を使用している場合([Client-Server Integration Guide for JavaScript](../guides/integration-javascript-client-server.md) を参照してください)、このステップに従ってください： @@ -169,7 +169,7 @@ Standard Integration (Client and Server) を使用している場合([Client-Ser ユーザーがオプトアウトした場合、このメソッドは `null` を返しますので、必ず処理してください。 ::: -#### Server-Side Integration +#### Basic Usage, Server-Side Integration Server-Side Integration ([Publisher Integration Guide, Server-Side](../guides/integration-publisher-server-side.md) を参照してください) を使用している場合は、以下の手順に従ってください: @@ -241,7 +241,7 @@ Server-Side Integration ([Publisher Integration Guide, Server-Side](../guides/in TokenGenerateResponse tokenGenerateResponse = publisherUid2Helper.createTokenGenerateResponse({response body}, envelope); ``` -#### Client-Server Integration +#### Advanced Usage, Client-Server Integration Standard Integration (client and server) を使用している場合 ([Client-Server Integration Guide for JavaScript](../guides/integration-javascript-client-server.md) を参照してください)、以下の手順に従ってください: @@ -255,7 +255,7 @@ Standard Integration (client and server) を使用している場合 ([Client-Se ユーザーがオプトアウトした場合、このメソッドは `null` を返しますので、必ず処理してください。 ::: -#### Server-Side Integration +#### Advanced Usage, Server-Side Integration Server-Side Integration ([Publisher Integration Guide, Server-Side](../guides/integration-publisher-server-side.md) を参照してください) を使用している場合は、以下の手順に従ってください: