SDK Runtime API: integration guide

As you read through the Privacy Sandbox on Android documentation, use the Developer Preview or Beta button to select the program version that you're working with, as instructions may vary.

To help you with integration planning, this guide provides a comprehensive view of the integration process, which may include features that are not yet implemented at the current stage of the Privacy Sandbox on Android Developer Preview. In these cases, timeline guidance is provided.

The chart below displays the updated development workflow for the SDK Runtime integration. Sections listed in the same column can be worked on in parallel; for example, Partner Engagement can be done concurrently with setting up your test environment.

Visual diagram of the SDK Runtime integration workflow.
Figure 1: Workflow for the SDK Runtime integration.

Pre-Requisites and Setup

Completing this pre-work section ensures that you have a good understanding of the SDK Runtime and will set you up for meaningful results when using the API in the ad tech ecosystem.

Familiarize with the API

Begin by reading the Design Proposal to familiarize yourself with the SDK Runtime, its capabilities, and restrictions.

Read the Developer Guide to learn how to incorporate the code and API calls that you will need for your use cases.

Please submit any feedback you have for the documentation, especially regarding the open questions.

Sign up to receive updates on the Privacy Sandbox on Android. This will help you stay current on new features that are introduced in future releases.

Setup and test the sample app

Once you are ready to begin your integration, download the latest Developer Preview in Android Studio by following the instructions listed here. This guide requires using the latest Canary version of Android Studio. You can run this version of Android Studio in parallel to other versions you use, so please let us know if this requirement does not work for you.

Fork and run the code in our sample app to familiarize yourself with installing the RE SDK called “example-sdk” and the client app called “client-app” on a device or emulator ensuring that an example ad will load.

Adapt existing SDK to the SDK Runtime

The goal of this section is to implement functionality, such as showing a banner ad, from the existing SDK in a runtime enabled SDK (RE SDK), and set up communication between the app and RE SDK.

  • Create or update the sdk-example and sdk-implementation to implement functionality in the RE SDK.

  • Architecturally, consider adding the RE SDK as a dependency to the existing SDK, which acts as a wrapper. This allows the client app to continue calling the existing SDK, or the wrapper, directly. The wrapper SDK may route API calls based on different strategies outlined below.

Visual diagram of the System architecture after SDK Runtime integration.
Figure 2: System architecture after SDK Runtime integration.

For use cases requiring custom data, such as calling into the PPAPIs, an API definition will need to be created using IPC. Using the Android’s IBinder and AIDL, create a communication protocol to send information to the runtime-enabled SDK for any required information or actions that are necessary. More information in the SDK Runtime developer guide here.

Route traffic to the Runtime Enabled SDK

Routing strategies for API calls

Depending on your use cases, it’s recommended to route SDK calls through the existing SDK and the RE SDK code paths. This will help you implement A/B testing in the initial rollout. To ease app integration, this guide takes into account that the app will depend on the RE SDK and delegate to the existing SDK when appropriate. Consider the following strategies:

Route a percentage of SDK calls to the RE SDK

Only route a percentage of SDK calls to the RE SDK. Route the rest to the existing SDK code path. For example, consider this strategy for cases where you need to satisfy the SDK request once, such as displaying a banner ad.

  • Modify your existing SDK to route a percentage of requests to the RE SDK. For example, use a server-based dynamic configuration flag, such as Firebase Remote Config, to control the diversion criteria dynamically.
  • This essentially makes the existing SDK the only interface that the app interacts with and is in charge of routing SDK requests to the new RE SDK.
  • Your code should only redirect requests that can be handled by RE SDK. For example, verify that the ad format is supported by the SDK Runtime.
  • Follow these instructions to update your SDK code to interact with the RE SDK.

Pseudo code for routing logic:

void showAd(AdRequest request) {
  if (request.isBannerAd() && enableRuntimeSdkDiversion() == true) {
    // Call showAd() from the RE SDK
  } else {
    // Call showAd() using the existing SDK code path
  }
}

Route all SDK calls to both the existing and RE SDKs

Route all SDK calls to both the existing SDK code path and the RE SDK code path, on supported devices. Consider this strategy for cases where you need to exercise both existing and new code paths for comparison purposes. For example, compare conversion reporting results.

  • Modify your code to route all SDK calls to both the existing SDK code path and the RE SDK code path. You should verify the functionality is supported by the SDK Runtime and that the RE SDK is loaded successfully.

Pseudo code for routing logic:

void reportAttribution(AdRequest request) {
  if (request.isFeatureSupported() && isSdkLoaded() == true) {
    // Call RE SDK
  }

  // Call existing SDK code path
}

Closed beta for runtime-enabled SDK distribution

Google Play is offering a closed beta program for ads-related SDKs for developers who sign up for the Beta program and have performed local testing. If you are interested in taking part, sign up here.