Build and consume a Runtime-Enabled SDK

1
 Key concepts
2
 Set up your development environment
3
 Build an RE SDK
4
 Consume the RE SDK
5
 Testing, and building for distribution

Build and configure a test app

This section explains how to set up and prepare an app to consume a runtime-enabled SDK for local testing.

Prepare your app

First, create a separate standalone project or module.

In this scenario, the app does not contain the SDK code; it declares it as a Maven dependency instead.

Building an app that consumes a Runtime Enabled SDK requires Android Studio Ladybug Canary 1 or later, and Android Gradle Plugin (AGP) 8.7.0-alpha01 or later.

  1. Follow the same steps as described previously to set up your development environment and device/emulator for testing.

  2. Enable the SDK Runtime using the flag described in Step 3: Prepare your SDK section.

    # This enables the Privacy Sandbox for your project on Android Studio.
android.experimental.privacysandboxsdk.enable=true
android.experimental.privacysandboxsdk.requireServices=false

  3. Add the Privacy Sandbox Maven URL to your project's top-level build.gradle file.

        allprojects {
        repositories {
            google()
            maven {
                url "https://maven.privacysandbox.com/v1/repository"
                }
            }
        }

  4. Keep the Maven dependency on the existing ad library (your runtime-aware SDK) Maven target.

  5. Add a privacySandbox block to the project build.gradle with a dependency on the SDK library and set enable true

    plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
}

android {
    //...
    privacySandbox {
        enable true
    }
    //...
}

dependencies {
    // SDK library dependency
    implementation(<maven coordinates to SDK library>)
}

  6. The app can now use the SDK's APIs in the same way as explained in the API consumption section.

Build your app

You can build your apps as an Android App Bundle (AAB) as you normally would.

Test your SDK locally

To run your test app, install the runtime enabled SDK and app onto your test device or emulator using Android Studio.

  1. Open the Android Studio project for your test app.
  2. Go to Run > Edit Configurations. The "Run/Debug" Configuration window appears. You can deploy as "Default APK" or "APK from Bundle".
  3. Under Launch Options, set Launch to Specified Activity.
  4. Click the three-dot menu next to Activity and select the Main Activity for your client.
  5. Click Apply and then OK.
  6. Click Run to install the client app and SDK on your test device.

Build your SDK for distribution

You need to build your SDK as an Android SDK Bundle (ASB) before you can publish it to an app store. ASB is a non-signed publication package equivalent to Android App Bundles.

The ASB, or its derivative the Android SDK Archive (ASAR), together with the app's AAB are turned by Bundletool into a set of installable APKs. App developers can use BundleTool directly in Android Studio (currently Canary version) to output all APK variants.

Bundletool takes an AAB and an ASB and can output a set of APK variants:

  1. An APK built for running in SDK Runtime backward compatible mode, for devices that aren't compatible with the SDK runtime (Android 13 and below). This APK contains all the code needed for both the app and the SDK.
  2. An APK built for running SDK Runtime mode for devices compatible with the SDK Runtime (Android 14 and above). This APK contains only the app code, with API stubs for the runtime-enabled SDK.
  3. The SDK APK with the runtime-enabled SDK code, aimed to be installed before the app APK described in the previous step.

You can build an ASB in two ways:

  • Android Studio
    1. Build your project. This can be done by calling Build > Rebuild project.
    2. The ASB file lives in your runtime-enabled ASB module under build/outputs/asb/single/<your-asb-module-name>.asb
  • Bundletool's command line - follow these instructions.

The SDK has to be signed with an upload key before you can publish it. Use this upload key to sign your ASB for upload to the SDK Console. Google uses the upload certificate to verify your identity.

The following steps are an overview of what you need to do to sign your ASB:

  1. Generate a keystore and upload key. This is identical to generating a keystore and upload key for apps.
  2. Sign your ASB with the upload key. To do this, add a signingConfig block to your build.gradle file specifying the newly created key and the keystore:
android {
  signingConfig {
    storeFile file(path-to-keystore.jks)
    storePassword "keystorePassword"
    keyAlias "UploadKey"
    keyPassword "keyPassword"
  }
}

App stores can develop different strategies to use these components to support Runtime-Enabled app distribution. SDK Runtime is continuously working with app stores to extend the support for runtime-enabled SDKs.

Step 4: Consume the runtime-enabled SDK