diff --git a/docs/sdks/uid2-sdk-ref-java.md b/docs/sdks/uid2-sdk-ref-java.md index 99fe6b8e9..9cfd2995f 100644 --- a/docs/sdks/uid2-sdk-ref-java.md +++ b/docs/sdks/uid2-sdk-ref-java.md @@ -25,6 +25,7 @@ You can use the UID2 SDK for Java on the server side to facilitate the following - [Response Content](#response-content) - [Response Statuses](#response-statuses) * [FAQs](#faqs) +- [Usage for Publishers](#usage-for-publishers) * [Usage for UID2 Sharers](#usage-for-uid2-sharers) --> ## Overview @@ -66,7 +67,9 @@ The initialization function configures the parameters necessary for the SDK to a The interface allows you to decrypt UID2 advertising tokens and return the corresponding raw UID2. ->NOTE: When you use an SDK, you do not need to store or manage decryption keys. +:::note +When you use an SDK, you do not need to store or manage decryption keys. +::: If you're a DSP, for bidding, call the interface to decrypt a UID2 advertising token and return the UID2. For details on the bidding logic for handling user opt-outs, see [DSP Integration Guide](../guides/dsp-guide.md). @@ -102,6 +105,182 @@ Available information returned through the SDK is outlined in the following tabl | `KeysNotSynced` | The client has failed to synchronize keys from the UID2 service. | | `VersionNotSupported` | The client library does not support the version of the encrypted token. | +-------------------------------------------copy begin----------------------------------------------- + +Copy from: https://github.com/IABTechLab/uid2-client-java#usage-for-publishers + +## Usage for Publishers + +As a publisher, there are two ways to use the UID2 SDK for Java: +1. [**Basic Usage**](#basic-usage) is for publishers who want to use this SDK's HTTP implementation (synchronous [OkHttp](https://square.github.io/okhttp/)). +2. [**Advanced Usage**](#advanced-usage) is for publishers who prefer to use their own HTTP library. + +For an example application that demonstrates both Basic and Advanced usage, see [Java UID2 Integration Example](https://github.com/UnifiedID2/uid2-examples/tree/main/publisher/uid2-java-test-site#readme). + +### Basic Usage + +If you're using the SDK's HTTP implementation, follow these steps. + +1. Create an instance of `PublisherUid2Client` as an instance variable: + + ```java + private final PublisherUid2Client publisherUid2Client = new PublisherUid2Client(UID2_BASE_URL, UID2_API_KEY, UID2_SECRET_KEY); + ``` + +2. Call a function that takes the user's email address or phone number as input and generates a `TokenGenerateResponse` object. The following example uses an email address: + ```java + TokenGenerateResponse tokenGenerateResponse = publisherUid2Client.generateTokenResponse(TokenGenerateInput.fromEmail(emailAddress).doNotGenerateTokensForOptedOut()); + ``` + + :::important + - Be sure to call the POST /token/generate endpoint only when you have obtained legal basis to convert the user’s [directly identifying information (DII)](../ref-info/glossary-uid.md#gl-dii) to UID2 tokens for targeted advertising. + + - Always apply `doNotGenerateTokensForOptedOut()`. This applies a parameter similar to setting `optout_check=1` in the call to the POST /token/generate endpoint (see [Unencrypted JSON Body Parameters](../endpoints/post-token-generate.md#unencrypted-json-body-parameters)). + ::: + +#### Standard Integration + +If you're using standard integration (client and server) (see [JavaScript Standard Integration Guide](../guides/integration-javascript-standard.md)), follow this step: + +* Send this identity as a JSON string back to the client (to use in the [identity field](../sdks/client-side-identity.md#initopts-object-void)), using the following: + + ```java + tokenGenerateResponse.getIdentityJsonString() + ``` + + :::note + If the user has opted out, this method returns `null`, so be sure to handle that case. + ::: + +#### Server-Only Integration + +If you're using server-only integration (see [Publisher Integration Guide, Server-Only](../guides/custom-publisher-integration.md)), follow these steps: + +1. Store this identity as a JSON string in the user's session, using the `tokenGenerateResponse.getIdentityJsonString()` function. + + If the user has opted out, this method returns `null`, so be sure to handle that case. + +2. To retrieve the user's UID2 token, use the following: + + ```java + IdentityTokens identity = tokenGenerateResponse.getIdentity(); + if (identity != null) { String advertisingToken = identity.getAdvertisingToken(); } + ``` +3. When the user accesses another page, or on a timer, determine whether a refresh is needed: + 1. Retrieve the identity JSON string from the user's session, and then call the following function that takes the identity information as input and generates an `IdentityTokens` object: + + ```java + IdentityTokens identity = IdentityTokens.fromJsonString(identityJsonString); + ``` + 2. 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) } + ``` + 3. Determine if a refresh is needed: + + ```java + if (identity.isDueForRefresh()) {..} + ``` +4. If needed, refresh the token and associated values: + + ```java + TokenRefreshResponse tokenRefreshResponse = publisherUid2Client.refreshToken(identity); + ``` + +5. Store `tokenRefreshResponse.getIdentityJsonString()` in the user's session. + + If the user has opted out, this method returns `null`, indicating that the user's identity should be removed from the session. To confirm optout, you can use the `tokenRefreshResponse.isOptout()` function. + +### Advanced Usage + +1. Create an instance of `PublisherUid2Helper` as an instance variable: + + ```java + private final PublisherUid2Helper publisherUid2Helper = new PublisherUid2Helper(UID2_SECRET_KEY); + ``` +2. Call a function that takes the user's email address or phone number as input and creates a secure request data envelope. See [Encrypting requests](../getting-started/gs-encryption-decryption.md#encrypting-requests). The following example uses an email address: + + ```java + EnvelopeV2 envelope = publisherUid2Helper.createEnvelopeForTokenGenerateRequest(TokenGenerateInput.fromEmail(emailAddress).doNotGenerateTokensForOptedOut()); + ``` +3. Using an HTTP client library of your choice, post this envelope to the [POST token/generate](../endpoints/post-token-generate.md) endpoint, including headers and body: + 1. Headers: Depending on your HTTP library, this might look something like the following: + + `.putHeader("Authorization", "Bearer " + UID2_API_KEY)` + `.putHeader("X-UID2-Client-Version", PublisherUid2Helper.getVersionHeader())` + 2. Body: `envelope.getEnvelope()` + :::important + - Be sure to call the POST /token/generate endpoint only when you have obtained legal basis to convert the user’s [directly identifying information (DII)](../ref-info/glossary-uid.md#gl-dii) to UID2 tokens for targeted advertising. + + - Always apply `doNotGenerateTokensForOptedOut()`. This applies a parameter similar to setting `optout_check=1` in the call to the POST /token/generate endpoint (see [Unencrypted JSON Body Parameters](../endpoints/post-token-generate.md#unencrypted-json-body-parameters)). + ::: + +4. If the HTTP response status code is _not_ 200, see [Response Status Codes](../endpoints/post-token-generate.md#response-status-codes) to determine next steps. Otherwise, convert the UID2 identity response content into a `TokenGenerateResponse` object: + + ```java + TokenGenerateResponse tokenGenerateResponse = publisherUid2Helper.createTokenGenerateResponse({response body}, envelope); + ``` + +#### Standard Integration + +If you're using standard integration (client and server) (see [JavaScript Standard Integration Guide](../guides/integration-javascript-standard.md)), follow this step: + +* Send this identity as a JSON string back to the client (to use in the [identity field](../sdks/client-side-identity.md#initopts-object-void)) using the following: + + ```java + tokenGenerateResponse.getIdentityJsonString() + ``` + + :::caution + This method returns null if the user has opted out, so be sure to handle that case. + ::: + +#### Server-Only Integration + +If you're using server-only integration (see [Publisher Integration Guide, Server-Only](../guides/custom-publisher-integration.md)): + +1. Store this identity as a JSON string in the user's session, using: `tokenGenerateResponse.getIdentityJsonString()`. + + This method returns null if the user has opted out, so be sure to handle that case. +2. To retrieve the user's UID2 token, use: + + ```java + IdentityTokens identity = tokenGenerateResponse.getIdentity(); + if (identity != null) { String advertisingToken = identity.getAdvertisingToken(); } + ``` + +3. When the user accesses another page, or on a timer, determine whether a refresh is needed: + 1. Retrieve the identity JSON string from the user's session, and then call the following function that generates an `IdentityTokens` object: + + ```java + IdentityTokens identity = IdentityTokens.fromJsonString(identityJsonString); + ``` + 2. Determine whether 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) } + ``` + 3. Determine whether a refresh is needed: + + ```java + if (identity.isDueForRefresh()) {..} + ``` +4. If a refresh is needed, call the [POST token/refresh](../endpoints/post-token-refresh.md) endpoint, with the following: + 1. Headers: Depending on your HTTP library, this might look something like the following: + + `.putHeader("Authorization", "Bearer " + UID2_API_KEY)` + `.putHeader("X-UID2-Client-Version", PublisherUid2Helper.getVersionHeader())`. + 2. Body: `identity.getRefreshToken()` +5. If the refresh HTTP response status code is 200: + + ```java + TokenRefreshResponse tokenRefreshResponse = PublisherUid2Helper.createTokenRefreshResponse({response body}, identity); + ``` +6. Store `tokenRefreshResponse.getIdentityJsonString()` in the user's session. + + If the user has opted out, this method returns null, indicating that the user's identity should be removed from the session. To confirm optout, you can use the `tokenRefreshResponse.isOptout()` function. + ## Usage for UID2 Sharers A UID2 sharer is any participant that wants to share UID2s with another participant. Raw UID2s must be encrypted into UID2 tokens before sending them to another participant. For an example of usage, see [com.uid2.client.test.IntegrationExamples](https://github.com/IABTechLab/uid2-client-java/blob/master/src/test/java/com/uid2/client/test/IntegrationExamples.java) (`runSharingExample` method). @@ -110,12 +289,12 @@ A UID2 sharer is any participant that wants to share UID2s with another particip The following instructions provide an example of how you can implement sharing using the UID2 SDK for Java, either as a sender or a receiver. -1. Create an ```IUID2Client``` reference: +1. Create a `IUID2Client` reference: ```java IUID2Client client = UID2ClientFactory.create(UID2_BASE_URL, UID2_API_KEY, UID2_SECRET_KEY); ``` -2. Refresh once at startup, and then periodically. Recommended refresh interval is hourly: for details, see [Best Practices for Managing UID2 Tokens](../sharing/sharing-best-practices#key-refresh-cadence). +2. Refresh once at startup, and then periodically. Recommended refresh interval is hourly: for details, see [Best Practices for Managing UID2 Tokens](../sharing/sharing-best-practices.md#key-refresh-cadence). ```java client.refresh(); diff --git a/docs/sdks/uid2-sdk-ref-python.md b/docs/sdks/uid2-sdk-ref-python.md index 1ac995e79..c987072b0 100644 --- a/docs/sdks/uid2-sdk-ref-python.md +++ b/docs/sdks/uid2-sdk-ref-python.md @@ -14,7 +14,8 @@ You can use the UID2 SDK for Python on the server side to facilitate the followi - Encrypting raw UID2s to create UID2 tokens - Decrypting UID2 advertising tokens to access the raw UID2s - +--> ## Overview @@ -73,7 +75,7 @@ If you're a DSP, for bidding, call the interface to decrypt a UID2 advertising t The following is the decrypt method in Python: -```python +```py from uid2_client import Uid2ClientFactory client = Uid2ClientFactory.create('https://prod.uidapi.com', 'my-auth-token', 'my-secret-key') @@ -104,64 +106,23 @@ Available information returned through the SDK is outlined in the following tabl | `KeysNotSynced` | The client has failed to synchronize keys from the UID2 service. | | `VersionNotSupported` | The client library does not support the version of the encrypted token. | -## Usage for UID2 Sharers - -A UID2 sharer is any participant that wants to share UID2s with another participant. Raw UID2s must be encrypted into UID2 tokens before sending them to another participant. For an example of usage, see [examples/sample_sharing.py](https://github.com/IABTechLab/uid2-client-python/blob/master/examples/sample_sharing.py) script. - ->IMPORTANT: The UID2 token generated during this process is for sharing only—you cannot use it in the bid stream. There is a different workflow for generating tokens for the bid stream: see [Sharing in the Bid Stream](../sharing/sharing-bid-stream.md). - -The following instructions provide an example of how you can implement sharing using the UID2 SDK for Python, either as a sender or a receiver. - -1. Create a ```UID2Client``` reference: - - ```python - from uid2_client import Uid2ClientFactory - client = Uid2ClientFactory.create(base_url, auth_key, secret_key) - ``` - -2. Refresh once at startup, and then periodically (recommended refresh interval is hourly): - - ```python - client.refresh_keys() - ``` - -3. Senders: - 1. Call the `encrypt` function. Then, if encryption succeeded, send the UID2 token to the receiver: - - ```python - try: - encrypted_data = client.encrypt(raw_uid) - # send encrypted_data to receiver - except EncryptionError as err: - # check for failure reason - print(err) - ``` - -4. Receivers: - 1. Call the `decrypt` function. Then, if decryption succeeded, use the raw UID2: - - ```python - try: - result = client.decrypt(ad_token) - # use successfully decrypted result.uid2 - except EncryptionError as err: - # check for failure reason - print(err) - ``` - ## Usage for Publishers 1. Create an instance of Uid2PublisherClient: - - `client = Uid2PublisherClient(UID2_BASE_URL, UID2_API_KEY, UID2_SECRET_KEY)` - + ```py + client = Uid2PublisherClient(UID2_BASE_URL, UID2_API_KEY, UID2_SECRET_KEY) + ``` 2. Call a function that takes the user's email address or phone number as input and generates a `TokenGenerateResponse` object. The following example uses an email address: - `token_generate_response = client.generate_token(TokenGenerateInput.from_email(emailAddress).do_not_generate_tokens_for_opted_out())` + ```py + token_generate_response = client.generate_token(TokenGenerateInput.from_email(emailAddress).do_not_generate_tokens_for_opted_out()) + ``` - >IMPORTANT: Be sure to call this function only when you have obtained legal basis to convert the user’s [directly identifying information (DII)](../ref-info/glossary-uid.md#gl-dii) to UID2 tokens for targeted advertising. + :::important + Be sure to call this function only when you have obtained legal basis to convert the user’s [directly identifying information (DII)](../ref-info/glossary-uid.md#gl-dii) to UID2 tokens for targeted advertising. + ::: - >`do_not_generate_tokens_for_opted_out()` applies `optout_check=1` in the [POST /token/generate](../endpoints/post-token-generate.md) call. Without this, `optout_check` is omitted to maintain backwards compatibility. + `do_not_generate_tokens_for_opted_out()` applies `optout_check=1` in the [POST /token/generate](../endpoints/post-token-generate.md) call. Without this, `optout_check` is omitted to maintain backwards compatibility. ### Standard Integration @@ -169,9 +130,13 @@ If you're using standard integration (client and server) (see [JavaScript Standa * Send this identity as a JSON string back to the client (to use in the [identity field](../sdks/client-side-identity.md#initopts-object-void)) using the following: - `token_generate_response.get_identity_json_string()` - - Note: If the user has opted out, this method returns None, so be sure to handle that case. + ```py + token_generate_response.get_identity_json_string() + ``` + + :::note + If the user has opted out, this method returns None, so be sure to handle that case. + ::: ### Server-Only Integration @@ -182,7 +147,7 @@ If you're using server-only integration (see [Publisher Integration Guide, Serve If the user has opted out, this method returns `None`, so be sure to handle that case. 2. To retrieve the user's UID2 token, use the following: - ``` + ```py identity = token_generate_response.get_identity() if identity: advertising_token = identity.get_advertising_token() @@ -190,21 +155,77 @@ If you're using server-only integration (see [Publisher Integration Guide, Serve 3. Periodically check if the user's UID2 token should be refreshed. This can be done at fixed intervals using a timer, or can be done whenever the user accesses another page: 1. Retrieve the identity JSON string from the user's session, and then call the following function that takes the identity information as input and generates an `IdentityTokens` object: - `identity = IdentityTokens.from_json_string(identityJsonString)` + ```py + identity = IdentityTokens.from_json_string(identityJsonString) + ``` + 2. Determine if the identity can be refreshed (that is, the refresh token hasn't expired): - `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) ` + ```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) + ``` + 3. Determine if a refresh is needed: - `if identity.is_due_for_refresh()):` + ```py + if identity.is_due_for_refresh()): + ``` + 4. If needed, refresh the token and associated values: - `token_refresh_response = client.refresh_token(identity)` + ```py + token_refresh_response = client.refresh_token(identity)` + ``` 5. Store `token_refresh_response.get_identity_json_string()` in the user's session. If the user has opted out, this method returns `None`, indicating that the user's identity should be removed from the session. To confirm optout, you can use the `token_refresh_response.is_optout()` function. +## Usage for UID2 Sharers + +A UID2 sharer is any participant that wants to share UID2s with another participant. Raw UID2s must be encrypted into UID2 tokens before sending them to another participant. For an example of usage, see [examples/sample_sharing.py](https://github.com/IABTechLab/uid2-client-python/blob/master/examples/sample_sharing.py) script. + +>IMPORTANT: The UID2 token generated during this process is for sharing only—you cannot use it in the bid stream. There is a different workflow for generating tokens for the bid stream: see [Sharing in the Bid Stream](../sharing/sharing-bid-stream.md). + +The following instructions provide an example of how you can implement sharing using the UID2 SDK for Python, either as a sender or a receiver. + +1. Create a `UID2Client` reference: + + ```py + from uid2_client import Uid2ClientFactory + client = Uid2ClientFactory.create(base_url, auth_key, secret_key) + ``` + +2. Refresh once at startup, and then periodically (recommended refresh interval is hourly): + + ```py + client.refresh_keys() + ``` + +3. Senders: + 1. Call the `encrypt` function. Then, if encryption succeeded, send the UID2 token to the receiver: + + ```py + try: + encrypted_data = client.encrypt(raw_uid) + # send encrypted_data to receiver + except EncryptionError as err: + # check for failure reason + print(err) + ``` + +4. Receivers: + 1. Call the `decrypt` function. Then, if decryption succeeded, use the raw UID2: + + ```py + try: + result = client.decrypt(ad_token) + # use successfully decrypted result.uid2 + except EncryptionError as err: + # check for failure reason + print(err) + ``` + ## FAQs For a list of frequently asked questions for DSPs, see [FAQs for DSPs](../getting-started/gs-faqs.md#faqs-for-dsps).