diff --git a/docs/endpoints/post-identity-buckets.md b/docs/endpoints/post-identity-buckets.md index 1d6293a0d..54cf88332 100644 --- a/docs/endpoints/post-identity-buckets.md +++ b/docs/endpoints/post-identity-buckets.md @@ -23,7 +23,7 @@ Used by: This endpoint is used mainly by advertisers and data providers. For det | Path Parameter | Data Type | Attribute | Description | | :--- | :--- | :--- | :--- | -| `{environment}` | string | Required | Testing environment: `https://operator-integ.uidapi.com`
Production environment: `https://prod.uidapi.com`
For a full list, including regional operators, see [Environments](../getting-started/gs-environments.md). | +| `{environment}` | string | Required | Integration environment: `https://operator-integ.uidapi.com`
Production environment: `https://prod.uidapi.com`
For a full list, including regional operators, see [Environments](../getting-started/gs-environments.md). | >NOTE: The integration environment and the production environment require different API keys. diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index 6db6fc24b..02212f8d2 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -32,7 +32,7 @@ Here's what you need to know: | Path Parameter | Data Type | Attribute | Description | | :--- | :--- | :--- | :--- | -| `{environment}` | string | Required | Testing environment: `https://operator-integ.uidapi.com`
Production environment: `https://prod.uidapi.com`
For a full list, including regional operators, see [Environments](../getting-started/gs-environments.md). | +| `{environment}` | string | Required | Integration environment: `https://operator-integ.uidapi.com`
Production environment: `https://prod.uidapi.com`
For a full list, including regional operators, see [Environments](../getting-started/gs-environments.md). | >NOTE: The integration environment and the production environment require different API keys. diff --git a/docs/endpoints/post-token-validate.md b/docs/endpoints/post-token-validate.md index 48bb8e8e6..bb8bac45f 100644 --- a/docs/endpoints/post-token-validate.md +++ b/docs/endpoints/post-token-validate.md @@ -25,7 +25,7 @@ Used by: This endpoint is used mainly by publishers. | Path Parameter | Data Type | Attribute | Description | | :--- | :--- | :--- | :--- | -| `{environment}` | string | Required | Testing environment: `https://operator-integ.uidapi.com`
Production environment: `https://prod.uidapi.com`
For a full list, including regional operators, see [Environments](../getting-started/gs-environments.md). | +| `{environment}` | string | Required | Integration environment: `https://operator-integ.uidapi.com`
Production environment: `https://prod.uidapi.com`
For a full list, including regional operators, see [Environments](../getting-started/gs-environments.md). | >NOTE: The integration environment and the production environment require different API keys. diff --git a/docs/getting-started/gs-account-setup.md b/docs/getting-started/gs-account-setup.md index 03e14304e..a9d42e833 100644 --- a/docs/getting-started/gs-account-setup.md +++ b/docs/getting-started/gs-account-setup.md @@ -45,12 +45,20 @@ All participants will need to provide at least the following information: ### Client-Side Implementation for Publishers -If you're a publisher, and you determine that you want to implement UID2 so that tokens are generated on the client side, you'll also need to provide a list of **domain names** for your sites. This is a security measure, for client-side implementation only. +If you're a publisher publishing to [web](../overviews/overview-publishers.md#web-integrations) rather than [mobile](../overviews/overview-publishers.md#mobile-integrations), and you determine that you want to implement UID2 so that tokens are generated on the client side, you'll also need to provide a list of **domain names** for your sites. This is a security measure, for client-side implementation only. :::tip Only top-level (root-level) domains are required for account setup. For example, if you're going to implement UID2 to generate tokens on the client side on example.com, shop.example.com, and example.org, you only need to provide the domain names example.com and example.org. ::: +### Client-Side Mobile Integrations + +If you're publishing to [mobile apps](../guides/integration-mobile-client-side.md), you'll need to provide a list of app names for all the mobile apps that you'll be integrating with the UID2 mobile SDKs, including any of these values that apply: + +- Android Application ID +- iOS Bundle Identifier +- iOS App Store ID + ## Credentials When you've signed a contract for participating in UID2, you'll be issued with [UID2 credentials](gs-credentials.md) and other information for getting up and running with UID2. diff --git a/docs/guides/images/integration-mobile-client-server.png b/docs/guides/images/integration-mobile-client-server.png new file mode 100644 index 000000000..0b5c5736b Binary files /dev/null and b/docs/guides/images/integration-mobile-client-server.png differ diff --git a/docs/guides/images/resource/integration-mobile-client-server.pptx b/docs/guides/images/resource/integration-mobile-client-server.pptx new file mode 100644 index 000000000..c454f8b78 Binary files /dev/null and b/docs/guides/images/resource/integration-mobile-client-server.pptx differ diff --git a/docs/guides/integration-javascript-server-side.md b/docs/guides/integration-javascript-server-side.md index 801e09ea3..47d5eeb4a 100644 --- a/docs/guides/integration-javascript-server-side.md +++ b/docs/guides/integration-javascript-server-side.md @@ -13,7 +13,7 @@ import Link from '@docusaurus/Link'; # Server-Side Integration Guide for JavaScript -This guide is intended for publishers with web assets who want to generate identity tokens using UID2 for the RTB bidstream, while integrating directly with UID2 rather than UID2-enabled single-sign-on or identity providers. This requires server-side changes such as generating UID2 tokens on the server side and passing them to the publishers' web pages. If you want to integrate with UID2 via only client-side JavaScript changes, refer to [Client-Side Integration Guide for JavaScript](publisher-client-side.md) instead. +This guide is for publishers with web assets who want to generate identity tokens using UID2 for the RTB bidstream, while integrating directly with UID2 rather than UID2-enabled single-sign-on or identity providers. This requires server-side changes such as generating UID2 tokens on the server side and passing them to the publishers' web pages. If you want to integrate with UID2 via only client-side JavaScript changes, refer to [Client-Side Integration Guide for JavaScript](publisher-client-side.md) instead. For technical details about the SDK, see [UID2 SDK for JavaScript Reference Guide](../sdks/client-side-identity.md). diff --git a/docs/guides/integration-javascript.md b/docs/guides/integration-javascript.md index dad3fa21c..0640114f3 100644 --- a/docs/guides/integration-javascript.md +++ b/docs/guides/integration-javascript.md @@ -32,7 +32,7 @@ The options for integrating with UID2 using the UID2 SDK for JavaScript are summ | Scenario | Option | Integration Guide | | :--- | :--- | :--- | | You have access to DII on the client side and want to do front-end development only. | Client-side integration | [Client-Side Integration Guide for JavaScript](publisher-client-side.md) | -| You have access to DII on the server side and can do server-side development, or you are using a [Private Operator](../ref-info/glossary-uid.md#gl-private-operator). | Server-side integration | [Server-Side Integration Guide for JavaScript](integration-javascript-server-side.md) | +| You have access to DII on the server side and can do server-side development, or you are using a Private Operator. | Server-side integration | [Server-Side Integration Guide for JavaScript](integration-javascript-server-side.md) | ## Generating the UID2 Token diff --git a/docs/guides/integration-mobile-client-server.md b/docs/guides/integration-mobile-client-server.md new file mode 100644 index 000000000..6a83878a8 --- /dev/null +++ b/docs/guides/integration-mobile-client-server.md @@ -0,0 +1,359 @@ +--- +title: UID2 Client-Server Integration Guide for Mobile +sidebar_label: Client-Server Integration for Mobile +pagination_label: UID2 Client-Server Integration Guide for Mobile +description: Setting up a mobile integration with token generate on server and refresh on client. +hide_table_of_contents: false +sidebar_position: 04 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Link from '@docusaurus/Link'; +import ReduceLatency from '/docs/snippets/_sdk-reduce-latency.mdx'; +import EnableLogging from '/docs/snippets/_mobile-docs-enable-logging.mdx'; +import GMAIMA_Plugins from '/docs/snippets/_mobile_docs_gmaima-plugin-gss.mdx'; + +# UID2 Client-Server Integration Guide for Mobile + +This guide is for mobile app publishers who want to integrate with UID2 by generating UID2 tokens server-side via a Public Operator or Private Operator and then passing the tokens and user identities into their mobile apps, which will in turn pass the tokens for bidstream use.   + +This is called Client-Server Integration because some integration steps are client-side and some are server-side. + +If you want to integrate with UID2 via client-side only changes (that is, all integration changes required are within the mobile apps), refer to the [UID2 Client-Side Integration Guide for Mobile](integration-mobile-client-side.md) instead. + +This page provides a high-level overview of integration steps and links to additional documentation. + +UID2 provides mobile SDKs for [Android](../sdks/uid2-sdk-ref-android.md) and [iOS](../sdks/uid2-sdk-ref-ios.md). Each SDK has the following features: + +- Takes in a UID2 identity (a UID2 token and associated values) and persists it in local file storage. +- Automatically refreshes UID2 tokens. + +:::note +This guide uses the group term **UID2 mobile SDKs** to include both the UID2 SDK for Android and the UID2 SDK for iOS. +::: + +You'll need to complete the following steps: + +1. [Complete the UID2 account setup](#complete-the-uid2-account-setup). +2. [Implement server-side token generation](#implement-server-side-token-generation). +3. [Add the UID2 mobile SDK to your mobile app](#add-the-uid2-mobile-sdk-to-your-mobile-app). +4. [Configure the UID2 mobile SDK](#configure-the-uid2-mobile-sdk). +5. [Check that the token was successfully generated and then pass it for bidstream use](#pass-generated-token-for-bidstream-use). +6. [Optionally, integrate the UID2 GMA/IMA Plugin for GAM Secure Signal integration](#optional-uid2-gmaima-plugin-for-gam-secure-signal-integration). + + + + +## Mobile SDK Version + +This guide provides instructions for using version 1.2.0 or higher of either of these UID2 mobile SDKs: + +- UID2 SDK for Android +- UID2 SDK for iOS + +For instructions for installing the correct SDK/version into your mobile app, see [Add the UID2 Mobile SDK to Your Mobile App](#add-the-uid2-mobile-sdk-to-your-mobile-app). + + +## Complete the UID2 Account Setup + +To set up your account, follow the steps described in [Account Setup](../getting-started/gs-account-setup.md). + +When account setup is complete, you'll receive your unique API key and client secret. These values are unique to you, and it's important to keep them secure. For details, see [API Key and Client Secret](../getting-started/gs-credentials.md#api-key-and-client-secret). + +## Client-Server Mobile Integration Data Flow Overview + +The following diagram shows the data flow that the publisher must implement for UID2 client-server mobile integration. + +This example uses the [UID2 SDK for Android](../sdks/uid2-sdk-ref-android.md) in the client-side mobile app and the [UID2 SDK for Java](../sdks/uid2-sdk-ref-java.md) on the server side. + +![Mobile Client-Server Integration Example](images/integration-mobile-client-server.png) + + + +## Implement Server-Side Token Generation + +The first step of UID2 integration is to be able to generate the UID2 token on your server. Then, you can pass the token into your mobile apps for sending to the RTB bidstream. + +There are two approaches to generating UID2 tokens on the server side by providing directly identifying information (DII) (email address or phone number): + +- Integration with an SDK +- Direct integration to API endpoints + +Options are summarized in the following table. + +| Integration Solution  | Generate Token | Refresh Token | +| :--- | :--- | :--- | +| [UID2 SDK for Java](../sdks/uid2-sdk-ref-java.md) | ✅ | ✅ | +| [UID2 SDK for Python](../sdks/uid2-sdk-ref-python.md) | ✅ | ✅ | +| [Direct integration (API endpoints with custom code)](../endpoints/post-token-generate.md) | ✅ | ✅ | + +Whatever integration option you choose to generate the identity (UID2 token and associated values), you'll need to implement one of the following: + +- Call the [POST /token/generate](../endpoints/post-token-generate.md) endpoint. + + The identity output that you need for the rest of this guide is the content inside the body section of a successful endpoint response. For an example, see [Successful Response](../endpoints/post-token-generate.md#successful-response). + +- 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 [UID2 SDK for Java, Publisher Basic Usage](../sdks/uid2-sdk-ref-java.md#basic-usage) or [UID2 SDK for Python, Usage for Publishers](../sdks/uid2-sdk-ref-python.md#usage-for-publishers). + + If you're using an SDK option, the `Identity` response that you need for the rest of this guide is the output of the applicable method, as follows: + + + + + ```java + tokenGenerateResponse.getIdentityJsonString() + ``` + + + + + ```py + token_generate_response.get_identity_json_string() + ``` + + + + +:::important +The endpoint and SDK API returns opt-out status if the DII you are generating the token for has been opted out of UID2. If this happens, save the information and do not call the token generation endpoint for the same DII again.  +::: + +You will need to pass the `Identity` response into the mobile app: see [Configure the UID2 Mobile SDK](#configure-the-uid2-mobile-sdk). + +:::warning +For security reasons, the API key and secret used in token generation must be called server-side. Do not store these values inside a mobile app. For details, see [Security of API Key and Client Secret](../getting-started/gs-credentials.md#security-of-api-key-and-client-secret). +::: + +## 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. + +You might decide to do server-side token refresh if you want to keep your changes in the mobile apps as simple as possible. + +If you want to manage token refresh on the server side and not the client/mobile side, you can do so using one of the following: + +- 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 [UID2 SDK for Java, Publisher Server-Only Integration section](../sdks/uid2-sdk-ref-java.md#server-only-integration) or [UID2 SDK for Python, Publisher Server-Only Integration section](../sdks/uid2-sdk-ref-python.md#server-only-integration). + +Then, pass the newly refreshed `Identity` value to the mobile app by following the rest of this guide. + +## Add the UID2 Mobile SDK to Your Mobile App + +For installation instructions, refer to one of the following: + +- [UID2 SDK for Android Reference Guide](../sdks/uid2-sdk-ref-android.md) +- [UID2 SDK for iOS Reference Guide](../sdks/uid2-sdk-ref-ios.md) + +At this point, you are ready to use the UID2 Identity generated server-side in the mobile SDK. + +### Using the UID2 Integration Environment + +By default, the SDK is configured to work with the UID2 production environment: `https://prod.uidapi.com`. If you want to use the UID2 integration environment instead, provide the following URL in your call to UID2Manager initialization: + + + + +```js +UID2Manager.init( + context = this, + serverUrl = "https://operator-integ.uidapi.com" +) +``` + + + + +```js +// Must be set before UID2Manager.shared is accessed +UID2Settings.shared.environment = .custom( + url: URL(string: "https://operator-integ.uidapi.com")! +) +``` + + + + +:::note +Bear in mind the following differences between environments: +- Tokens from the UID2 integration environment are not valid for passing to the bidstream. +- You'll have a different set of API key and client secret values for each environment (integration and production). Be sure to use the correct values for each environment. +::: + +### Optional: Reduce Latency by Setting the API Base URL for the Production Environment + + + +To specify a different UID2 server, you can change it in the `init` call: + + + + +```js +UID2Manager.init( + context = this, + serverUrl = "https://global.prod.uidapi.com" +) +``` + + + + +```js +UID2Settings.shared.environment = .singapore +// or +UID2Settings.shared.environment = .custom( + url: URL(string: "https://global.prod.uidapi.com")! +) +``` + + + + +## Configure the UID2 Mobile SDK + +After you've instantiated `UID2Manager` correctly in your mobile app, you'll need to pass a UID2 identity generated server-side (see [Implement server-side token generation](#implement-server-side-token-generation)), and then pass it into the mobile app using the `setIdentity` method, as shown in the following: + + + + +```js +UID2Manager.getInstance().setIdentity() +``` + + + + +```js +UID2Manager.shared.setIdentity() +``` + + + + +## Token Storage + +After you call the `setIdentity` method, the UID2 identity is persisted in local file storage. + +:::warning +The format of the file stored in the local file storage, or the filename itself, could change without notice. We recommend that you do not read or update the file directly. +::: + +## Pass Generated Token for Bidstream Use + +To retrieve the token, in your mobile app, call the following: + + + + +```js +UID2Manager.getInstance().getAdvertisingToken() +``` + + + + +```js +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== +``` + +You can use this identity to pass downstream for sending in the RTB bidstream. + +If the `getAdvertisingToken()` method call returns `null`, there was no identity or valid token generated. Some possible reasons for this, and some things you could do to troubleshoot, are as follows: + +- The identity is invalid. In this scenario there are a couple of options: + - Check to see whether there are any errors from the previous `setIdentity()` call. + - Check the status of the identity, using `UID2Manager.getInstance().getIdentityStatus()` for Android or `UID2Manager.shared.identityStatus` for iOS. +- You could enable logging to get more information: see [Enable Logging](#enable-logging). +- The advertising token inside the UID2 identity has expired, and the refresh token has also expired, so the SDK cannot refresh the token. + +If there is no identity, follow the instructions in [Implement Server-Side Token Generation](#implement-server-side-token-generation) again, generate a new identity, and pass the result into your mobile app's UID2Manager again. + +## When to Pass a new UID2 Identity/Token into the SDK + +The best way to determine whether a new UID2 identity is required by the UID2 SDK again is to call the `getAdvertisingToken()` method in all cases: + + + + +```js +UID2Manager.getInstance().getAdvertisingToken() +``` + + + + +```js +UID2Manager.shared.getAdvertisingToken() +``` + + + + +On startup/resumption of the app, if `getAdvertisingToken()` returns `null`, it is time to generate new identity on the server by following the instructions in [Implement Server-Side Token Generation](#implement-server-side-token-generation). Then, pass the result into the mobile app’s UID2Manager again: see [Configure the UID2 mobile SDK](#configure-the-uid2-mobile-sdk). + +## Enable Logging + + + +## Enable Automatic Token Refresh in Mobile App/Client Side + +By default, after a valid UID2 identity has been passed into the UID2Manager, it performs automatic token refresh. If for any reason token refresh was disabled, you can enable it with the following method call: + + + + +**Android Java**: + +```java +UID2Manager.getInstance().setAutomaticRefreshEnabled(false) +``` + +**Android Kotlin**: + +```kotlin +UID2Manager.getInstance().automaticRefreshEnabled = false +``` + + + + +```js +UID2Manager.shared.automaticRefreshEnabled = false +``` + + + + +## Optional: UID2 GMA/IMA Plugin for GAM Secure Signal integration + + diff --git a/docs/guides/integration-mobile-client-side.md b/docs/guides/integration-mobile-client-side.md new file mode 100644 index 000000000..897bbe86c --- /dev/null +++ b/docs/guides/integration-mobile-client-side.md @@ -0,0 +1,703 @@ +--- +title: UID2 Client-Side Integration Guide for Mobile +sidebar_label: Client-Side Integration for Mobile +pagination_label: UID2 Client-Side Integration Guide for Mobile +description: Setting up a mobile integration with token generate and refresh both on the client side. +hide_table_of_contents: false +sidebar_position: 04 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Link from '@docusaurus/Link'; +import ReduceLatency from '/docs/snippets/_sdk-reduce-latency.mdx'; +import GMAIMA_Plugins from '/docs/snippets/_mobile_docs_gmaima-plugin-gss.mdx'; +import EnableLogging from '/docs/snippets/_mobile-docs-enable-logging.mdx'; + +# UID2 Client-Side Integration Guide for Mobile + +This guide is for mobile app publishers who want to integrate with UID2 with changes only within their mobile app. + +These instructions do not apply to publishers who want to use a Private Operator, or who want to generate tokens server-side. Those publishers should follow the [Client-Server Integration Guide for Mobile](integration-mobile-client-server.md). + +This page provides a high-level overview of integration steps and links to additional documentation. + +UID2 provides mobile SDKs for [Android](../sdks/uid2-sdk-ref-android.md) and [iOS](../sdks/uid2-sdk-ref-ios.md). Each SDK has the following features: + +- Generates a UID2 identity (a UID2 token and associated values) and persists it in local file storage. +- Automatically refreshes UID2 tokens. + +:::note +This guide uses the group term **UID2 mobile SDKs** to include both the UID2 SDK for Android and the UID2 SDK for iOS. +::: + +To integrate with UID2 client-side, you'll need to complete the following steps: + +1. [Complete the UID2 account setup](#complete-the-uid2-account-setup). + +1. [Add the UID2 mobile SDK to your mobile app](#add-the-uid2-mobile-sdk-to-your-mobile-app). + +1. [Configure the UID2 mobile SDK](#configure-the-uid2-mobile-sdk). + +1. [Check that the token was successfully generated and then pass it for bidstream use](#pass-generated-token-for-bidstream-use). + +1. [Optionally, integrate the UID2 GMA/IMA Plugin for GAM Secure Signal integration](#optional-uid2-gmaima-plugin-for-gam-secure-signal-integration). + + + +## Mobile SDK Version + +This guide provides instructions for using version 1.2.0 or higher of either of these UID2 mobile SDKs: + +- UID2 SDK for Android +- UID2 SDK for iOS + +For instructions for installing the correct SDK/version into your mobile app, see [Add the UID2 Mobile SDK to Your Mobile App](#add-the-uid2-mobile-sdk-to-your-mobile-app). + +## Client-Side Integration Example + +For an example of how to configure a UID2 mobile SDK, and how to generate tokens using client-side integration for mobile, you can try out the UID2 development app. + +Follow the applicable instructions, for Android or iOS: + + + + +1. Check out the main branch of the [UID2 SDK for Android source code repository on GitHub](https://github.com/IABTechLab/uid2-android-sdk/tree/main). +1. In Android Studio (Jellyfish/v2023.3.1 or whichever future version supports the Android Gradle Plugin version required by the UID2 SDK for Android release at the time), open the directory that you checked out. +1. Run the **dev-app** app. +1. When you've started the app, make sure that the **Client Side** checkbox is checked. +1. Enter an email or phone number, and then click the arrow to the right. + + + + +1. Check out the [main branch of the UID2 SDK For iOS source code repository on GitHub](https://github.com/IABTechLab/uid2-ios-sdk/tree/main). +1. In Xcode, open this project file: + + ```js + Development/UID2SDKDevelopmentApp/UID2SDKDevelopmentApp.xcodeproj + ``` +1. Run the **UID2SDKDevelopmentApp** app scheme. +1. When you've started the app, make sure that the **Client Side** checkbox is checked. +1. Enter an email or phone number, and then click the arrow to the right. + + + + +Behind the scenes, the development app makes the following UID2 SDK API call. This call sends a request to the UID2 service to generate an identity (a UID2 token and associated values) for the email/phone input: + + + + +```js +UID2Manager.getInstance().generateIdentity( + identityRequest: IdentityRequest, + subscriptionId: String, + publicKey: String, + onResult: (GenerateIdentityResult) -> Unit +) +``` + + + + +```js +UID2Manager.shared.generateIdentity( + _ identity: IdentityType, + subscriptionID: String, + serverPublicKey: String, + appName: String? = nil +) +``` + + + + +When the API call is successful, the app displays the resulting identity and persists it inside the `UID2Manager` class. + +The identity includes the generated UID2 advertising token value, which you can retrieve using the `getAdvertisingToken()` method call: + + + + +```js +UID2Manager.getInstance().getAdvertisingToken() +``` + + + + +```js +UID2Manager.shared.getAdvertisingToken() +``` + + + + +This method call returns the value that you need to make an ad request: see [Pass Generated Token for Bidstream Use](#pass-generated-token-for-bidstream-use). + +### Testing With Your Own Configuration + +By default, the development app uses default values for Subscription ID and public key, which are stored in the following object: + + + + +```js +com.uid2.dev.ui.MainScreenViewModel.Companion +``` + + + + +```js +RootViewModel +``` + + + + +By default, the development app is configured to connect to the UID2 integration environment, as specified in the following Android method call/iOS file: + + + + +```js +com.uid2.UID2Manager.Companion#init +``` + + + + +```js +see UID2SDKDevelopmentApp/UID2SDKDevelopmentApp/Info.plist +``` + + + + +If necessary, you can also change the default Subscription ID and public key to values assigned to you, and connect to the UID2 Production environment. For details, see [Optional: Reduce Latency by Setting the API Base URL for the Production Environment](#optional-reduce-latency-by-setting-the-api-base-url-for-the-production-environment). + +## Complete the UID2 Account Setup + +To set up your account, follow the steps described in [Account Setup](../getting-started/gs-account-setup.md). As part of the account setup process, you'll need to provide a list of app names for all the mobile apps that you'll be integrating with the UID2 mobile SDKs, including any of these values that apply: + +- Android Application ID +- iOS Bundle Identifier +- iOS App Store ID + +When account setup is complete, you'll receive a [Subscription ID and public key](../getting-started/gs-credentials.md#subscription-id-and-public-key). These values are unique to you, and you'll use them when you [configure the UID2 mobile SDK](#configure-the-uid2-mobile-sdk). + +## Add the UID2 Mobile SDK to Your Mobile App + +To add the mobile SDK to your app, follow the applicable documentation: + +- [UID2 SDK for Android Reference Guide](../sdks/uid2-sdk-ref-android.md) +- [UID2 SDK for iOS Reference Guide](../sdks/uid2-sdk-ref-ios.md) + +At this point, you are ready to start generating UID2 tokens using the SDK. + +### Using the UID2 Integration Environment + +By default, the SDK is configured to work with the UID2 production environment: `https://prod.uidapi.com`. If you want to use the integration environment instead, provide the following URL in your call to initialize `UID2Manager`: + + + + +```js +UID2Manager.init( + context = this, + serverUrl = "https://operator-integ.uidapi.com" +) +``` + + + + +```js +// Must be set before UID2Manager.shared is accessed +UID2Settings.shared.environment = .custom( + url: URL(string: "https://operator-integ.uidapi.com")! +) +``` + + + + +:::note +Bear in mind the following differences between environments: +- Tokens from the UID2 integration environment are not valid for passing to the bidstream. +- You'll have a different set of Subscription ID and public key values for each environment (integration and production). Be sure to use the correct values for each environment. +::: + +### Optional: Reduce Latency by Setting the API Base URL for the Production Environment + + + +To specify a different UID2 server, you can make config changes, as shown in the following examples: + + + + +```js +UID2Manager.init( + context = this, + serverUrl = "https://global.prod.uidapi.com" +) +``` + + + + +```js +// Must be set before UID2Manager.shared is accessed +UID2Settings.shared.environment = .custom( + url: URL(string: "https://global.prod.uidapi.com")! +) +// or use a named environment +UID2Settings.shared.environment = .sydney +``` + + + + +## Configure the UID2 Mobile SDK + +UID2 provides the publisher with the following values, which are needed for generating the UID2 token on the client side: + +- Subscription ID +- Public key + +You'll have one set of these values for your Integration environment, and a separate set for your production environment. + +To configure the SDK, you must pass in the Subscription ID and public key that you received during account setup, as well as the user’s hashed or unhashed directly identifying information (DII) (email address or phone number), into the following method call: + + + + +```js +UID2Manager.getInstance().generateIdentity( + identityRequest: IdentityRequest, + subscriptionId: String, + publicKey: String, + onResult: (GenerateIdentityResult) -> Unit +) +``` + + + + +```js +UID2Manager.shared.generateIdentity( + _ identity: IdentityType, + subscriptionID: String, + serverPublicKey: String, + appName: String? = nil +) +``` + + + + +Once it's configured, the UID2 mobile SDK does the following: + +- Generates a UID2 identity, including token, for the user. +- Stores the token locally on the user’s device. +- Automatically refreshes the token as required while your app is open. + +:::tip +You can pass the user’s DII to the UID2 mobile SDK either hashed or unhashed. If you pass the DII unhashed, the SDK hashes it for you. If you want to pass the DII to the SDK already hashed, you must normalize it before hashing. For details, see [Normalization and Encoding](../getting-started/gs-normalization-encoding.md). +::: + +### Format Examples for DII + +The SDK encrypts the hashed DII before sending it to the UID2 service. + +You can invoke the `generateIdentity` method using any of the four accepted formats for DII, for any specific user. The DII format might vary per user, but you can only send one value per user. + +The following examples demonstrate the different ways that you can configure the UID2 mobile SDK and list the requirements for the DII passed into the SDK: + +- Email, Unhashed +- Email, Normalized and Hashed +- Phone Number, Unhashed +- Phone Number, Normalized and Hashed + +If the `generateIdentity` method is called multiple times, the UID2 mobile SDK uses the most recent configuration values. + + + + +The following example configures the UID2 mobile SDK with an email address. + + + + +```js +UID2Manager.getInstance().generateIdentity( + IdentityRequest.Email("test@example.com"), + subscriptionId, + publicKey, +) { result -> + when (result) { + is Error -> ... + is Success -> ... + } +} +``` + + + + +```js +struct InvalidEmailError: Error, LocalizedError { + var errorDescription: String = "Invalid email address" +} +Task { + do { + guard let normalizedEmail = IdentityType.NormalizedEmail(string: "test@example.com") else { + throw InvalidEmailError() // email is invalid and cannot be normalized, handle error + } + try await UID2Manager.shared.generateIdentity( + .email(normalizedEmail), + subscriptionID: subscriptionID, + serverPublicKey: serverPublicKeyString + ) + } catch { + // read `error` object for troubleshooting or enable logging to view it in logs + } +} +``` + + + + +In this scenario: + +- No normalization or hashing is required by the publisher. +- The UID2 mobile SDK normalizes and hashes the email address before sending the encrypted hash to the UID2 service. + + + + +The following example configures the UID2 SDK with a hashed email address. + + + + +```js +UID2Manager.getInstance().generateIdentity( + IdentityRequest.EmailHash( + “eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc=” + ), + subscriptionId, + publicKey, +) { result -> + when (result) { + is Error -> ... + is Success -> ... + } +} +``` + + + + +```js +Task { + do { + try await UID2Manager.shared.generateIdentity( + .emailHash("eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc="), + subscriptionID: subscriptionID, + serverPublicKey: serverPublicKeyString + ) + } catch { + // read `error` object for troubleshooting or enable logging to view it in logs + } +} +``` + + + + +In this scenario: + +- The publisher is responsible for normalizing and hashing the email address. For details, see [Email Address Normalization](../getting-started/gs-normalization-encoding.md#email-address-normalization). +- The UID2 mobile SDK encrypts the hashed DII before sending it to the UID2 service. + + + + +The following example configures the UID2 mobile SDK with a phone number. + + + + +```js +UID2Manager.getInstance().generateIdentity( + IdentityRequest.Phone(“+1111111111”), + subscriptionId, + publicKey, +) { result -> + when (result) { + is Error -> ... + is Success -> ... + } +} +``` + + + + +```js +struct InvalidPhoneError: Error, LocalizedError { + var errorDescription: String = "Invalid phone number" +} +Task { + do { + guard let normalizedPhone = IdentityType.NormalizedPhone(normalized: "+1111111111") else { + throw InvalidPhoneError() // Phone number is not normalized according to ITU E.164. + } + try await UID2Manager.shared.generateIdentity( + .phone(normalizedPhone), + subscriptionID: subscriptionID, + serverPublicKey: serverPublicKeyString + ) + } catch { + // read `error` object for troubleshooting or enable logging to view it in logs + } +} +``` + + + + +In this scenario: + +- The publisher is responsible for normalizing the phone number. For details, see [Phone Number Normalization](../getting-started/gs-normalization-encoding.md#phone-number-normalization). +- The UID2 mobile SDK hashes the phone number before sending the encrypted hash to the UID2 service. + + + + +The following example configures the UID2 mobile SDK with a hashed phone number. + + + + +```js +UID2Manager.getInstance().generateIdentity( + IdentityRequest.PhoneHash( + “eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc=” + ), + subscriptionId, + publicKey, +) { result -> + when (result) { + is Error -> ... + is Success -> ... + } +} +``` + + + + +```js +Task { + do { + try await UID2Manager.shared.generateIdentity( + .phoneHash("eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc="), + subscriptionID: subscriptionID, + serverPublicKey: serverPublicKeyString + ) + } catch { + // read `error` object for troubleshooting or enable logging to view it in logs + } +} +``` + + + + +In this scenario: + +- The publisher is responsible for normalizing and hashing the phone number. For details, see [Phone Number Hash Encoding](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding). +- The UID2 mobile SDK encrypts the hashed DII before sending it to the UID2 service. + + + + +## Token Storage and Refresh + +After a call to the applicable method listed in [Format Examples for DII](#format-examples-for-dii) is successful, an identity is generated and stored in local file storage. The UID2 mobile SDK refreshes the UID2 token periodically. + +:::warning +The format of the file stored in the local file storage, or the filename itself, could change without notice. We recommend that you do not read or update the file directly. +::: + +## Pass Generated Token for Bidstream Use + +In your mobile app, if the call to `generateIdentity` was successful, it returned an identity. The next step is to call the `getAdvertisingToken()` method, as follows: + + + + +```js +UID2Manager.getInstance().getAdvertisingToken() +``` + + + + +```js +UID2Manager.shared.getAdvertisingToken() +``` + + + + +If successful, this method call returns the token—a non-null string object such as the following: + +```js +AgAAAQFt3aNLXKXEyWS8Tpezcymk1Acv3n+ClOHLdAgqR0kt0Y+pQWSOVaW0tsKZI4FOv9K/rZH9+c4lpm2DBpmFJqjdF6FAaAzva5vxDIX/67UOspsYtiwxH73zU7Fj8PhVf1JcpsxUHRHzuk3vHF+ODrM13A8NAVlO1p0Wkb+cccIIhQ== +``` + +You can use this token to pass downstream for sending in the RTB bidstream. + +If the `getAdvertisingToken()` method call returns `null`, there was no identity or valid token generated. + +Some possible reasons for this, and some things you could do to troubleshoot, are as follows: + +- The identity is invalid. In this scenario there are a couple of options: + - Check to see whether there are any errors from the previous `generateIdentity` call. + - Check the status of the identity, using `UID2Manager.getInstance().getIdentityStatus()` for Android or `UID2Manager.shared.identityStatus` for iOS. + + It's possible that the DII has been opted out of UID2: for details, see [When to Pass DII into the SDK](#when-to-pass-dii-into-the-sdk). +- You could enable logging to get more information: see [Enable Logging](#enable-logging). +- The advertising token inside the UID2 identity has expired, and the refresh token has also expired, so the SDK cannot refresh the token. + +If there is no identity, you'll need to call the `generateIdentity` method again: see [Configure the UID2 Mobile SDK](#configure-the-uid2-mobile-sdk). + +For more information, see [When to Pass DII into the SDK](#when-to-pass-dii-into-the-sdk) (next section). + +## When to Pass DII into the SDK + +The first time a new user opens the app, no UID2 identity exists. You'll need to call the `generateIdentity` method, with the DII, to start the token generation: + + + + +```js +UID2Manager.getInstance().generateIdentity( + identityRequest: IdentityRequest, + subscriptionId: String, + publicKey: String, + onResult: (GenerateIdentityResult) -> Unit +) +``` + + + + +```js +UID2Manager.shared.generateIdentity( + _ identity: IdentityType, + subscriptionID: String, + serverPublicKey: String, + appName: String? = nil +) +``` + + + + +When this method call completes successfully, the advertising token (UID2 token) is available for you to send to the bidstream. + +If the UID2 identity stored in local file storage has expired and cannot be refreshed, you must call the `generateIdentity` method again to generate a new identity and get the resulting UID2 token. The only exception is when the response to the following Android method/iOS object indicates that the DII was opted out of UID2: + + + + +```js +UID2Manager.getInstance().getIdentityStatus() +``` + + + + +```js +UID2Manager.shared.identityStatus +``` + + + + +A response status of `OPT_OUT` for Android, or `optOut` for iOS, indicates that the DII has been opted out of UID2 and no identity/token should be generated for it. You might want to avoid making repeated `generateIdentity` calls: if the DII has a status of opted out, the UID2 token is not generated. + +The best way to determine if DII is required by the UID2 mobile SDKs is to always call the `getAdvertisingToken()` method when the app starts up or resumes: + + + + +```js +UID2Manager.getInstance().getAdvertisingToken() +``` + + + + +```js +UID2Manager.shared.getAdvertisingToken() +``` + + + + +If `getAdvertisingToken()` returns null, and the identity status is not `OPT_OUT`/`optOut`, you'll need to generate a new token. To do this, pass the DII into the `generateIdentity` method again. For details, see [Configure the UID2 mobile SDK](#configure-the-uid2-mobile-sdk). + + + +## Enable Logging + + + +## Optional: UID2 GMA/IMA Plugin for GAM Secure Signal integration + + diff --git a/docs/guides/integration-mobile-overview.md b/docs/guides/integration-mobile-overview.md new file mode 100644 index 000000000..798b99ae6 --- /dev/null +++ b/docs/guides/integration-mobile-overview.md @@ -0,0 +1,65 @@ +--- +title: UID2 Mobile Integration Overview for Android and iOS +sidebar_label: Integration Overview for Mobile +pagination_label: Mobile Integration Overview for Android and iOS +description: Overview of options for UID2 mobile integration. +hide_table_of_contents: false +sidebar_position: 04 +displayed_sidebar: sidebarPublishers +--- + +import Link from '@docusaurus/Link'; + +# UID2 Mobile Integration Overview for Android and iOS + +This guide is an overview of integration options for mobile app publishers who want to integrate with UID2 using the UID2 SDK for Android or the UID2 SDK for iOS. + +:::note +This guide uses the group term **UID2 mobile SDKs** to include both the UID2 SDK for Android and the UID2 SDK for iOS. +::: + + + +## Introduction + +UID2 provides SDKs for Android/iOS that support the following: + +- Generating the UID2 token +- Refreshing the UID2 token +- Storing the UID2 token + +For additional flexibility, UID2 also provides alternative methods for some of the features and complementary products, such as UID2 Google GMA/IMA Plugins. Available options are described in the individual guides: see [Integration Overview: High-Level Steps](#integration-overview-high-level-steps). + +## Client-Side or Client-Server Integration + +The options for integrating with UID2 using the UID2 mobile SDKs are summarized in the following table. Choose the option that's best for you. + +| Scenario | Option | Integration Guide | +| :--- | :--- | :--- | +| You have access to DII (email address or phone number) on the client side/within the mobile app, and want to keep changes within your app only. | Client-side integration | [UID2 Client-Side Integration Guide for Mobile](integration-mobile-client-side.md) | +| You have access to DII on the server side only and can do the necessary development to generate UID2 tokens server-side, or you are using a Private Operator. | Client-Server Integration | [UID2 Client-Server Integration Guide for Mobile](integration-mobile-client-server.md) | + +## Integration Overview: High-Level Steps + +At a high level, to integrate your mobile app with UID2 using the UID2 mobile SDKs, you'll need to complete the following steps: + +1. Complete the UID2 account setup. + +1. Client-Server Integration Only: Integrate server-side token generation. + +1. Add the UID2 SDK for Android or iOS into your mobile app. + +1. Configure the SDK. + +1. Check that the token was successfully generated and then pass it for bidstream use. + +1. Optionally, configure the UID2 GMA/IMA plugins for integration with the [Google GMA SDK](https://developers.google.com/ad-manager/mobile-ads-sdk) and the [Google IMA SDK](https://developers.google.com/interactive-media-ads/). + +For details, refer to one of the following guides: + +- [Client-Side Integration Guide for Mobile](integration-mobile-client-side.md) +- [Client-Server Integration Guide for Mobile](integration-mobile-client-server.md) diff --git a/docs/guides/integration-prebid-client-side.md b/docs/guides/integration-prebid-client-side.md index d0424e882..da6d15227 100644 --- a/docs/guides/integration-prebid-client-side.md +++ b/docs/guides/integration-prebid-client-side.md @@ -60,7 +60,7 @@ Complete the UID2 account setup by following the steps described in the [Account Only root-level domains are required for account setup. For example, if you're going to use UID2 with Prebid.js on example.com, shop.example.com, and example.org, you only need to provide the domain names example.com and example.org. ::: -When account setup is complete, you'll receive a public key and subscription ID. These values are unique to you, and you'll use them to configure the UID2 module. For details, see [Subscription ID and Public Key](../getting-started/gs-credentials.md#subscription-id-and-public-key). +When account setup is complete, you'll receive a public key and Subscription ID. These values are unique to you, and you'll use them to configure the UID2 module. For details, see [Subscription ID and Public Key](../getting-started/gs-credentials.md#subscription-id-and-public-key). ### Add Prebid.js to Your Site @@ -76,7 +76,7 @@ To make sure that the UID2 module is installed, find the string `uid2IdSystem` i ### Configure the UID2 Module -To configure the UID2 module, call `pbjs.setConfig` with an object containing the **public key** and **subscription ID** that you received during account setup, as well as the user's hashed or unhashed email address or phone number. +To configure the UID2 module, call `pbjs.setConfig` with an object containing the **public key** and **Subscription ID** that you received during account setup, as well as the user's hashed or unhashed email address or phone number. Once it's configured, the UID2 module generates a UID2 token for the user and stores it in the user's browser. The module automatically refreshes the token as needed as long as your site is open in the user's browser. @@ -116,7 +116,7 @@ const baseConfig = { ``` :::note -This example assumes that you're using the UID2 production environment. During integration testing, use the UID2 integration environment by setting `params.uid2ApiBase` to `'https://operator-integ.uidapi.com'`. Tokens from the UID2 integration environment are not valid for passing to the bidstream. For the integration environment, you will have different **subscription ID** and **public key** values. +This example assumes that you're using the UID2 production environment. During integration testing, use the UID2 integration environment by setting `params.uid2ApiBase` to `'https://operator-integ.uidapi.com'`. Tokens from the UID2 integration environment are not valid for passing to the bidstream. For the integration environment, you will have different **Subscription ID** and **public key** values. ::: ## Storing the UID2 Token in the Browser @@ -183,9 +183,9 @@ To check that the UID2 module has successfully generated a UID2 token, call `pbj If there are problems with the integration, here are some steps you can take: - Check the browser console logs. -- Check the values for **subscription ID** and **public key**: +- Check the values for **Subscription ID** and **public key**: - Make sure they are exactly the same values that you received from the UID2 team. - - Check that you have the correct values for the environment you're using. You'll have different **subscription ID** and **public key** values for each [environment](../getting-started/gs-environments.md). + - Check that you have the correct values for the environment you're using. You'll have different **Subscription ID** and **public key** values for each [environment](../getting-started/gs-environments.md). - Check that you provided the domain name of the site to the UID2 team during account setup. If needed, to confirm, ask your UID2 contact. - Use the browser developer tools to inspect the API calls to the UID2 service. @@ -198,7 +198,7 @@ An example of a tool for validating and debugging Prebid.js configuration is Pro ## Optional: Reduce Latency by Setting the API Base URL for the Production Environment -By default, the UID2 module makes API calls to a UID2 server in the USA. Depending on where your users are based, you might consider choosing a server closer to your users to reduce latency. +By default, the UID2 module makes API calls to a UID2 production environment server in the USA. Depending on where your users are based, you might consider choosing a server closer to your users to reduce latency. To specify a different UID2 server when you're configuring the UID2 module, set the optional params.uid2ApiBase parameter, as shown in the following example: @@ -216,4 +216,4 @@ pbjs.setConfig({ }); ``` -For the list of possible base URLs, see [Environments](../getting-started/gs-environments.md). +For the list of valid base URLs, see [Environments](../getting-started/gs-environments.md). diff --git a/docs/guides/integration-prebid-server-side.md b/docs/guides/integration-prebid-server-side.md index 854033b30..865c82a1b 100644 --- a/docs/guides/integration-prebid-server-side.md +++ b/docs/guides/integration-prebid-server-side.md @@ -390,7 +390,7 @@ The following sample is fictitious, but shows what the token response object, re ## Optional: Reduce Latency by Setting the API Base URL for the Production Environment -By default, the UID2 module makes API calls to a UID2 server in the USA. Depending on where your users are based, you might consider choosing a server closer to your users to reduce latency. +By default, the UID2 module makes API calls to a UID2 production environment server in the USA. Depending on where your users are based, you might consider choosing a server closer to your users to reduce latency. To specify a different UID2 server when you're configuring the UID2 module, set the optional params.uid2ApiBase parameter, as shown in the following example: diff --git a/docs/guides/mobile-plugin-gma-android.md b/docs/guides/mobile-plugin-gma-android.md index cae05f60e..b30f8b2ca 100644 --- a/docs/guides/mobile-plugin-gma-android.md +++ b/docs/guides/mobile-plugin-gma-android.md @@ -34,16 +34,16 @@ To run this plugin, install the following: 1. Google Mobile Ads SDK v22.0.0 or later: - [SDK](https://developers.google.com/admob/android/sdk) - [Release notes](https://developers.google.com/admob/android/rel-notes) -1. UID2 SDK for Android v0.5.0: +1. UID2 SDK for Android v0.5.0 or later: - [SDK](https://central.sonatype.com/artifact/com.uid2/uid2-android-sdk) - [UID2 SDK for Android Reference Guide](../sdks/uid2-sdk-ref-android.md) 1. [UID2 Android GMA Plugin v0.5.0](https://central.sonatype.com/artifact/com.uid2/uid2-android-sdk-gma/) ## Installation -Prerequisite: Install the Google Mobile Ads SDK and the UID2 Android SDK. +Prerequisite: Install the Google Mobile Ads SDK and the UID2 SDK for Android. -Install the UID2 Android GMA Plugin v0.5.0 to an existing app with the UID2 Android SDK and Google GMA SDK installed. There are two installation options: +Install the UID2 Android GMA Plugin v0.5.0 to an existing app with the UID2 SDK for Android and Google GMA SDK installed. There are two installation options: - [Gradle](#gradle) - [Maven](#maven) @@ -52,7 +52,7 @@ Install the UID2 Android GMA Plugin v0.5.0 to an existing app with the UID2 Andr To install with Gradle, add the SDK as a dependency in the `build.gradle` file: -``` javascript +```js implementation 'com.uid2:uid2-android-sdk-gma:0.5.0' ``` diff --git a/docs/guides/mobile-plugin-gma-ios.md b/docs/guides/mobile-plugin-gma-ios.md index 9800cc0c7..d72f28ee7 100644 --- a/docs/guides/mobile-plugin-gma-ios.md +++ b/docs/guides/mobile-plugin-gma-ios.md @@ -19,7 +19,7 @@ This plugin simplifies integration with Google Mobile Ads (GMA) for any publishe -This documentation is for the UID2 GMA Plugin for iOS version 0.3.0. +This documentation is for the UID2 GMA Plugin for iOS version 0.3.0 or later. ## GitHub Repository @@ -34,17 +34,17 @@ To run this plugin, install the following: 1. Google Mobile Ads SDK v10.7.0 or later: - [SDK](https://developers.google.com/admob/ios) - [Release Notes](https://developers.google.com/admob/ios/rel-notes) -1. UID2 SDK for iOS v0.3.0: +1. UID2 SDK for iOS v0.3.0 or later: - [SDK](https://github.com/IABTechLab/uid2-ios-sdk) - [UID2 SDK for iOS Reference Guide](../sdks/uid2-sdk-ref-ios.md) 1. [UID2 GMA Plugin for iOS v0.3.0](https://github.com/IABTechLab/uid2-ios-plugin-google-gma) ## Installation -Prerequisite: Install the Google Mobile Ads SDK and the UID2 iOS SDK. +Prerequisite: Install the Google Mobile Ads SDK and the UID2 SDK for iOS. -Install the UID2 iOS GMA Plugin via Swift Package Manager to an existing app with the UID2 iOS SDK and the Google Mobile Ads SDK installed: +Install the UID2 iOS GMA Plugin via Swift Package Manager to an existing app with the UID2 SDK for iOS and the Google Mobile Ads SDK installed: -``` javascript -.package(url: https://github.com/IABTechLab/uid2-ios-plugin-google-gma.git, exact: "0.3.0") +```js +.package(url: "https://github.com/IABTechLab/uid2-ios-plugin-google-gma.git", exact: "0.3.0") ``` diff --git a/docs/guides/mobile-plugin-ima-android.md b/docs/guides/mobile-plugin-ima-android.md index 3944942ca..517a58d0a 100644 --- a/docs/guides/mobile-plugin-ima-android.md +++ b/docs/guides/mobile-plugin-ima-android.md @@ -31,19 +31,19 @@ This plugin is in the following open-source GitHub repository: To run this plugin, install the following: -1. Google IMA SDK v3.30.3: +1. Google IMA SDK v3.30.3 or later: - [SDK](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side) - [Release history](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/history) -1. UID2 SDK for Android v0.5.0: +1. UID2 SDK for Android v0.5.0 or later: - [SDK](https://central.sonatype.com/artifact/com.uid2/uid2-android-sdk) - [UID2 SDK for Android Reference Guide](../sdks/uid2-sdk-ref-android.md) 1. [UID2 IMA Plugin for Android v0.5.0](https://central.sonatype.com/artifact/com.uid2/uid2-android-sdk-ima) ## Installation -Prerequisite: Install the Google Interactive Media Ads SDK and the UID2 Android SDK. +Prerequisite: Install the Google Interactive Media Ads SDK and the UID2 SDK for Android. -Install the UID2 Android IMA Plugin to an existing app with the UID2 Android SDK and Google IMA SDK installed. There are two installation options: +Install the UID2 Android IMA Plugin to an existing app with the UID2 SDK for Android and Google IMA SDK installed. There are two installation options: - [Gradle](#gradle) - [Maven](#maven) @@ -52,7 +52,7 @@ Install the UID2 Android IMA Plugin to an existing app with the UID2 Android SDK ### Gradle To install with Gradle, add the SDK as a dependency in the `build.gradle` file: -``` javascript +```js implementation 'com.uid2:uid2-android-sdk-ima:0.5.0' ``` diff --git a/docs/guides/mobile-plugin-ima-ios.md b/docs/guides/mobile-plugin-ima-ios.md index 195beea2a..4d5598099 100644 --- a/docs/guides/mobile-plugin-ima-ios.md +++ b/docs/guides/mobile-plugin-ima-ios.md @@ -19,7 +19,7 @@ This plugin simplifies integration with Google Interactive Media Ads (IMA) for a -This documentation is for the UID2 IMA Plugin for iOS version 0.3.0. +This documentation is for the UID2 IMA Plugin for iOS version 0.3.0 or later. ## GitHub Repository @@ -34,17 +34,17 @@ To run this plugin, install the following: 1. Google IMA SDK v3.19.1 or later: - [SDK](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side) - [Release history](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/history) -1. UID2 SDK for iOS v0.3.0: +1. UID2 SDK for iOS v0.3.0 or later: - [SDK](https://github.com/IABTechLab/uid2-ios-sdk) - [UID2 SDK for iOS Reference Guide](../sdks/uid2-sdk-ref-ios.md) 1. [UID2 IMA Plugin for iOS v0.3.0](https://github.com/IABTechLab/uid2-ios-plugin-google-ima) ## Installation -Prerequisite: Install the Google Interactive Media Ads SDK and the UID2 iOS SDK. +Prerequisite: Install the Google Interactive Media Ads SDK and the UID2 SDK for iOS. -Install the UID2 iOS IMA Plugin via Swift Package Manager to an existing app with the UID2 iOS SDK and the Google Interactive Media Ads SDK installed. +Install the UID2 iOS IMA Plugin via Swift Package Manager to an existing app with the UID2 SDK for iOS and the Google Interactive Media Ads SDK installed. ``` -.package(url: https://github.com/IABTechLab/uid2-ios-plugin-google-ima.git, exact: "0.3.0") +.package(url: "https://github.com/IABTechLab/uid2-ios-plugin-google-ima.git", exact: "0.3.0") ``` diff --git a/docs/guides/publisher-client-side.md b/docs/guides/publisher-client-side.md index b62d134e3..f2b6f38b7 100644 --- a/docs/guides/publisher-client-side.md +++ b/docs/guides/publisher-client-side.md @@ -10,12 +10,13 @@ sidebar_position: 04 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import Link from '@docusaurus/Link'; +import ReduceLatency from '/docs/snippets/_sdk-reduce-latency.mdx'; # Client-Side Integration Guide for JavaScript This guide is for publishers who want to integrate with UID2 and generate [UID2 tokens](../ref-info/glossary-uid.md#gl-uid2-token) (advertising tokens) using only JavaScript client-side changes on their website with minimum effort. -This guide does not apply to publishers who want to use a [private operator](../ref-info/glossary-uid.md#gl-private-operator), or who want to generate tokens server-side. Those publishers should follow the [Server-Side Integration Guide for JavaScript](integration-javascript-server-side.md). +This guide does not apply to publishers who want to use a private operator, or who want to generate tokens server-side. Those publishers should follow the [Server-Side Integration Guide for JavaScript](integration-javascript-server-side.md). It is also applicable to anyone who wants to share UID2 tokens in pixels, such as tracking pixels. @@ -59,7 +60,7 @@ For an example website, see this example: Complete the UID2 account setup by following the steps described in the [Account Setup](../getting-started/gs-account-setup.md) page. As part of the account setup process, you'll need to provide a list of **domain names** for the sites that you'll be using with this UID2 SDK for JavaScript. -When account setup is complete, you'll receive a **public key** and **subscription ID**. These values are unique to you, and you'll use them to configure the UID2 module. +When account setup is complete, you'll receive a **public key** and **Subscription ID**. These values are unique to you, and you'll use them to configure the UID2 module. :::tip Only root-level domains are required for account setup. For example, if you're going to use UID2 SDK for JavaScript on example.com, shop.example.com, and example.org, you only need to provide the domain names example.com and example.org. @@ -116,18 +117,12 @@ __uid2.init({ }); ``` :::note -Tokens from the UID2 integration environment are not valid for passing to the bidstream. For the integration environment, you will have different **subscription ID** and **public key** values. +Tokens from the UID2 integration environment are not valid for passing to the bidstream. For the integration environment, you will have different **Subscription ID** and **public key** values. ::: ### Optional: Reduce Latency by Setting the API Base URL for the Production Environment -By default, in the production environment, the JS SDK makes API calls to a UID2 server in the USA. Depending on where your users are based, you might consider choosing a server closer to your users in order to reduce latency. - -For example, a publisher in Singapore can set the base URL to `https://sg.prod.uidapi.com`. This is still the UID2 production environment, but the servers are in Singapore. - -For the list of possible base URLs, see [Environments](../getting-started/gs-environments.md). - -A publisher can also set the base URL to `https://global.prod.uidapi.com`. This URL directs readers to a region geographically close to them, which is ideal if your audience is geographically distributed. + To specify a different UID2 server, you can change it in the `init` call: @@ -141,12 +136,12 @@ __uid2.init({ UID2 provides the publisher with the following values required to use the client-side token generation feature: -* A subscription ID +* A Subscription ID * A public key -You'll have one set of these values for your publisher testing environment, and a separate set for your production environment. +You'll have one set of these values for your publisher Integration environment, and a separate set for your production environment. -To configure the SDK, call one of the following methods, with an object containing the **public key** and **subscription ID** that you received during account setup, as well as the user's hashed or unhashed DII (email address or phone number): +To configure the SDK, call one of the following methods, with an object containing the **public key** and **Subscription ID** that you received during account setup, as well as the user's hashed or unhashed DII (email address or phone number): * `__uid2.setIdentityFromEmail` * `__uid2.setIdentityFromEmailHash` @@ -170,10 +165,10 @@ You can configure the SDK using any one of the four accepted DII formats, for an The following examples demonstrate the different ways that you can configure the UID2 SDK and list the requirements for the DII passed to the SDK: -- Configure for Email Address -- Configure for Hashed Email Address -- Configure for Phone Number -- Configure for Hashed Phone Number +- Email, Unhashed +- Email, Normalized and Hashed +- Phone Number, Unhashed +- Phone Number, Normalized and Hashed If the SDK is configured multiples times, it uses the most recent configuration values. @@ -219,7 +214,7 @@ In this scenario: - The UID2 SDK encrypts the hash before sending it to the UID2 service. - + The following example configures the UID2 SDK with a phone number. @@ -238,7 +233,7 @@ In this scenario: - The UID2 SDK hashes the phone number before sending the encrypted hash to the UID2 service. - + The following example configures the UID2 SDK with a hashed phone number: @@ -261,15 +256,15 @@ In this scenario: ## Token Storage and Refresh -After calling one of the methods listed in [Configure the SDK for JavaScript](#configure-the-sdk-for-javascript) successfully, an [identity](../ref-info/glossary-uid.md#gl-identity) is generated and stored in local storage, under the key `UID2-sdk-identity`. The SDK refreshes the UID2 token periodically. +After calling one of the methods listed in [Configure the SDK for JavaScript](#configure-the-sdk-for-javascript) successfully, an identity is generated and stored in local storage, under the key `UID2-sdk-identity`. The SDK refreshes the UID2 token periodically. -:::danger -The format of the object stored in local storage could change without notice. We recommend that you do **not** read and update the object in local storage directly. +:::warning +The format of the object stored in local storage could change without notice. We recommend that you do **not** read or update the object in local storage directly. ::: ## Example Integration Code and When to Pass DII to the UID2 SDK -When this is the first page load with no [identity](../ref-info/glossary-uid.md#gl-identity), to start the token generation call you'll need to call one of the `setIdentity` methods with DII. Once an identity is generated, the advertising token ([UID2 token](../ref-info/glossary-uid.md#gl-uid2-token)) that you would send to the bidstream will be available by waiting for the `IdentityUpdated` event from the SDK. For an example, see how the value for `advertising_token_to_use` is set in the following code snippet. +When this is the first page load with no identity, to start the token generation call you'll need to call one of the `setIdentity` methods with DII. Once an identity is generated, the advertising token ([UID2 token](../ref-info/glossary-uid.md#gl-uid2-token)) that you would send to the bidstream will be available by waiting for the `IdentityUpdated` event from the SDK. For an example, see how the value for `advertising_token_to_use` is set in the following code snippet. In some cases, the user's DII is not available on page load, and getting the DII has some associated cost. For example, an API call might be required to fetch the DII, or the user has to be prompted to provide the DII information. @@ -357,7 +352,6 @@ If there was a problem generating the token, find the request in the **Network** ![Publisher Workflow](images/NetworkTraffic.png) - ## Example Code: Hashing and Base-64 Encoding The following code example demonstrates how to generate email and phone hashes in JavaScript. diff --git a/docs/guides/summary-guides.md b/docs/guides/summary-guides.md index c26e71a50..946d13ee9 100644 --- a/docs/guides/summary-guides.md +++ b/docs/guides/summary-guides.md @@ -35,7 +35,7 @@ Publisher integrations fall into the following main categories: The following resources are available for publisher web integrations. :::tip -For a detailed summary of web integration options, see [Web Integration Overview](../guides/integration-options-publisher-web.md). +For a detailed summary of web integration options, see [Web Integration Overview](integration-options-publisher-web.md). ::: | Integration Guide | Content Description | @@ -53,10 +53,11 @@ For a detailed summary of web integration options, see [Web Integration Overview The following resources are available for publishers integrating with Android or iOS devices. -| Integration Guide | Content Description | -| :--- | :--- | -| [UID2 SDK for Android Reference Guide](../sdks/uid2-sdk-ref-android.md) |An SDK that facilitates the process of establishing client identity using UID2 and retrieving UID2 tokens for publishers that need to support Android apps. | -| [UID2 SDK for iOS Reference Guide](../sdks/uid2-sdk-ref-ios.md) | An SDK that facilitates the process of establishing client identity using UID2 and retrieving UID2 tokens for publishers that need to support iOS apps. | +| Integration Type| Documentation | Content Description | +| :--- | :--- | :--- | +| Android/iOS (Overview) | [Mobile Integration Overview for Android and iOS](integration-mobile-overview.md) | An overview of options for mobile app publishers who want to integrate with UID2 using the UID2 SDK for Android or the UID2 SDK for iOS. | +| Android/iOS, Client-Side Integration | [Client-Side Integration Guide for Mobile](integration-mobile-client-side.md) | An integration guide for mobile app publishers who want to integrate with UID2 with changes only within the mobile app (no server-side changes). | +| Android/iOS, Client-Server Integration | [Client-Server Integration Guide for Mobile](../guides/integration-mobile-client-server.md) | An integration guide for mobile app publishers who want to integrate with UID2 by doing the following:
  1. Generating UID2 tokens server-side via either a Public or Private Operator.
  2. Passing the resulting identities to a mobile app for passing into the bidstream.
| ### Prebid Integrations @@ -66,7 +67,7 @@ The following resources are available for publishers integrating with Prebid. | :--- | :--- | | [UID2 Integration Overview for Prebid.js](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 in the RTB bidstream. | | [UID2 Client-Side Integration Guide for Prebid.js](integration-prebid-client-side.md) | An integration guide for publishers who want to integrate with UID2 and want Prebid.js to manage token generation and automatic token refresh as well as passing the tokens into the RTB bidstream. This guide is for publishers who want to request UID2 tokens client-side, which is the easiest implementation approach. | -| [UID2 Server-Side Integration Guide for Prebid.js](../guides/integration-prebid-server-side.md) | An integration guide for publishers who want to integrate with UID2 and generate identity tokens to be passed by Prebid in the RTB bidstream. This guide is for publishers who are using a private operator or who want to generate tokens server-side. | +| [UID2 Server-Side Integration Guide for Prebid.js](integration-prebid-server-side.md) | An integration guide for publishers who want to integrate with UID2 and generate identity tokens to be passed by Prebid in the RTB bidstream. This guide is for publishers who are using a private operator or who want to generate tokens server-side. | ### Google Ad Manager Integrations @@ -106,4 +107,4 @@ The following resources are available for Private Operator integrations. | :--- | :--- | | [UID2 Private Operator for AWS](operator-guide-aws-marketplace.md) | Instructions for setting up a Private Operator service for AWS Marketplace. | | [UID2 Private Operator for GCP](operator-private-gcp-confidential-space.md) | Information for setting up the UID2 Operator Service in [Confidential Space](https://cloud.google.com/confidential-computing#confidential-space), a confidential computing option from [Google Cloud](https://cloud.google.com/docs/overview/) Platform. | -| [UID2 Private Operator for Azure](operator-guide-azure-enclave.md) | Instructions for setting up the UID2 Operator Service in a Confidential Container, a confidential computing option from Microsoft Azure. | \ No newline at end of file +| [UID2 Private Operator for Azure](operator-guide-azure-enclave.md) | Instructions for setting up the UID2 Operator Service in a Confidential Container, a confidential computing option from Microsoft Azure. | diff --git a/docs/overviews/overview-publishers.md b/docs/overviews/overview-publishers.md index 9ec450f6f..3ad40bbf7 100644 --- a/docs/overviews/overview-publishers.md +++ b/docs/overviews/overview-publishers.md @@ -109,8 +109,9 @@ The following resources are available for publisher integrations supporting Andr | Integration Type| Documentation | Content Description | | :--- | :--- | :--- | -| Android | [UID2 SDK for Android Reference Guide](../sdks/uid2-sdk-ref-android.md) | Android SDK reference for publishers who want to establish client identity using UID2 and retrieve advertising tokens on Android devices. | -| iOS | [UID2 SDK for iOS Reference Guide](../sdks/uid2-sdk-ref-ios.md) | iOS SDK reference is for publishers who want to establish client identity using UID2 and retrieve advertising tokens on iOS devices. | +| Android/iOS (Overview) | [Mobile Integration Overview for Android and iOS](../guides/integration-mobile-overview.md) | An overview of options for mobile app publishers who want to integrate with UID2 using the UID2 SDK for Android or the UID2 SDK for iOS. | +| Android/iOS, Client-Side Integration | [Client-Side Integration Guide for Mobile](../guides/integration-mobile-client-side.md) | An integration guide for mobile app publishers who want to integrate with UID2 with changes only within the mobile app (no server-side changes). | +| Android/iOS, Client-Server Integration | [Client-Server Integration Guide for Mobile](../guides/integration-mobile-client-server.md) | An integration guide for mobile app publishers who want to integrate with UID2 by doing the following:
  1. Generating UID2 tokens server-side via either a Public or Private Operator.
  2. Passing the resulting identities to a mobile app for passing into the bidstream.
| ### Prebid Integrations @@ -136,4 +137,4 @@ The following resources are available for publishers integrating with Google Ad ## FAQs for Publishers -For a list of frequently asked questions for publishers using the UID2 framework, see [FAQs for Publishers](/docs/getting-started/gs-faqs.md#faqs-for-publishers). \ No newline at end of file +For a list of frequently asked questions for publishers using the UID2 framework, see [FAQs for Publishers](/docs/getting-started/gs-faqs.md#faqs-for-publishers). diff --git a/docs/ref-info/glossary-uid.md b/docs/ref-info/glossary-uid.md index 41e689264..4cf2f8ef7 100644 --- a/docs/ref-info/glossary-uid.md +++ b/docs/ref-info/glossary-uid.md @@ -114,7 +114,7 @@ import Link from '@docusaurus/Link';
See client secret.
App name
-
The Android application ID, the iOS app store ID, or the iOS bundle identifier.
+
In the context of mobile integrations, the app name is the Android application ID, the iOS app store ID, or the iOS bundle identifier.
Authorization header
The Authorization header is a way to authenticate the client to the UID2 service.
@@ -278,7 +278,7 @@ import Link from '@docusaurus/Link';
A private instance of the Operator Service, run by a Private Operator.
Public key
-
For server-side publisher integrations, the public key is one of the two values issued to publishers as their UID2 credentials. For details, see Subscription ID and Public Key.
+
For client-side publisher integrations, the public key is one of the two values issued to publishers as their UID2 credentials. For details, see Subscription ID and Public Key.
Public Operator
A Public Operator is an entity that runs a public instance of the UID2 Operator Service. For example, The Trade Desk currently serves as a Public Operator for the UID2 framework, available to all participants.
@@ -336,7 +336,7 @@ import Link from '@docusaurus/Link';
SSO is an acronym for Single sign-on. SSO allows a user to log in with the same credentials (usually, but not always, ID and password) to one of several software systems, such as apps or websites. SSO allows the user to log in once to multiple applications or sites using one set of credentials. With SSO, websites/apps do not have to maintain their own authentication systems.
Subscription ID
-
For server-side publisher integrations, the subscription ID is one of the two values issued to publishers as their UID2 credentials. For details, see Subscription ID and Public Key.
+
For client-side publisher integrations, the Subscription ID is one of the two values issued to publishers as their UID2 credentials. For details, see Subscription ID and Public Key.
diff --git a/docs/sdks/client-side-identity.md b/docs/sdks/client-side-identity.md index b35bba0d0..9b5f4f21c 100644 --- a/docs/sdks/client-side-identity.md +++ b/docs/sdks/client-side-identity.md @@ -437,7 +437,7 @@ When a user logs out of the publisher's site, make the following call: After this function is executed, the [getAdvertisingToken()](#getadvertisingtoken-string) function returns `undefined` and the [isLoginRequired()](#isloginrequired-boolean) function returns `true`. -:::danger +:::warning If you need to provide a `cookieDomain` or `cookiePath` for the SDK to access the correct cookie, and `init` has not been completed, the SDK cannot clear the cookie. In this case, no error is raised. ::: @@ -504,7 +504,7 @@ The following is an example of the UID2 cookie structure: } } ``` -:::danger +:::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/sdks/images/xcode-uid2-ios-sdk.png b/docs/sdks/images/xcode-uid2-ios-sdk.png deleted file mode 100644 index c37dfde18..000000000 Binary files a/docs/sdks/images/xcode-uid2-ios-sdk.png and /dev/null differ diff --git a/docs/sdks/summary-sdks.md b/docs/sdks/summary-sdks.md index d0a230880..7e451d3fa 100644 --- a/docs/sdks/summary-sdks.md +++ b/docs/sdks/summary-sdks.md @@ -25,8 +25,8 @@ The following table summarizes the functionality available with each SDK. |Python | Server | ✅ | ✅ | ✅ | ✅ | — | |C# / .NET | Server | ✅ | ✅ | — | — | — | |C++ | Server | ✅ | ✅ | — | — | — | -|Android | Client (Mobile) | — | — | — | ✅ | — | -|iOS | Client (Mobile)| — | — | —| ✅ |— | +|Android | Client (Mobile) | — | — | ✅ | ✅ | — | +|iOS | Client (Mobile)| — | — | ✅| ✅ |— | *Advertisers and Data Providers who need to generate raw UID2s from DII can also do this via Snowflake (see [Snowflake Integration Guide](../guides/snowflake_integration.md)) or by using the [POST /identity/map](../endpoints/post-identity-map.md) endpoint. @@ -43,5 +43,5 @@ The following SDK documentation is available for UID2 integration. Documentation | [UID2 SDK for Python](uid2-sdk-ref-python.md) | An SDK for audiences using Python server-side:
  • Helps publishers to generate or refresh UID2 tokens from DII ([POST /token/generate](../endpoints/post-token-generate)).
  • Helps UID2 sharers to encrypt or decrypt UID2 tokens ([Usage for UID2 Sharers](uid2-sdk-ref-python.md#usage-for-uid2-sharers)).
  • Helps DSPs to decrypt UID2 tokens from bid requests ([Decrypt UID2 Tokens for RTB Use](guides/dsp-guide.md#decrypt-uid2-tokens-for-rtb-use)).
| Publishers
DSPs
Data Providers
Sharers | | [UID2 SDK for C# / .NET](uid2-sdk-ref-csharp-dotnet.md) | An SDK for audiences using .NET server-side:
  • Helps DSPs to decrypt UID2 tokens from bid requests.
  • Helps UID2 sharers to encrypt or decrypt UID2 tokens.
| DSPs
Data Providers
Sharers | | [UID2 SDK for C++](uid2-sdk-ref-cplusplus.md) | An SDK for audiences using C++ server-side:
  • Helps DSPs to decrypt UID2 tokens from bid requests.
  • Helps UID2 sharers to encrypt or decrypt UID2 tokens.
| DSPs
Data Providers
Sharers | -| [UID2 SDK for Android](uid2-sdk-ref-android.md) |An SDK that facilitates the process of establishing client identity using UID2 and retrieving UID2 tokens for publishers that need to support Android apps. | Publishers | -| [UID2 SDK for iOS](uid2-sdk-ref-ios.md) | An SDK that facilitates the process of establishing client identity using UID2 and retrieving UID2 tokens for publishers that need to support iOS apps. | Publishers | +| [UID2 SDK for Android](uid2-sdk-ref-android.md) |An SDK that facilitates the process of generating or establishing client identity using UID2 and retrieving UID2 tokens for publishers that need to support Android apps. | Publishers | +| [UID2 SDK for iOS](uid2-sdk-ref-ios.md) | An SDK that facilitates the process of generating or establishing client identity using UID2 and retrieving UID2 tokens for publishers that need to support iOS apps. | Publishers | diff --git a/docs/sdks/uid2-sdk-ref-android.md b/docs/sdks/uid2-sdk-ref-android.md index 56fffc25e..d82b5eb44 100644 --- a/docs/sdks/uid2-sdk-ref-android.md +++ b/docs/sdks/uid2-sdk-ref-android.md @@ -11,23 +11,27 @@ import Link from '@docusaurus/Link'; + --> -You can use the UID2 SDK for Android to facilitate the process of establishing client identity using UID2 and retrieving advertising tokens on Android devices. +You can use the UID2 SDK for Android for the following: + +- Generating or establishing client identity using UID2. +- Retrieving advertising tokens for bidstream use. +- Automatically refreshing UID2 tokens. The following Android-related plugins, and associated documentation, are also available. @@ -36,35 +40,34 @@ The following Android-related plugins, and associated documentation, are also av | To use the Google Mobile Ads (GMA) SDK to send [UID2 tokens](../ref-info/glossary-uid.md#gl-uid2-token) as [secure signals](https://support.google.com/admob/answer/11556288) in ad requests from Android apps | [UID2 GMA Plugin for Android Integration Guide](../guides/mobile-plugin-gma-android.md) | | To use the Google Interactive Media Ads (IMA) SDK for Android to send [UID2 tokens](../ref-info/glossary-uid.md#gl-uid2-token) as [secure signals](https://support.google.com/admob/answer/11556288) in ad requests from Android apps | [UID2 IMA Plugin for Android Integration Guide](../guides/mobile-plugin-ima-android.md) | +## Non-Mobile Android Device Support + +This UID2 SDK for Android can be used for non-mobile devices for Android platforms as well. + ## Functionality This SDK simplifies integration with UID2 for any publishers who want to support UID2 for apps running on Android devices. The following table shows the functions it supports. | Encrypt Raw UID2 to UID2 Token | Decrypt UID2 Token | Generate UID2 Token from DII | Refresh UID2 Token | | :--- | :--- | :--- | :--- | -| Not supported | Not supported | Not supported | Supported | +| Not supported | Not supported | Supported | Supported | -## API Permissions +The UID2 SDK for Android is designed to generate and/or manage UID2 identity on behalf of Android apps. It enables UID2 identity to be persisted across app lifecycles by securely storing the identity on a device via platform-native encryption tools. -To use this SDK, you'll need to complete the UID2 account setup by following the steps described in the [Account Setup](../getting-started/gs-account-setup.md) page. +By default, the SDK automatically refreshes UID2 identity based on expiration dates. However, you can disable this to allow implementing apps to manage the UID2 identity lifecycle manually. -You'll be granted permission to use specific functions offered by the SDK, and given credentials for that access. Bear in mind that there might be functions in the SDK that you don't have permission to use. For example, publishers get a specific API permission to generate and refresh tokens, but the SDK might support other activities, such as sharing, which require a different API permission. +## API Permissions -For details, see [API Permissions](../getting-started/gs-permissions.md). +To use this SDK, you'll need to complete the UID2 account setup by following the steps described in the [Account Setup](../getting-started/gs-account-setup.md) page. +You'll be granted permission to use specific functions offered by the SDK, and given credentials for that access. ## SDK Version - - -This documentation is for the UID2 Android SDK version 0.5.0 and later. + -For information about specific release versions, see [https://github.com/IABTechLab/uid2-android-sdk/releases](https://github.com/IABTechLab/uid2-android-sdk/releases). +This documentation is for the UID2 SDK for Android version 1.2.0 and later. -## Features - -The UID2 Android SDK is designed to manage UID2 identity on behalf of Android apps. It enables UID2 identity to be persisted across app lifecycles by securely storing the identity on a device via platform-native encryption tools. - -By default, the SDK automatically refreshes UID2 identity based on expiration dates. However, you can disable this to allow implementing apps to manage the UID2 identity lifecycle manually. +For current and past release notes information, see [https://github.com/IABTechLab/uid2-android-sdk/releases](https://github.com/IABTechLab/uid2-android-sdk/releases). ## GitHub Repository/Binary @@ -80,7 +83,7 @@ The binary is published on Sonatype: Minimum requirements for this SDK are as follows: -- Android Studio version: 2022.1.1 Patch 2+ +- Android Studio version: v2023.3.1+ - Minimum target Android version: 4.4+ / API 19+ (SDK) 5.0+ / API 21+ (Dev-App) @@ -98,8 +101,8 @@ There are two options for installing the Android UID2 SDK: To install with Gradle, add the SDK as a dependency in the build.gradle file: -``` javascript -implementation 'com.uid2:uid2-android-sdk:0.5.0' +```js +implementation 'com.uid2:uid2-android-sdk:1.2.0' ``` ### Installing with Maven @@ -110,19 +113,62 @@ To install with Maven, add the SDK as a dependency in the `pom.xml` file: com.uid2 uid2-android-sdk - 0.5.0 + 1.2.0 ``` ## Usage Guidelines -The initial UID2 Identity *must* be generated by the implementing application and then passed into the UID2 SDK. Because of security requirements, the UID2 Mobile SDKs cannot create new UID2 identities. +The **UID2Manager** singleton is the primary developer API for the UID2 SDK for Android. It is responsible for storing, refreshing, and retrieving the UID2 Identity including the UID2 token. + +The UID2Manager singleton must be initialized before use because: + +- It allows for easier access later. +- It allows the consuming application to potentially provide its own network instance, responsible for making requests. + +The initialization can be done during the creation of the application instance, as shown in the following example: + +```js +class MyApplication : Application() { + override fun onCreate() { + super.onCreate() + // Initialize the UID2Manager class. Use DefaultNetworkSession rather than providing our own + // custom implementation. This can be done to allow wrapping something like OkHttp. + UID2Manager.init(this.applicationContext) +``` + +There are two ways to establish an initial UID2 Identity: + +1. Generate the UID2 identity using DII—email (hashed or unhashed) or phone number (hashed or unhashed). For integration instructions, see [Client-Side Integration Guide for Mobile](../guides/integration-mobile-client-side.md). + +2. Create a UID2 identity server-side and then pass it into the UID2 SDK. For integration instructions, refer to [Client-Server Integration Guide for Mobile](../guides/integration-mobile-client-server.md). The UID2 Mobile SDKs can perform refreshes of UID2 identities, after an Identity is established. This is because the refresh functionality relies on the refresh tokens that are part of the UID2 Identity. -The **UID2Manager** singleton is the primary developer API for the UID2 Android and iOS SDKs. It is responsible for storing, refreshing, and retrieving UID2 Identity. +## Code Samples + +The following code samples provide examples of performing specific activities relating to managing UID2 with the UID2 SDK for Android. + +Generate an initial UID2 Identity (refer to [Client-Side Integration Guide for Mobile](../guides/integration-mobile-client-side#configure-the-uid2-mobile-sdk)): +``` javascript +UID2Manager.getInstance().generateIdentity( + identityRequest: IdentityRequest, + subscriptionId: String, + publicKey: String, + onResult: (GenerateIdentityResult) -> Unit +) +``` +Set the UID2 Identity (refer to [Client-Server Integration Guide for Mobile](../guides/integration-mobile-client-server#configure-the-uid2-mobile-sdk)): + +```js +UID2Manager.getInstance().setIdentity(identity: UID2Identity) +``` + +Get the UID2 token (advertising token) to pass to the Advertising SDK (for ad request or bidstream use): -For Android, you must initialize the `UID2Manager` manually before you can use it. See [Android Initialization](#android-initialization). +```js +UID2Manager.getInstance().getAdvertisingToken() +``` ## UID2Manager API @@ -131,15 +177,20 @@ This section includes the functions and variables that are part of the UID2Manag ### Functions The following functions are available as part of the UID2Manager API: +- [generateIdentity()](#generateidentity) - [setIdentity()](#setidentity) - [resetIdentity()](#resetidentity) - [refreshIdentity()](#refreshidentity) - [getAdvertisingToken()](#getadvertisingtoken) - [setAutomaticRefreshEnabled()](#setautomaticrefreshenabled) +#### generateIdentity() + +Generate a UID2 Identity using Directly identifying information (DII). For instructions, see [Configure the UID2 mobile SDK](../guides/integration-mobile-client-side.md#configure-the-uid2-mobile-sdk) in the *Client-Side Integration Guide for Mobile*. + #### setIdentity() -Sets the UID2 Identity to be managed by the SDK. +Sets a UID2 Identity, created server-side, to be managed by the SDK. For details, see [Configure the UID2 Mobile SDK](../guides/integration-mobile-client-server.md#configure-the-uid2-mobile-sdk) in the *Client-Server Integration Guide for Mobile*. #### resetIdentity() @@ -172,37 +223,3 @@ The Identity variable stores and returns the current UID2Identity data object be The identityStatus variable stores and returns the status of the current UID2 Identity being managed by the SDK. -## Android Initialization - -The Android implementation expects the singleton to be initialized before use. This does two things: - -- It allows for easier access later. - -- It allows the consuming application to potentially provide its own network instance, responsible for making requests. - -The initialization can be done during the creation of the APPLICATION instance, as shown in the following example: - -``` javascript -class MyApplication : Application() { - override fun onCreate() { - super.onCreate() - // Initialize the UID2Manager class. Use DefaultNetworkSession rather than providing our own - // custom implementation. This can be done to allow wrapping something like OkHttp. - UID2Manager.init(this.applicationContext) -``` - -## Code Samples - -The following code samples provide examples of performing specific activities relating to managing UID2 with the UID2 Android SDK. - -Set the Initial UID2 Identity: - -``` javascript -UID2Manager.getInstance().setIdentity(identity: UID2Identity) -``` - -Get the UID2 token (advertising token) to pass to the Advertising SDK: - -``` javascript -UID2Manager.getInstance().getAdvertisingToken() -``` diff --git a/docs/sdks/uid2-sdk-ref-ios.md b/docs/sdks/uid2-sdk-ref-ios.md index 15992559a..69bf1273d 100644 --- a/docs/sdks/uid2-sdk-ref-ios.md +++ b/docs/sdks/uid2-sdk-ref-ios.md @@ -11,10 +11,10 @@ import Link from '@docusaurus/Link'; -You can use the UID2 SDK for iOS to facilitate the process of establishing client identity using UID2 and retrieving advertising tokens on iOS devices. +You can use the UID2 SDK for iOS for the following: + +- Generating or establishing client identity using UID2. +- Retrieving advertising tokens for bidstream use. +- Automatically refreshing UID2 tokens. The following iOS-related plugins, and associated documentation, are also available: | Purpose | Product/Documentation | | :--- | :--- | -| To use the Google Mobile Ads (GMA) SDK to send [UID2 tokens](../ref-info/glossary-uid.md#gl-uid2-token) as [secure signals](https://support.google.com/admob/answer/11556288) in ad requests from iOS apps | [UID2 GMA Plugin for iOS Integration Guide](../guides/mobile-plugin-gma-ios.md) | -| To use the Google Interactive Media Ads SDK for iOS to send [UID2 tokens](../ref-info/glossary-uid.md#gl-uid2-token) as [secure signals](https://support.google.com/admob/answer/11556288) in ad requests from iOS apps | [UID2 IMA Plugin for iOS Integration Guide](../guides/mobile-plugin-ima-ios.md) | +| To use the Google Mobile Ads (GMA) SDK to send [UID2 tokens](../ref-info/glossary-uid.md#gl-uid2-token) as [secure signals](https://support.google.com/admob/answer/11556288) in ad requests from iOS/tvOS apps | [UID2 GMA Plugin for iOS Integration Guide](../guides/mobile-plugin-gma-ios.md) | +| To use the Google Interactive Media Ads SDK for iOS to send [UID2 tokens](../ref-info/glossary-uid.md#gl-uid2-token) as [secure signals](https://support.google.com/admob/answer/11556288) in ad requests from iOS/tvOS apps | [UID2 IMA Plugin for iOS Integration Guide](../guides/mobile-plugin-ima-ios.md) | + +## tvOS Support +Although this page refers to UID2 SDK for iOS, this SDK also supports tvOS. For the required tvOS version, see [Minimum Requirements](#minimum-requirements). ## Functionality @@ -42,27 +48,24 @@ This SDK simplifies integration with UID2 for any publishers who want to support | Encrypt Raw UID2 to UID2 Token | Decrypt UID2 Token | Generate UID2 Token from DII | Refresh UID2 Token | | :--- | :--- | :--- | :--- | -| Not supported | Not supported | Not supported | Supported | +| Not supported | Not supported | Supported | Supported | -## API Permissions +The UID2 SDK for iOS is designed to generate and/or manage UID2 identity on behalf of iOS apps. It enables UID2 identity to be persisted across app lifecycles by securely storing the identity on a device via platform-native encryption tools. -To use this SDK, you'll need to complete the UID2 account setup by following the steps described in the [Account Setup](../getting-started/gs-account-setup.md) page. +By default, the SDK automatically refreshes UID2 identity based on expiration dates. However, you can disable this to allow implementing apps to manage the UID2 identity lifecycle manually. -You'll be granted permission to use specific functions offered by the SDK, and given credentials for that access. Bear in mind that there might be functions in the SDK that you don't have permission to use. For example, publishers get a specific API permission to generate and refresh tokens, but the SDK might support other activities, such as sharing, which require a different API permission. +## API Permissions -For details, see [API Permissions](../getting-started/gs-permissions.md). +To use this SDK, you'll need to complete the UID2 account setup by following the steps described in the [Account Setup](../getting-started/gs-account-setup.md) page. +You'll be granted permission to use specific functions offered by the SDK, and given credentials for that access. ## SDK Version - - -This documentation is for the UID2 iOS SDK version 0.3.0. + -## Features +This documentation is for the UID2 SDK for iOS version 1.2.0 and later. -The UID2 iOS SDK is designed to manage UID2 identity on behalf of iOS apps. It enables UID2 identity to be persisted across app lifecycles by securely storing the identity on a device via platform-native encryption tools. - -By default, the SDK automatically refreshes UID2 identity based on expiration dates. However, you can disable this to allow implementing apps to manage the UID2 identity lifecycle manually. +For current and past release notes information, see [https://github.com/IABTechLab/uid2-ios-sdk/releases](https://github.com/IABTechLab/uid2-ios-sdk/releases). ## GitHub Open-Source Repository @@ -74,8 +77,9 @@ This SDK is in the following open-source GitHub repository: Minimum requirements for this SDK are as follows: -- Xcode version: 14.0+ -- iOS minimum target version: 13.0+ +- Xcode version: 15.0+ +- iOS minimum target version: 13.0+ +- tvOS minimum target version: 13.0+ - Swift version: 5.0+ @@ -91,27 +95,60 @@ Install the iOS SDK via Swift Package Manager (SPM). There are two installation Add the following dependency to Package.swift: -``` javascript +```js dependencies: [ -.package(url: \"https://github.com/IABTechLab/uid2-ios-sdk.git\", from: "0.3.0"), + .package(url: "https://github.com/IABTechLab/uid2-ios-sdk.git", from: "1.2.0"), ] ``` ### Installing with Xcode -Add the following dependency via Xcode: +Add the following entry in the Package Dependencies for your apps: -![Xcode Dependency](images/xcode-uid2-ios-sdk.png) +| Name | Location | Dependency Rule | +| :--- | :--- |:----------------------------------------| +| uid2-ios-sdk | `git@github.com:IABTechLab/uid2-ios-sdk.git` | Up to next major version: 1.2.0 < 2.0.0 | ## Usage Guidelines -The initial UID2 Identity *must* be generated by the implementing application and then passed into the UID2 SDK. Because of security requirements, the UID2 Mobile SDKs cannot create new UID2 identities. +The **UID2Manager** singleton is the primary developer API for the UID2 SDK for iOS. It is responsible for storing, refreshing, and retrieving the UID2 Identity including the UID2 token. + +For iOS, the `UID2Manager` is initialized automatically the first time it is accessed. You can configure it to support automatic or manual refresh capabilities. + +There are two ways to establish an initial UID2 Identity: + +1. Generate the UID2 identity using DII—email (hashed or unhashed) or phone number (hashed or unhashed). For integration instructions, see [Client-Side Integration Guide for Mobile](../guides/integration-mobile-client-side.md). + +2. Create a UID2 identity from your server's back end and then pass it to the UID2 SDK. For integration instructions, see [Client-Server Integration Guide for Mobile](../guides/integration-mobile-client-server). The UID2 Mobile SDKs can perform refreshes of UID2 identities, after an Identity is established. This is because the refresh functionality relies on the refresh tokens that are part of the UID2 Identity. -The **UID2Manager** singleton is the primary developer API for the UID2 Android and iOS SDKs. It is responsible for storing, refreshing, and retrieving UID2 Identity. -For iOS, the `UID2Manager` is initialized automatically the first time it is accessed. You can configure it to support automatic or manual refresh capabilities. +## Code Samples + +The following code samples provide examples of performing specific activities relating to managing UID2 with the UID2 SDK for iOS. + +Generate an initial UID2 Identity (for instructions, see [Client-Side Integration Guide for Mobile](../guides/integration-mobile-client-side#configure-the-uid2-mobile-sdk)): + +```js +UID2Manager.shared.generateIdentity( + _ identity: IdentityType, + subscriptionID: String, + serverPublicKey: String, + appName: String? = nil +) +``` +Set the Initial UID2 Identity (for instructions, see [Client-Server Integration Guide for Mobile](../guides/integration-mobile-client-server#configure-the-uid2-mobile-sdk)): + +``` javascript +UID2Manager.shared.setIdentity(_ identity: UID2Identity) +``` + +Get the UID2 token (advertising token) to pass to the Advertising SDK (for ad request or bidstream use): + +```js +UID2Manager.shared.getAdvertisingToken() +``` ## UID2Manager API @@ -120,15 +157,20 @@ This section includes the functions and variables that are part of the UID2Manag ### Functions The following functions are available as part of the UID2Manager API: +- [generateIdentity()](#generateidentity) - [setIdentity()](#setidentity) - [resetIdentity()](#resetidentity) - [refreshIdentity()](#refreshidentity) - [getAdvertisingToken()](#getadvertisingtoken) - [setAutomaticRefreshEnabled()](#setautomaticrefreshenabled) +#### generateIdentity() + +Generate a UID2 Identity using Directly identifying information (DII). For details, see [Configure the UID2 mobile SDK](../guides/integration-mobile-client-side.md#configure-the-uid2-mobile-sdk) in the *Client-Side Integration Guide for Mobile*. + #### setIdentity() -Sets the UID2 Identity to be managed by the SDK. +Sets a UID2 Identity, created server-side, to be managed by the SDK. For details, see [Configure the UID2 Mobile SDK](../guides/integration-mobile-client-server.md#configure-the-uid2-mobile-sdk) in the *Client-Server Integration Guide for Mobile*. #### resetIdentity() @@ -161,18 +203,3 @@ The Identity variable stores and returns the current UID2Identity data object be The identityStatus variable stores and returns the status of the current UID2 Identity being managed by the SDK. -## Code Samples - -The following code samples provide examples of performing specific activities relating to managing UID2 with the UID2 iOS SDK. - -Set the initial UID2 Identity: - -``` javascript -UID2Manager.shared.setIdentity(_ identity: UID2Identity) -``` - -Get the UID2 token (advertising token) to pass to the Advertising SDK: - -``` javascript -UID2Manager.shared.getAdvertisingToken() -``` diff --git a/docs/snippets/_mobile-docs-enable-logging.mdx b/docs/snippets/_mobile-docs-enable-logging.mdx new file mode 100644 index 000000000..3b043f47e --- /dev/null +++ b/docs/snippets/_mobile-docs-enable-logging.mdx @@ -0,0 +1,26 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +The UID2 SDK can generate logs, which could help in debugging any issues during UID2 integration work. To enable logging, do the following: + + + + +```js +// During UID2Manager initialization: +UID2Manager.init( + context = this, + isLoggingEnabled = true +) +``` + + + + +```swift +UID2Settings.shared.isLoggingEnabled = true +// On iOS, you must set UID2Settings before you first access UID2Manager.shared. Changes made to settings after first access are not read. +``` + + + \ No newline at end of file diff --git a/docs/snippets/_mobile_docs_gmaima-plugin-gss.mdx b/docs/snippets/_mobile_docs_gmaima-plugin-gss.mdx new file mode 100644 index 000000000..27f0e530d --- /dev/null +++ b/docs/snippets/_mobile_docs_gmaima-plugin-gss.mdx @@ -0,0 +1,32 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +If you intend to generate UID2 tokens to send to the [Google GMA SDK](https://developers.google.com/ad-manager/mobile-ads-sdk) or the [Google IMA SDK](https://developers.google.com/interactive-media-ads/), assuming you have followed the instructions in this guide, you must also add the UID2 GMA/IMA plugins into your mobile app. For instructions, refer to the applicable plug-in guide: + +- [UID2 GMA Plugin for Android Integration Guide](../guides/mobile-plugin-gma-android) +- [UID2 GMA Plugin for iOS Integration Guide](../guides/mobile-plugin-gma-ios) +- [UID2 IMA Plugin for Android Integration Guide](../guides/mobile-plugin-ima-android) +- [UID2 IMA Plugin for iOS Integration Guide](../guides/mobile-plugin-ima-ios) + +You do not need to explicitly make the `getAdvertisingToken()` method call to retrieve the advertising tokens and pass them into Google GMA/IMA SDK manually. The UID2 GMA/IMA plugins manage this for you. + +All you need to do is make sure that `getAdvertisingToken()` returns a non-null string object: + + + + +```js +UID2Manager.getInstance().getAdvertisingToken() +``` + + + + +```js +UID2Manager.shared.getAdvertisingToken() +``` + + + + +If the token exists, the Google GMA/IMA plug-ins can retrieve it automatically via the UID2 GMA/IMA plugins. \ No newline at end of file diff --git a/docs/snippets/_sdk-reduce-latency.mdx b/docs/snippets/_sdk-reduce-latency.mdx new file mode 100644 index 000000000..00ac1858f --- /dev/null +++ b/docs/snippets/_sdk-reduce-latency.mdx @@ -0,0 +1,7 @@ +By default, UID2 SDKs make API calls to a UID2 production environment server in the USA. Depending on where your users are based, you might consider choosing a server closer to your users to reduce latency. + +For example, a publisher in Singapore can set the base URL to `https://sg.prod.uidapi.com`. This is still the UID2 production environment, but the servers are in Singapore. + +For the list of valid base URLs, see [Environments](../getting-started/gs-environments). + +You can also set the base URL to `https://global.prod.uidapi.com`. This URL directs readers to a region geographically close to them, which is ideal if your audience is geographically distributed. \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-account-setup.md b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-account-setup.md index cb5a9b4f0..1d539efec 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-account-setup.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-account-setup.md @@ -51,6 +51,14 @@ UID2 に興味を示していただいたら、詳細を詰めるために担当 アカウント設定に必要なのは、ルートレベルのドメインだけです。たとえば、example.com、shop.example.com、example.org の Client-Side でトークンを生成するために UID2 を実装する場合、ドメイン名 example.com と example.org だけを提供します。 ::: +### Client-Side Mobile Integrations + +If you're publishing to [mobile apps](../guides/integration-mobile-client-side.md), you'll need to provide a list of app names for all the mobile apps that you'll be integrating with the UID2 mobile SDKs, including any of these values that apply: + +- Android Application ID +- iOS App Store ID +- App Store ID + ## Credentials UID2 に参加する契約を結ぶと、[UID2 credentials](gs-credentials.md) と UID2 を始めるために必要な情報が提供されます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/images/integration-mobile-client-server.png b/i18n/ja/docusaurus-plugin-content-docs/current/guides/images/integration-mobile-client-server.png new file mode 100644 index 000000000..360191bdd Binary files /dev/null and b/i18n/ja/docusaurus-plugin-content-docs/current/guides/images/integration-mobile-client-server.png differ 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 new file mode 100644 index 000000000..6a83878a8 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-mobile-client-server.md @@ -0,0 +1,359 @@ +--- +title: UID2 Client-Server Integration Guide for Mobile +sidebar_label: Client-Server Integration for Mobile +pagination_label: UID2 Client-Server Integration Guide for Mobile +description: Setting up a mobile integration with token generate on server and refresh on client. +hide_table_of_contents: false +sidebar_position: 04 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Link from '@docusaurus/Link'; +import ReduceLatency from '/docs/snippets/_sdk-reduce-latency.mdx'; +import EnableLogging from '/docs/snippets/_mobile-docs-enable-logging.mdx'; +import GMAIMA_Plugins from '/docs/snippets/_mobile_docs_gmaima-plugin-gss.mdx'; + +# UID2 Client-Server Integration Guide for Mobile + +This guide is for mobile app publishers who want to integrate with UID2 by generating UID2 tokens server-side via a Public Operator or Private Operator and then passing the tokens and user identities into their mobile apps, which will in turn pass the tokens for bidstream use.   + +This is called Client-Server Integration because some integration steps are client-side and some are server-side. + +If you want to integrate with UID2 via client-side only changes (that is, all integration changes required are within the mobile apps), refer to the [UID2 Client-Side Integration Guide for Mobile](integration-mobile-client-side.md) instead. + +This page provides a high-level overview of integration steps and links to additional documentation. + +UID2 provides mobile SDKs for [Android](../sdks/uid2-sdk-ref-android.md) and [iOS](../sdks/uid2-sdk-ref-ios.md). Each SDK has the following features: + +- Takes in a UID2 identity (a UID2 token and associated values) and persists it in local file storage. +- Automatically refreshes UID2 tokens. + +:::note +This guide uses the group term **UID2 mobile SDKs** to include both the UID2 SDK for Android and the UID2 SDK for iOS. +::: + +You'll need to complete the following steps: + +1. [Complete the UID2 account setup](#complete-the-uid2-account-setup). +2. [Implement server-side token generation](#implement-server-side-token-generation). +3. [Add the UID2 mobile SDK to your mobile app](#add-the-uid2-mobile-sdk-to-your-mobile-app). +4. [Configure the UID2 mobile SDK](#configure-the-uid2-mobile-sdk). +5. [Check that the token was successfully generated and then pass it for bidstream use](#pass-generated-token-for-bidstream-use). +6. [Optionally, integrate the UID2 GMA/IMA Plugin for GAM Secure Signal integration](#optional-uid2-gmaima-plugin-for-gam-secure-signal-integration). + + + + +## Mobile SDK Version + +This guide provides instructions for using version 1.2.0 or higher of either of these UID2 mobile SDKs: + +- UID2 SDK for Android +- UID2 SDK for iOS + +For instructions for installing the correct SDK/version into your mobile app, see [Add the UID2 Mobile SDK to Your Mobile App](#add-the-uid2-mobile-sdk-to-your-mobile-app). + + +## Complete the UID2 Account Setup + +To set up your account, follow the steps described in [Account Setup](../getting-started/gs-account-setup.md). + +When account setup is complete, you'll receive your unique API key and client secret. These values are unique to you, and it's important to keep them secure. For details, see [API Key and Client Secret](../getting-started/gs-credentials.md#api-key-and-client-secret). + +## Client-Server Mobile Integration Data Flow Overview + +The following diagram shows the data flow that the publisher must implement for UID2 client-server mobile integration. + +This example uses the [UID2 SDK for Android](../sdks/uid2-sdk-ref-android.md) in the client-side mobile app and the [UID2 SDK for Java](../sdks/uid2-sdk-ref-java.md) on the server side. + +![Mobile Client-Server Integration Example](images/integration-mobile-client-server.png) + + + +## Implement Server-Side Token Generation + +The first step of UID2 integration is to be able to generate the UID2 token on your server. Then, you can pass the token into your mobile apps for sending to the RTB bidstream. + +There are two approaches to generating UID2 tokens on the server side by providing directly identifying information (DII) (email address or phone number): + +- Integration with an SDK +- Direct integration to API endpoints + +Options are summarized in the following table. + +| Integration Solution  | Generate Token | Refresh Token | +| :--- | :--- | :--- | +| [UID2 SDK for Java](../sdks/uid2-sdk-ref-java.md) | ✅ | ✅ | +| [UID2 SDK for Python](../sdks/uid2-sdk-ref-python.md) | ✅ | ✅ | +| [Direct integration (API endpoints with custom code)](../endpoints/post-token-generate.md) | ✅ | ✅ | + +Whatever integration option you choose to generate the identity (UID2 token and associated values), you'll need to implement one of the following: + +- Call the [POST /token/generate](../endpoints/post-token-generate.md) endpoint. + + The identity output that you need for the rest of this guide is the content inside the body section of a successful endpoint response. For an example, see [Successful Response](../endpoints/post-token-generate.md#successful-response). + +- 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 [UID2 SDK for Java, Publisher Basic Usage](../sdks/uid2-sdk-ref-java.md#basic-usage) or [UID2 SDK for Python, Usage for Publishers](../sdks/uid2-sdk-ref-python.md#usage-for-publishers). + + If you're using an SDK option, the `Identity` response that you need for the rest of this guide is the output of the applicable method, as follows: + + + + + ```java + tokenGenerateResponse.getIdentityJsonString() + ``` + + + + + ```py + token_generate_response.get_identity_json_string() + ``` + + + + +:::important +The endpoint and SDK API returns opt-out status if the DII you are generating the token for has been opted out of UID2. If this happens, save the information and do not call the token generation endpoint for the same DII again.  +::: + +You will need to pass the `Identity` response into the mobile app: see [Configure the UID2 Mobile SDK](#configure-the-uid2-mobile-sdk). + +:::warning +For security reasons, the API key and secret used in token generation must be called server-side. Do not store these values inside a mobile app. For details, see [Security of API Key and Client Secret](../getting-started/gs-credentials.md#security-of-api-key-and-client-secret). +::: + +## 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. + +You might decide to do server-side token refresh if you want to keep your changes in the mobile apps as simple as possible. + +If you want to manage token refresh on the server side and not the client/mobile side, you can do so using one of the following: + +- 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 [UID2 SDK for Java, Publisher Server-Only Integration section](../sdks/uid2-sdk-ref-java.md#server-only-integration) or [UID2 SDK for Python, Publisher Server-Only Integration section](../sdks/uid2-sdk-ref-python.md#server-only-integration). + +Then, pass the newly refreshed `Identity` value to the mobile app by following the rest of this guide. + +## Add the UID2 Mobile SDK to Your Mobile App + +For installation instructions, refer to one of the following: + +- [UID2 SDK for Android Reference Guide](../sdks/uid2-sdk-ref-android.md) +- [UID2 SDK for iOS Reference Guide](../sdks/uid2-sdk-ref-ios.md) + +At this point, you are ready to use the UID2 Identity generated server-side in the mobile SDK. + +### Using the UID2 Integration Environment + +By default, the SDK is configured to work with the UID2 production environment: `https://prod.uidapi.com`. If you want to use the UID2 integration environment instead, provide the following URL in your call to UID2Manager initialization: + + + + +```js +UID2Manager.init( + context = this, + serverUrl = "https://operator-integ.uidapi.com" +) +``` + + + + +```js +// Must be set before UID2Manager.shared is accessed +UID2Settings.shared.environment = .custom( + url: URL(string: "https://operator-integ.uidapi.com")! +) +``` + + + + +:::note +Bear in mind the following differences between environments: +- Tokens from the UID2 integration environment are not valid for passing to the bidstream. +- You'll have a different set of API key and client secret values for each environment (integration and production). Be sure to use the correct values for each environment. +::: + +### Optional: Reduce Latency by Setting the API Base URL for the Production Environment + + + +To specify a different UID2 server, you can change it in the `init` call: + + + + +```js +UID2Manager.init( + context = this, + serverUrl = "https://global.prod.uidapi.com" +) +``` + + + + +```js +UID2Settings.shared.environment = .singapore +// or +UID2Settings.shared.environment = .custom( + url: URL(string: "https://global.prod.uidapi.com")! +) +``` + + + + +## Configure the UID2 Mobile SDK + +After you've instantiated `UID2Manager` correctly in your mobile app, you'll need to pass a UID2 identity generated server-side (see [Implement server-side token generation](#implement-server-side-token-generation)), and then pass it into the mobile app using the `setIdentity` method, as shown in the following: + + + + +```js +UID2Manager.getInstance().setIdentity() +``` + + + + +```js +UID2Manager.shared.setIdentity() +``` + + + + +## Token Storage + +After you call the `setIdentity` method, the UID2 identity is persisted in local file storage. + +:::warning +The format of the file stored in the local file storage, or the filename itself, could change without notice. We recommend that you do not read or update the file directly. +::: + +## Pass Generated Token for Bidstream Use + +To retrieve the token, in your mobile app, call the following: + + + + +```js +UID2Manager.getInstance().getAdvertisingToken() +``` + + + + +```js +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== +``` + +You can use this identity to pass downstream for sending in the RTB bidstream. + +If the `getAdvertisingToken()` method call returns `null`, there was no identity or valid token generated. Some possible reasons for this, and some things you could do to troubleshoot, are as follows: + +- The identity is invalid. In this scenario there are a couple of options: + - Check to see whether there are any errors from the previous `setIdentity()` call. + - Check the status of the identity, using `UID2Manager.getInstance().getIdentityStatus()` for Android or `UID2Manager.shared.identityStatus` for iOS. +- You could enable logging to get more information: see [Enable Logging](#enable-logging). +- The advertising token inside the UID2 identity has expired, and the refresh token has also expired, so the SDK cannot refresh the token. + +If there is no identity, follow the instructions in [Implement Server-Side Token Generation](#implement-server-side-token-generation) again, generate a new identity, and pass the result into your mobile app's UID2Manager again. + +## When to Pass a new UID2 Identity/Token into the SDK + +The best way to determine whether a new UID2 identity is required by the UID2 SDK again is to call the `getAdvertisingToken()` method in all cases: + + + + +```js +UID2Manager.getInstance().getAdvertisingToken() +``` + + + + +```js +UID2Manager.shared.getAdvertisingToken() +``` + + + + +On startup/resumption of the app, if `getAdvertisingToken()` returns `null`, it is time to generate new identity on the server by following the instructions in [Implement Server-Side Token Generation](#implement-server-side-token-generation). Then, pass the result into the mobile app’s UID2Manager again: see [Configure the UID2 mobile SDK](#configure-the-uid2-mobile-sdk). + +## Enable Logging + + + +## Enable Automatic Token Refresh in Mobile App/Client Side + +By default, after a valid UID2 identity has been passed into the UID2Manager, it performs automatic token refresh. If for any reason token refresh was disabled, you can enable it with the following method call: + + + + +**Android Java**: + +```java +UID2Manager.getInstance().setAutomaticRefreshEnabled(false) +``` + +**Android Kotlin**: + +```kotlin +UID2Manager.getInstance().automaticRefreshEnabled = false +``` + + + + +```js +UID2Manager.shared.automaticRefreshEnabled = false +``` + + + + +## Optional: UID2 GMA/IMA Plugin for GAM Secure Signal integration + + diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-mobile-client-side.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-mobile-client-side.md new file mode 100644 index 000000000..897bbe86c --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-mobile-client-side.md @@ -0,0 +1,703 @@ +--- +title: UID2 Client-Side Integration Guide for Mobile +sidebar_label: Client-Side Integration for Mobile +pagination_label: UID2 Client-Side Integration Guide for Mobile +description: Setting up a mobile integration with token generate and refresh both on the client side. +hide_table_of_contents: false +sidebar_position: 04 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Link from '@docusaurus/Link'; +import ReduceLatency from '/docs/snippets/_sdk-reduce-latency.mdx'; +import GMAIMA_Plugins from '/docs/snippets/_mobile_docs_gmaima-plugin-gss.mdx'; +import EnableLogging from '/docs/snippets/_mobile-docs-enable-logging.mdx'; + +# UID2 Client-Side Integration Guide for Mobile + +This guide is for mobile app publishers who want to integrate with UID2 with changes only within their mobile app. + +These instructions do not apply to publishers who want to use a Private Operator, or who want to generate tokens server-side. Those publishers should follow the [Client-Server Integration Guide for Mobile](integration-mobile-client-server.md). + +This page provides a high-level overview of integration steps and links to additional documentation. + +UID2 provides mobile SDKs for [Android](../sdks/uid2-sdk-ref-android.md) and [iOS](../sdks/uid2-sdk-ref-ios.md). Each SDK has the following features: + +- Generates a UID2 identity (a UID2 token and associated values) and persists it in local file storage. +- Automatically refreshes UID2 tokens. + +:::note +This guide uses the group term **UID2 mobile SDKs** to include both the UID2 SDK for Android and the UID2 SDK for iOS. +::: + +To integrate with UID2 client-side, you'll need to complete the following steps: + +1. [Complete the UID2 account setup](#complete-the-uid2-account-setup). + +1. [Add the UID2 mobile SDK to your mobile app](#add-the-uid2-mobile-sdk-to-your-mobile-app). + +1. [Configure the UID2 mobile SDK](#configure-the-uid2-mobile-sdk). + +1. [Check that the token was successfully generated and then pass it for bidstream use](#pass-generated-token-for-bidstream-use). + +1. [Optionally, integrate the UID2 GMA/IMA Plugin for GAM Secure Signal integration](#optional-uid2-gmaima-plugin-for-gam-secure-signal-integration). + + + +## Mobile SDK Version + +This guide provides instructions for using version 1.2.0 or higher of either of these UID2 mobile SDKs: + +- UID2 SDK for Android +- UID2 SDK for iOS + +For instructions for installing the correct SDK/version into your mobile app, see [Add the UID2 Mobile SDK to Your Mobile App](#add-the-uid2-mobile-sdk-to-your-mobile-app). + +## Client-Side Integration Example + +For an example of how to configure a UID2 mobile SDK, and how to generate tokens using client-side integration for mobile, you can try out the UID2 development app. + +Follow the applicable instructions, for Android or iOS: + + + + +1. Check out the main branch of the [UID2 SDK for Android source code repository on GitHub](https://github.com/IABTechLab/uid2-android-sdk/tree/main). +1. In Android Studio (Jellyfish/v2023.3.1 or whichever future version supports the Android Gradle Plugin version required by the UID2 SDK for Android release at the time), open the directory that you checked out. +1. Run the **dev-app** app. +1. When you've started the app, make sure that the **Client Side** checkbox is checked. +1. Enter an email or phone number, and then click the arrow to the right. + + + + +1. Check out the [main branch of the UID2 SDK For iOS source code repository on GitHub](https://github.com/IABTechLab/uid2-ios-sdk/tree/main). +1. In Xcode, open this project file: + + ```js + Development/UID2SDKDevelopmentApp/UID2SDKDevelopmentApp.xcodeproj + ``` +1. Run the **UID2SDKDevelopmentApp** app scheme. +1. When you've started the app, make sure that the **Client Side** checkbox is checked. +1. Enter an email or phone number, and then click the arrow to the right. + + + + +Behind the scenes, the development app makes the following UID2 SDK API call. This call sends a request to the UID2 service to generate an identity (a UID2 token and associated values) for the email/phone input: + + + + +```js +UID2Manager.getInstance().generateIdentity( + identityRequest: IdentityRequest, + subscriptionId: String, + publicKey: String, + onResult: (GenerateIdentityResult) -> Unit +) +``` + + + + +```js +UID2Manager.shared.generateIdentity( + _ identity: IdentityType, + subscriptionID: String, + serverPublicKey: String, + appName: String? = nil +) +``` + + + + +When the API call is successful, the app displays the resulting identity and persists it inside the `UID2Manager` class. + +The identity includes the generated UID2 advertising token value, which you can retrieve using the `getAdvertisingToken()` method call: + + + + +```js +UID2Manager.getInstance().getAdvertisingToken() +``` + + + + +```js +UID2Manager.shared.getAdvertisingToken() +``` + + + + +This method call returns the value that you need to make an ad request: see [Pass Generated Token for Bidstream Use](#pass-generated-token-for-bidstream-use). + +### Testing With Your Own Configuration + +By default, the development app uses default values for Subscription ID and public key, which are stored in the following object: + + + + +```js +com.uid2.dev.ui.MainScreenViewModel.Companion +``` + + + + +```js +RootViewModel +``` + + + + +By default, the development app is configured to connect to the UID2 integration environment, as specified in the following Android method call/iOS file: + + + + +```js +com.uid2.UID2Manager.Companion#init +``` + + + + +```js +see UID2SDKDevelopmentApp/UID2SDKDevelopmentApp/Info.plist +``` + + + + +If necessary, you can also change the default Subscription ID and public key to values assigned to you, and connect to the UID2 Production environment. For details, see [Optional: Reduce Latency by Setting the API Base URL for the Production Environment](#optional-reduce-latency-by-setting-the-api-base-url-for-the-production-environment). + +## Complete the UID2 Account Setup + +To set up your account, follow the steps described in [Account Setup](../getting-started/gs-account-setup.md). As part of the account setup process, you'll need to provide a list of app names for all the mobile apps that you'll be integrating with the UID2 mobile SDKs, including any of these values that apply: + +- Android Application ID +- iOS Bundle Identifier +- iOS App Store ID + +When account setup is complete, you'll receive a [Subscription ID and public key](../getting-started/gs-credentials.md#subscription-id-and-public-key). These values are unique to you, and you'll use them when you [configure the UID2 mobile SDK](#configure-the-uid2-mobile-sdk). + +## Add the UID2 Mobile SDK to Your Mobile App + +To add the mobile SDK to your app, follow the applicable documentation: + +- [UID2 SDK for Android Reference Guide](../sdks/uid2-sdk-ref-android.md) +- [UID2 SDK for iOS Reference Guide](../sdks/uid2-sdk-ref-ios.md) + +At this point, you are ready to start generating UID2 tokens using the SDK. + +### Using the UID2 Integration Environment + +By default, the SDK is configured to work with the UID2 production environment: `https://prod.uidapi.com`. If you want to use the integration environment instead, provide the following URL in your call to initialize `UID2Manager`: + + + + +```js +UID2Manager.init( + context = this, + serverUrl = "https://operator-integ.uidapi.com" +) +``` + + + + +```js +// Must be set before UID2Manager.shared is accessed +UID2Settings.shared.environment = .custom( + url: URL(string: "https://operator-integ.uidapi.com")! +) +``` + + + + +:::note +Bear in mind the following differences between environments: +- Tokens from the UID2 integration environment are not valid for passing to the bidstream. +- You'll have a different set of Subscription ID and public key values for each environment (integration and production). Be sure to use the correct values for each environment. +::: + +### Optional: Reduce Latency by Setting the API Base URL for the Production Environment + + + +To specify a different UID2 server, you can make config changes, as shown in the following examples: + + + + +```js +UID2Manager.init( + context = this, + serverUrl = "https://global.prod.uidapi.com" +) +``` + + + + +```js +// Must be set before UID2Manager.shared is accessed +UID2Settings.shared.environment = .custom( + url: URL(string: "https://global.prod.uidapi.com")! +) +// or use a named environment +UID2Settings.shared.environment = .sydney +``` + + + + +## Configure the UID2 Mobile SDK + +UID2 provides the publisher with the following values, which are needed for generating the UID2 token on the client side: + +- Subscription ID +- Public key + +You'll have one set of these values for your Integration environment, and a separate set for your production environment. + +To configure the SDK, you must pass in the Subscription ID and public key that you received during account setup, as well as the user’s hashed or unhashed directly identifying information (DII) (email address or phone number), into the following method call: + + + + +```js +UID2Manager.getInstance().generateIdentity( + identityRequest: IdentityRequest, + subscriptionId: String, + publicKey: String, + onResult: (GenerateIdentityResult) -> Unit +) +``` + + + + +```js +UID2Manager.shared.generateIdentity( + _ identity: IdentityType, + subscriptionID: String, + serverPublicKey: String, + appName: String? = nil +) +``` + + + + +Once it's configured, the UID2 mobile SDK does the following: + +- Generates a UID2 identity, including token, for the user. +- Stores the token locally on the user’s device. +- Automatically refreshes the token as required while your app is open. + +:::tip +You can pass the user’s DII to the UID2 mobile SDK either hashed or unhashed. If you pass the DII unhashed, the SDK hashes it for you. If you want to pass the DII to the SDK already hashed, you must normalize it before hashing. For details, see [Normalization and Encoding](../getting-started/gs-normalization-encoding.md). +::: + +### Format Examples for DII + +The SDK encrypts the hashed DII before sending it to the UID2 service. + +You can invoke the `generateIdentity` method using any of the four accepted formats for DII, for any specific user. The DII format might vary per user, but you can only send one value per user. + +The following examples demonstrate the different ways that you can configure the UID2 mobile SDK and list the requirements for the DII passed into the SDK: + +- Email, Unhashed +- Email, Normalized and Hashed +- Phone Number, Unhashed +- Phone Number, Normalized and Hashed + +If the `generateIdentity` method is called multiple times, the UID2 mobile SDK uses the most recent configuration values. + + + + +The following example configures the UID2 mobile SDK with an email address. + + + + +```js +UID2Manager.getInstance().generateIdentity( + IdentityRequest.Email("test@example.com"), + subscriptionId, + publicKey, +) { result -> + when (result) { + is Error -> ... + is Success -> ... + } +} +``` + + + + +```js +struct InvalidEmailError: Error, LocalizedError { + var errorDescription: String = "Invalid email address" +} +Task { + do { + guard let normalizedEmail = IdentityType.NormalizedEmail(string: "test@example.com") else { + throw InvalidEmailError() // email is invalid and cannot be normalized, handle error + } + try await UID2Manager.shared.generateIdentity( + .email(normalizedEmail), + subscriptionID: subscriptionID, + serverPublicKey: serverPublicKeyString + ) + } catch { + // read `error` object for troubleshooting or enable logging to view it in logs + } +} +``` + + + + +In this scenario: + +- No normalization or hashing is required by the publisher. +- The UID2 mobile SDK normalizes and hashes the email address before sending the encrypted hash to the UID2 service. + + + + +The following example configures the UID2 SDK with a hashed email address. + + + + +```js +UID2Manager.getInstance().generateIdentity( + IdentityRequest.EmailHash( + “eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc=” + ), + subscriptionId, + publicKey, +) { result -> + when (result) { + is Error -> ... + is Success -> ... + } +} +``` + + + + +```js +Task { + do { + try await UID2Manager.shared.generateIdentity( + .emailHash("eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc="), + subscriptionID: subscriptionID, + serverPublicKey: serverPublicKeyString + ) + } catch { + // read `error` object for troubleshooting or enable logging to view it in logs + } +} +``` + + + + +In this scenario: + +- The publisher is responsible for normalizing and hashing the email address. For details, see [Email Address Normalization](../getting-started/gs-normalization-encoding.md#email-address-normalization). +- The UID2 mobile SDK encrypts the hashed DII before sending it to the UID2 service. + + + + +The following example configures the UID2 mobile SDK with a phone number. + + + + +```js +UID2Manager.getInstance().generateIdentity( + IdentityRequest.Phone(“+1111111111”), + subscriptionId, + publicKey, +) { result -> + when (result) { + is Error -> ... + is Success -> ... + } +} +``` + + + + +```js +struct InvalidPhoneError: Error, LocalizedError { + var errorDescription: String = "Invalid phone number" +} +Task { + do { + guard let normalizedPhone = IdentityType.NormalizedPhone(normalized: "+1111111111") else { + throw InvalidPhoneError() // Phone number is not normalized according to ITU E.164. + } + try await UID2Manager.shared.generateIdentity( + .phone(normalizedPhone), + subscriptionID: subscriptionID, + serverPublicKey: serverPublicKeyString + ) + } catch { + // read `error` object for troubleshooting or enable logging to view it in logs + } +} +``` + + + + +In this scenario: + +- The publisher is responsible for normalizing the phone number. For details, see [Phone Number Normalization](../getting-started/gs-normalization-encoding.md#phone-number-normalization). +- The UID2 mobile SDK hashes the phone number before sending the encrypted hash to the UID2 service. + + + + +The following example configures the UID2 mobile SDK with a hashed phone number. + + + + +```js +UID2Manager.getInstance().generateIdentity( + IdentityRequest.PhoneHash( + “eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc=” + ), + subscriptionId, + publicKey, +) { result -> + when (result) { + is Error -> ... + is Success -> ... + } +} +``` + + + + +```js +Task { + do { + try await UID2Manager.shared.generateIdentity( + .phoneHash("eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc="), + subscriptionID: subscriptionID, + serverPublicKey: serverPublicKeyString + ) + } catch { + // read `error` object for troubleshooting or enable logging to view it in logs + } +} +``` + + + + +In this scenario: + +- The publisher is responsible for normalizing and hashing the phone number. For details, see [Phone Number Hash Encoding](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding). +- The UID2 mobile SDK encrypts the hashed DII before sending it to the UID2 service. + + + + +## Token Storage and Refresh + +After a call to the applicable method listed in [Format Examples for DII](#format-examples-for-dii) is successful, an identity is generated and stored in local file storage. The UID2 mobile SDK refreshes the UID2 token periodically. + +:::warning +The format of the file stored in the local file storage, or the filename itself, could change without notice. We recommend that you do not read or update the file directly. +::: + +## Pass Generated Token for Bidstream Use + +In your mobile app, if the call to `generateIdentity` was successful, it returned an identity. The next step is to call the `getAdvertisingToken()` method, as follows: + + + + +```js +UID2Manager.getInstance().getAdvertisingToken() +``` + + + + +```js +UID2Manager.shared.getAdvertisingToken() +``` + + + + +If successful, this method call returns the token—a non-null string object such as the following: + +```js +AgAAAQFt3aNLXKXEyWS8Tpezcymk1Acv3n+ClOHLdAgqR0kt0Y+pQWSOVaW0tsKZI4FOv9K/rZH9+c4lpm2DBpmFJqjdF6FAaAzva5vxDIX/67UOspsYtiwxH73zU7Fj8PhVf1JcpsxUHRHzuk3vHF+ODrM13A8NAVlO1p0Wkb+cccIIhQ== +``` + +You can use this token to pass downstream for sending in the RTB bidstream. + +If the `getAdvertisingToken()` method call returns `null`, there was no identity or valid token generated. + +Some possible reasons for this, and some things you could do to troubleshoot, are as follows: + +- The identity is invalid. In this scenario there are a couple of options: + - Check to see whether there are any errors from the previous `generateIdentity` call. + - Check the status of the identity, using `UID2Manager.getInstance().getIdentityStatus()` for Android or `UID2Manager.shared.identityStatus` for iOS. + + It's possible that the DII has been opted out of UID2: for details, see [When to Pass DII into the SDK](#when-to-pass-dii-into-the-sdk). +- You could enable logging to get more information: see [Enable Logging](#enable-logging). +- The advertising token inside the UID2 identity has expired, and the refresh token has also expired, so the SDK cannot refresh the token. + +If there is no identity, you'll need to call the `generateIdentity` method again: see [Configure the UID2 Mobile SDK](#configure-the-uid2-mobile-sdk). + +For more information, see [When to Pass DII into the SDK](#when-to-pass-dii-into-the-sdk) (next section). + +## When to Pass DII into the SDK + +The first time a new user opens the app, no UID2 identity exists. You'll need to call the `generateIdentity` method, with the DII, to start the token generation: + + + + +```js +UID2Manager.getInstance().generateIdentity( + identityRequest: IdentityRequest, + subscriptionId: String, + publicKey: String, + onResult: (GenerateIdentityResult) -> Unit +) +``` + + + + +```js +UID2Manager.shared.generateIdentity( + _ identity: IdentityType, + subscriptionID: String, + serverPublicKey: String, + appName: String? = nil +) +``` + + + + +When this method call completes successfully, the advertising token (UID2 token) is available for you to send to the bidstream. + +If the UID2 identity stored in local file storage has expired and cannot be refreshed, you must call the `generateIdentity` method again to generate a new identity and get the resulting UID2 token. The only exception is when the response to the following Android method/iOS object indicates that the DII was opted out of UID2: + + + + +```js +UID2Manager.getInstance().getIdentityStatus() +``` + + + + +```js +UID2Manager.shared.identityStatus +``` + + + + +A response status of `OPT_OUT` for Android, or `optOut` for iOS, indicates that the DII has been opted out of UID2 and no identity/token should be generated for it. You might want to avoid making repeated `generateIdentity` calls: if the DII has a status of opted out, the UID2 token is not generated. + +The best way to determine if DII is required by the UID2 mobile SDKs is to always call the `getAdvertisingToken()` method when the app starts up or resumes: + + + + +```js +UID2Manager.getInstance().getAdvertisingToken() +``` + + + + +```js +UID2Manager.shared.getAdvertisingToken() +``` + + + + +If `getAdvertisingToken()` returns null, and the identity status is not `OPT_OUT`/`optOut`, you'll need to generate a new token. To do this, pass the DII into the `generateIdentity` method again. For details, see [Configure the UID2 mobile SDK](#configure-the-uid2-mobile-sdk). + + + +## Enable Logging + + + +## Optional: UID2 GMA/IMA Plugin for GAM Secure Signal integration + + diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-mobile-overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-mobile-overview.md new file mode 100644 index 000000000..798b99ae6 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-mobile-overview.md @@ -0,0 +1,65 @@ +--- +title: UID2 Mobile Integration Overview for Android and iOS +sidebar_label: Integration Overview for Mobile +pagination_label: Mobile Integration Overview for Android and iOS +description: Overview of options for UID2 mobile integration. +hide_table_of_contents: false +sidebar_position: 04 +displayed_sidebar: sidebarPublishers +--- + +import Link from '@docusaurus/Link'; + +# UID2 Mobile Integration Overview for Android and iOS + +This guide is an overview of integration options for mobile app publishers who want to integrate with UID2 using the UID2 SDK for Android or the UID2 SDK for iOS. + +:::note +This guide uses the group term **UID2 mobile SDKs** to include both the UID2 SDK for Android and the UID2 SDK for iOS. +::: + + + +## Introduction + +UID2 provides SDKs for Android/iOS that support the following: + +- Generating the UID2 token +- Refreshing the UID2 token +- Storing the UID2 token + +For additional flexibility, UID2 also provides alternative methods for some of the features and complementary products, such as UID2 Google GMA/IMA Plugins. Available options are described in the individual guides: see [Integration Overview: High-Level Steps](#integration-overview-high-level-steps). + +## Client-Side or Client-Server Integration + +The options for integrating with UID2 using the UID2 mobile SDKs are summarized in the following table. Choose the option that's best for you. + +| Scenario | Option | Integration Guide | +| :--- | :--- | :--- | +| You have access to DII (email address or phone number) on the client side/within the mobile app, and want to keep changes within your app only. | Client-side integration | [UID2 Client-Side Integration Guide for Mobile](integration-mobile-client-side.md) | +| You have access to DII on the server side only and can do the necessary development to generate UID2 tokens server-side, or you are using a Private Operator. | Client-Server Integration | [UID2 Client-Server Integration Guide for Mobile](integration-mobile-client-server.md) | + +## Integration Overview: High-Level Steps + +At a high level, to integrate your mobile app with UID2 using the UID2 mobile SDKs, you'll need to complete the following steps: + +1. Complete the UID2 account setup. + +1. Client-Server Integration Only: Integrate server-side token generation. + +1. Add the UID2 SDK for Android or iOS into your mobile app. + +1. Configure the SDK. + +1. Check that the token was successfully generated and then pass it for bidstream use. + +1. Optionally, configure the UID2 GMA/IMA plugins for integration with the [Google GMA SDK](https://developers.google.com/ad-manager/mobile-ads-sdk) and the [Google IMA SDK](https://developers.google.com/interactive-media-ads/). + +For details, refer to one of the following guides: + +- [Client-Side Integration Guide for Mobile](integration-mobile-client-side.md) +- [Client-Server Integration Guide for Mobile](integration-mobile-client-server.md) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-prebid-client-side.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-prebid-client-side.md index c98d3b530..0e6a244ff 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-prebid-client-side.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-prebid-client-side.md @@ -116,7 +116,7 @@ const baseConfig = { ``` :::note -この例では、UID2 本番環境を使用することを想定しています。インテグレーションテストでは、`params.uid2ApiBase` を `'https://operator-integ.uidapi.com'` に設定して UID2 テスト環境を使用します。UID2 テスト環境のトークンはビッドストリームに渡すには無効です。テスト環境では、**subscription ID** と **public key** の値が異なります。 +この例では、UID2 本番環境を使用することを想定しています。インテグレーションテストでは、`params.uid2ApiBase` を `'https://operator-integ.uidapi.com'` に設定して UID2 テスト環境を使用します。UID2 テスト環境のトークンはビッドストリームに渡すには無効です。テスト環境では、**Subscription ID** と **public key** の値が異なります。 ::: ## Storing the UID2 Token in the Browser diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-gma-android.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-gma-android.md index b87c24794..41e64b3c8 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-gma-android.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-gma-android.md @@ -34,7 +34,7 @@ UID2 Google Mobile Ads (GMA) Plugin for Android は、[Google Mobile Ads (GMA) S 1. Google Mobile Ads SDK v22.0.0 or later: - [SDK](https://developers.google.com/admob/android/sdk) - [Release notes](https://developers.google.com/admob/android/rel-notes) -1. UID2 SDK for Android v0.5.0: +1. UID2 SDK for Android v0.5.0 or later: - [SDK](https://central.sonatype.com/artifact/com.uid2/uid2-android-sdk) - [UID2 SDK for Android Reference Guide](../sdks/uid2-sdk-ref-android.md) 1. [UID2 Android GMA Plugin v0.5.0](https://central.sonatype.com/artifact/com.uid2/uid2-android-sdk-gma/) @@ -52,7 +52,7 @@ UID2 Android SDK と Google IMA SDK がインストールされている既存 Gradle でインストールするには、`build.gradle` ファイルに依存関係として SDK を追加します: -``` javascript +```js implementation 'com.uid2:uid2-android-sdk-gma:0.5.0' ``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-gma-ios.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-gma-ios.md index 3f00b4e85..3e2fe3908 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-gma-ios.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-gma-ios.md @@ -19,7 +19,7 @@ UID2 Google Mobile Ads (GMA) Plugin for iOS は、[Google Mobile Ads (GMA) SDK]( -このドキュメントは UID2 GMA Plugin for iOS バージョン 0.2.0 用です。 +このドキュメントは UID2 GMA Plugin for iOS バージョン 0.3.0 用です。 ## GitHub Repository @@ -34,10 +34,10 @@ UID2 Google Mobile Ads (GMA) Plugin for iOS は、[Google Mobile Ads (GMA) SDK]( 1. Google Mobile Ads SDK v10.7.0 or later: - [SDK](https://developers.google.com/admob/ios) - [Release Notes](https://developers.google.com/admob/ios/rel-notes) -1. UID2 SDK for iOS v0.2.0: +1. UID2 SDK for iOS v0.3.0 or later: - [SDK](https://github.com/IABTechLab/uid2-ios-sdk) - [UID2 SDK for iOS Reference Guide](../sdks/uid2-sdk-ref-ios.md) -1. [UID2 GMA Plugin for iOS v0.2.0](https://github.com/IABTechLab/uid2-ios-plugin-google-gma) +1. [UID2 GMA Plugin for iOS v0.3.0](https://github.com/IABTechLab/uid2-ios-plugin-google-gma) ## Installation @@ -45,6 +45,6 @@ UID2 Google Mobile Ads (GMA) Plugin for iOS は、[Google Mobile Ads (GMA) SDK]( UID2 iOS SDK と Google Mobile Ads SDK がインストールされている既存のアプリに、Swift Package Manager 経由で UID2 iOS IMA Plugin をインストールします: -``` javascript -.package(url: https://github.com/IABTechLab/uid2-ios-plugin-google-gma.git, exact: "0.2.0") +```js +.package(url: "https://github.com/IABTechLab/uid2-ios-plugin-google-gma.git", exact: "0.3.0") ``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-ima-android.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-ima-android.md index 32d08e006..80f1e1302 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-ima-android.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-ima-android.md @@ -31,10 +31,10 @@ UID2 Interactive Media Ads (IMA) Plugin for Android は、[Google IMA SDK for An このプラグインを実行するには、以下をインストールします: -1. Google IMA SDK v3.30.3: +1. Google IMA SDK v3.30.3 or later: - [SDK](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side) - [Release history](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/history) -1. UID2 SDK for Android v0.5.0: +1. UID2 SDK for Android v0.5.0 or later: - [SDK](https://central.sonatype.com/artifact/com.uid2/uid2-android-sdk) - [UID2 SDK for Android Reference Guide](../sdks/uid2-sdk-ref-android.md) 1. [UID2 IMA Plugin for Android v0.5.0](https://central.sonatype.com/artifact/com.uid2/uid2-android-sdk-ima) @@ -52,7 +52,7 @@ UID2 Android SDK と Google IMA SDK がインストールされている既存 ### Gradle Gradle でインストールするには、`build.gradle` ファイルに依存関係として SDK を追加します: -``` javascript +```js implementation 'com.uid2:uid2-android-sdk-ima:0.5.0' ``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-ima-ios.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-ima-ios.md index 146df9bdb..67025af15 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-ima-ios.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/mobile-plugin-ima-ios.md @@ -19,7 +19,7 @@ UID2 Interactive Media Ads (IMA) Plugin for iOS は、[Google IMA SDK for iOS](h -このドキュメントはUID2 IMA Plugin for iOS version 0.2.0 用です。 +このドキュメントはUID2 IMA Plugin for iOS version 0.3.0 用です。 ## GitHub Repository @@ -34,10 +34,10 @@ UID2 Interactive Media Ads (IMA) Plugin for iOS は、[Google IMA SDK for iOS](h 1. Google IMA SDK v3.19.1 or later: - [SDK](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side) - [Release history](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/history) -1. UID2 SDK for iOS v0.2.0: +1. UID2 SDK for iOS v0.3.0 or later: - [SDK](https://github.com/IABTechLab/uid2-ios-sdk) - [UID2 SDK for iOS Reference Guide](../sdks/uid2-sdk-ref-ios.md) -1. [UID2 IMA Plugin for iOS v0.2.0](https://github.com/IABTechLab/uid2-ios-plugin-google-ima) +1. [UID2 IMA Plugin for iOS v0.3.0](https://github.com/IABTechLab/uid2-ios-plugin-google-ima) ## Installation @@ -46,5 +46,5 @@ UID2 Interactive Media Ads (IMA) Plugin for iOS は、[Google IMA SDK for iOS](h UID2 iOS SDK と Google Interactive Media Ads SDK がインストールされている既存のアプリに、Swift Package Manager 経由で UID2 iOS IMA Plugin v0.2.0 をインストールします。 ``` -.package(url: https://github.com/IABTechLab/uid2-ios-plugin-google-ima.git, exact: "0.2.0") +.package(url: "https://github.com/IABTechLab/uid2-ios-plugin-google-ima.git", exact: "0.3.0") ``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/publisher-client-side.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/publisher-client-side.md index f08eabb35..f6647a2f0 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/publisher-client-side.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/publisher-client-side.md @@ -144,7 +144,7 @@ UID2 は、Client-Side のトークン生成機能を使用するために必要 パブリッシャーのテスト環境用に 1 セット、本番環境用に別のセットを用意します。 -SDK を設定するには、アカウントセットアップ時に受け取った **public key** と **subscription ID**、およびユーザーのハッシュ化またはハッシュ化していない [DII](../ref-info/glossary-uid.md#gl-dii)(メールアドレスまたは電話番号) を含むオブジェクトを指定して、以下のメソッドのいずれかを呼び出します: +SDK を設定するには、アカウントセットアップ時に受け取った **public key** と **Subscription ID**、およびユーザーのハッシュ化またはハッシュ化していない [DII](../ref-info/glossary-uid.md#gl-dii)(メールアドレスまたは電話番号) を含むオブジェクトを指定して、以下のメソッドのいずれかを呼び出します: * `__uid2.setIdentityFromEmail` * `__uid2.setIdentityFromEmailHash` @@ -217,7 +217,7 @@ await __uid2.setIdentityFromEmailHash( - UID2 SDK は、UID2 Service に送信する前にハッシュを暗号化します。 - + 以下の例では、UID2 SDK を電話番号で設定しています。 @@ -236,7 +236,7 @@ await __uid2.setIdentityFromPhone( - UID2 SDK は、暗号化されたハッシュを UID2 Service に送信する前に、電話番号をハッシュ化します。 - + 以下の例では、UID2 SDK をハッシュ化された電話番号で設定しています。 @@ -259,15 +259,15 @@ await __uid2.setIdentityFromPhoneHash( ## Token Storage and Refresh -[Configure the SDK for JavaScript](#configure-the-sdk-for-javascript) に記載されているメソッドのいずれかを正常に呼び出すと、[identity](../ref-info/glossary-uid.md#gl-identity) が生成され、`UID2-sdk-identity` というキーでローカルストレージに保存されます。SDK は UID2 Token を定期的にリフレッシュします。 +[Configure the SDK for JavaScript](#configure-the-sdk-for-javascript) に記載されているメソッドのいずれかを正常に呼び出すと、identity が生成され、`UID2-sdk-identity` というキーでローカルストレージに保存されます。SDK は UID2 Token を定期的にリフレッシュします。 -:::danger +:::warning ローカルストレージに保存されているオブジェクトのフォーマットは予告なく変更される可能性があります。ローカルストレージのオブジェクトを直接読み込んだり更新したり**しないこと**でください。 ::: ## Example Integration Code and When to Pass DII to the UID2 SDK -[identity](../ref-info/glossary-uid.md#gl-identity) がない状態で最初のページをロードする場合、トークン生成の呼び出しを開始するには、DII で `setIdentity` メソッドのいずれかを呼び出す必要があります。ID が生成されると、SDK からの `IdentityUpdated` イベントを待つことで、ビッドストリームに送信する Advertiser Token ([UID2 token](../ref-info/glossary-uid.md#gl-uid2-token)) を利用できるようになります。例として、`advertising_token_to_use` の値がどのように設定されるかを以下のコードスニペットで示します。 +identity がない状態で最初のページをロードする場合、トークン生成の呼び出しを開始するには、DII で `setIdentity` メソッドのいずれかを呼び出す必要があります。ID が生成されると、SDK からの `IdentityUpdated` イベントを待つことで、ビッドストリームに送信する Advertiser Token ([UID2 token](../ref-info/glossary-uid.md#gl-uid2-token)) を利用できるようになります。例として、`advertising_token_to_use` の値がどのように設定されるかを以下のコードスニペットで示します。 場合によっては、ユーザーの DII はページロード時に利用できず、DII の取得には何らかの関連コストがかかります。例えば、DII を取得するために API コールが必要な場合や、DII 情報を提供するためにユーザーにプロンプトが表示される場合があります。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/glossary-uid.md b/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/glossary-uid.md index e0992fdc5..2e65de6b5 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/glossary-uid.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/glossary-uid.md @@ -27,6 +27,7 @@ import MdxJumpAnchor from '@site/src/components/MdxJumpAnchor';
  • Advertising token
  • API key
  • API secret
    • +
  • App name
  • Authorization header
  • Bearer token
  • Client key
    • @@ -111,6 +112,9 @@ import MdxJumpAnchor from '@site/src/components/MdxJumpAnchor';
    API secret
    client secret を参照してください。
    +
    App name
    +
    In the context of mobile implementation, app name is a group term for the Android application ID, iOS app store ID, or iOS bundle identifier.
    +
    Authorization header
    Authorization header は、UID2 Service に対してクライアントを認証する方法です。
    詳細については、HTTP 仕様の RFC 9110 11.6.2. Authorization を参照してください。
    diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/sdks/client-side-identity.md b/i18n/ja/docusaurus-plugin-content-docs/current/sdks/client-side-identity.md index 120682e62..b1ac0c3ce 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/sdks/client-side-identity.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/sdks/client-side-identity.md @@ -437,7 +437,7 @@ UID2 ID をファーストパーティクッキーとローカルストレージ この関数が実行されると、[getAdvertisingToken()](#getadvertisingtoken-string) 関数は `undefined` を返し、[isLoginRequired()](#isloginrequired-boolean) 関数は `true` を返します。 -:::danger +:::warning SDK が正しいクッキーにアクセスするために `cookieDomain` または `cookiePath` を指定する必要があり、かつ `init` が完了していない場合、SDK はクッキーをクリアできません。この場合、エラーは発生しません。 ::: @@ -504,7 +504,7 @@ UID2 Cookie の内容は、[POST /token/generate](../endpoints/post-token-g } } ``` -:::danger +:::warning `private` オブジェクトの内容は明示的に指定されておらず、SDK が解釈するようになっています。このオブジェクトの構造、セマンティクス、互換性について、いかなる仮定もしないでください。クッキーの更新はその構造を保持しなければなりません。 ::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/sdks/uid2-sdk-ref-android.md b/i18n/ja/docusaurus-plugin-content-docs/current/sdks/uid2-sdk-ref-android.md index a674cb4cb..6aee8d4d3 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/sdks/uid2-sdk-ref-android.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/sdks/uid2-sdk-ref-android.md @@ -98,7 +98,7 @@ Android UID2 SDK をインストールするには、2 つの方法がありま Gradle を使用してインストールするには、build.gradle ファイルに依存関係として SDK を追加します: -``` javascript +```js implementation 'com.uid2:uid2-android-sdk:0.5.0' ``` @@ -182,7 +182,7 @@ Android の実装では、使用前にシングルトンを初期化します。 初期化は、次の例に示すように、APPLICATION インスタンスの生成時に行うことができます: -``` javascript +```js class MyApplication : Application() { override fun onCreate() { super.onCreate() @@ -197,12 +197,12 @@ class MyApplication : Application() { 初期 UID2 Identity を設定します: -``` javascript +```js UID2Manager.getInstance().setIdentity(identity: UID2Identity) ``` SDK に渡す UID2 Token (Advertising Token) を取得します: -``` javascript +```js UID2Manager.getInstance().getAdvertisingToken() ``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/sdks/uid2-sdk-ref-ios.md b/i18n/ja/docusaurus-plugin-content-docs/current/sdks/uid2-sdk-ref-ios.md index a8fdc6436..9a0d3f151 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/sdks/uid2-sdk-ref-ios.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/sdks/uid2-sdk-ref-ios.md @@ -91,9 +91,9 @@ Swift Package Manager (SPM) を使って iOS SDK をインストールします Package.swift に以下の依存関係を追加します: -``` javascript +```js dependencies: [ -.package(url: \"https://github.com/IABTechLab/uid2-ios-sdk.git\", from: "0.2.0"), + .package(url: "https://github.com/IABTechLab/uid2-ios-sdk.git", from: "1.2.0"), ] ``` @@ -167,12 +167,12 @@ identityStatus 変数は、SDK が管理している現在の UID2 Identity の 初期 UID2 Identity を設定します: -``` javascript +```js UID2Manager.shared.setIdentity(_ identity: UID2Identity) ``` Advertising SDK に渡す UID2 Token (Advertising Token) を取得します: -``` javascript +```js UID2Manager.shared.getAdvertisingToken() ``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/snippets/_mobile-docs-enable-logging.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/snippets/_mobile-docs-enable-logging.mdx new file mode 100644 index 000000000..3b043f47e --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/snippets/_mobile-docs-enable-logging.mdx @@ -0,0 +1,26 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +The UID2 SDK can generate logs, which could help in debugging any issues during UID2 integration work. To enable logging, do the following: + + + + +```js +// During UID2Manager initialization: +UID2Manager.init( + context = this, + isLoggingEnabled = true +) +``` + + + + +```swift +UID2Settings.shared.isLoggingEnabled = true +// On iOS, you must set UID2Settings before you first access UID2Manager.shared. Changes made to settings after first access are not read. +``` + + + \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/snippets/_mobile_docs_gmaima-plugin-gss.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/snippets/_mobile_docs_gmaima-plugin-gss.mdx new file mode 100644 index 000000000..572b42a49 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/snippets/_mobile_docs_gmaima-plugin-gss.mdx @@ -0,0 +1,32 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +If you intend to generate UID2 tokens to send to the [Google GMA SDK](https://developers.google.com/ad-manager/mobile-ads-sdk) or the [Google IMA SDK](https://developers.google.com/interactive-media-ads/), assuming you have followed the instructions in this guide, you must also add the UID2 GMA/IMA plugins into your mobile app. For instructions, refer to the applicable plug-in guide: + +- [UID2 GMA Plugin for Android Integration Guide](../guides/mobile-plugin-gma-android.md) +- [UID2 GMA Plugin for iOS Integration Guide](../guides/mobile-plugin-gma-ios.md) +- [UID2 IMA Plugin for Android Integration Guide](../guides/mobile-plugin-ima-android.md) +- [UID2 IMA Plugin for iOS Integration Guide](../guides/mobile-plugin-ima-ios.md) + +You do not need to explicitly make the `getAdvertisingToken()` method call to retrieve the advertising tokens and pass them into Google GMA/IMA SDK manually. The UID2 GMA/IMA plugins manage this for you. + +All you need to do is make sure that `getAdvertisingToken()` returns a non-null string object: + + + + +```js +UID2Manager.getInstance().getAdvertisingToken() +``` + + + + +```js +UID2Manager.shared.getAdvertisingToken() +``` + + + + +If the token exists, the Google GMA/IMA plug-ins can retrieve it automatically via the UID2 GMA/IMA plugins. \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/snippets/_private-operator-attest-failure.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/snippets/_private-operator-attest-failure.mdx new file mode 100644 index 000000000..45f10621e --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/snippets/_private-operator-attest-failure.mdx @@ -0,0 +1,8 @@ +## Private Operator Attestation Failure +When a private operator fails to attest with the core service, one of the following actions happens: +- HTTP 401 response. The Private Operator terminates itself immediately. + - Likely Causes: API key revoked or incorrect. +- Any other non-200 response code. The Private Operator continues to function for 12 hours. If the issue is not resolved in this time frame, it terminates itself. + - Likely Causes: Core service issues, network issues. + +Private Operator hosts must have infrastructure in place to handle alerting and restarting operators in the case of an error. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/snippets/_sdk-reduce-latency.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/snippets/_sdk-reduce-latency.mdx new file mode 100644 index 000000000..00ac1858f --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/snippets/_sdk-reduce-latency.mdx @@ -0,0 +1,7 @@ +By default, UID2 SDKs make API calls to a UID2 production environment server in the USA. Depending on where your users are based, you might consider choosing a server closer to your users to reduce latency. + +For example, a publisher in Singapore can set the base URL to `https://sg.prod.uidapi.com`. This is still the UID2 production environment, but the servers are in Singapore. + +For the list of valid base URLs, see [Environments](../getting-started/gs-environments). + +You can also set the base URL to `https://global.prod.uidapi.com`. This URL directs readers to a region geographically close to them, which is ideal if your audience is geographically distributed. \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 32d97a359..f5cf3def9 100644 --- a/sidebars.js +++ b/sidebars.js @@ -144,8 +144,9 @@ const fullSidebar = [ }, collapsed: true, items: [ - 'sdks/uid2-sdk-ref-android', - 'sdks/uid2-sdk-ref-ios', + 'guides/integration-mobile-overview', + 'guides/integration-mobile-client-side', + 'guides/integration-mobile-client-server', ], }, {