Merge pull request #711 from IABTechLab/gwh-APIDOCS-1964-refresh-arti…

…cle-plus-code-example

Gwh apidocs 1964 refresh article plus code example

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 `[email protected]` 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.

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.
 

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.
+
+<Tabs groupId="language-selection">
+<TabItem value='java' label='Java'>
+
+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()) {..}
+    ```
+
+</TabItem>
+<TabItem value='py' label='Python'>
+
+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()):
+    ```
+
+</TabItem>
+</Tabs>
+
+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).

docs/sdks/sdk-ref-java.md

@@ -155,7 +155,7 @@ If you're using the SDK's HTTP implementation, follow these steps.
 
    <!-- uid2_euid_diff re legal basis for admonition above (first bullet not in UID2) -->
 
-#### 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)):
 

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` 値をモバイルアプリに渡します。
 

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.
+
+<Tabs groupId="language-selection">
+<TabItem value='java' label='Java'>
+
+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()) {..}
+    ```
+
+</TabItem>
+<TabItem value='py' label='Python'>
+
+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()):
+    ```
+
+</TabItem>
+</Tabs>
+
+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).

i18n/ja/docusaurus-plugin-content-docs/current/sdks/sdk-ref-java.md

@@ -155,7 +155,7 @@ SDK の HTTP 実装を使用している場合は、以下の手順に従って
 
  <!-- uid2_euid_diff re legal basis for admonition above (first bullet not in UID2) -->
 
-#### 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) を参照してください) を使用している場合は、以下の手順に従ってください: