Add iAB Standard Size Experiences to an Android app

Show tag-driven IAB ad slots in an Android app with the iAB Standard Size Experience SDK 0.v3.11.

The iAB Standard Size Experience SDK renders IAB ad units (Interactive Advertising Bureau standard sizes such as 300×250 and 320×50) as Jetpack Compose composables. You add four Gradle artifacts, initialize the SDK with your API key, and place one composable per ad slot with a tag ID. The SDK fetches the creative, plays video and audio ads through Google Interactive Media Ads (IMA), tracks impressions and viewability, and reports analytics on its own.

A tag ID identifies one ad placement configured in Brand Control Center, so campaigns, creatives, and targeting change without an app update. This page covers the native Android SDK. The React Native wrapper is described in Add iAB Standard Size Experiences to a React Native app.

Sizes are the published AAR files before their dependencies. Keep every artifact on the same version.

Requirements

You also need an API key and at least one tag ID. See Step 5.

Step 1: Add the repositories

The four artifacts are on Maven Central, and their dependencies come from Google's repository and Maven Central. Declare both in your project settings:

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
    // Only with com.begenuin:pangle-ads. Pangle isn't on Maven Central.
    maven {
      url = uri("https://artifact.bytedance.com/repository/pangle/")
      content { includeGroupByRegex("com\\.pangle.*") }
    }
  }
}

A POM can't declare a repository, so the app has to. Without the ByteDance repository, a build that includes pangle-ads fails to resolve com.pangle.global:pag-sdk.

Step 2: Add the dependencies

Declare one version and apply it to every artifact:

val genuinVersion = "0.v3.11"

dependencies {
  implementation("com.begenuin:genuin-sdk:$genuinVersion")
  implementation("com.begenuin:feed:$genuinVersion")
  implementation("com.begenuin:core-v3:$genuinVersion")
  implementation("com.begenuin:instream-ads:$genuinVersion")   // never imported; required at runtime
  // implementation("com.begenuin:pangle-ads:$genuinVersion")  // optional: Pangle fill
  // implementation("com.begenuin:gma-ads:$genuinVersion")     // optional: Google Mobile Ads fill
}

Three things about this block:

• Declare core-v3 yourself. feed lists it at runtime scope only. Without your own line, BGInstreamAdEvent and BGGeoLocationInfo aren't on the compile classpath and the build fails with an unresolved reference.
• instream-ads has no public API. core-v3 finds it through ServiceLoader at runtime. Without it, every slot renders "No ads available" and nothing is logged.
• The ad-network modules need no code. Add pangle-ads or gma-ads only if Genuin has enabled that network for your tags. Each module registers itself through META-INF/services; there's no initialization call. Don't add the Pangle or Google Mobile Ads SDKs yourself, because they arrive transitively at the versions the SDK is tested with.

The SDK brings Media3 1.9.1 (ExoPlayer, HLS, and the IMA extension), Compose BOM 2024.09.00, and Material 1.13.0. It also pulls in Retrofit 2.9.0, kotlinx.serialization 1.7.3, Coil 2.6.0, Lottie Compose 4.0.0, Dagger 2.59.2, and the RudderStack Kotlin SDK 1.1.0. If your app already uses any of these, Gradle resolves to the higher version.

After a sync, confirm the wiring with ./gradlew :app:dependencies --configuration releaseRuntimeClasspath. The tree must show the four com.begenuin artifacts and androidx.media3:media3-exoplayer-ima.

Step 3: Enable Java 17, Compose, and desugaring

Ad playback runs on Google IMA, which arrives through androidx.media3:media3-exoplayer-ima:1.9.1. IMA uses java.time, so each app module must enable core-library desugaring itself; Gradle doesn't inherit it from a library.

plugins {
  id("org.jetbrains.kotlin.plugin.compose")   // the Kotlin 2.x Compose compiler
}

android {
  buildFeatures { compose = true }
  compileOptions {
    isCoreLibraryDesugaringEnabled = true
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
  }
  kotlinOptions { jvmTarget = "17" }
}

dependencies {
  coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
}

Without desugaring, the build fails with Invoke-customs are only supported starting with Android O (--min-api 26), or the app crashes on the first ad with NoClassDefFoundError: Failed resolution of: Ljava/time/Duration;.

Step 4: Configure the manifest

The library manifests don't declare network permissions. Add both to your AndroidManifest.xml, and register the Application subclass you'll initialize from:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<application android:name=".MyApp">
  <!-- your activities -->
</application>

ACCESS_NETWORK_STATE backs the SDK's connectivity check. It also arrives transitively today, so declare it anyway in case those dependencies change.

Two things merge in from the SDK without any work on your side:

• The advertising ID permission. instream-ads declares com.google.android.gms.permission.AD_ID to resolve the [DID], [LIMITED_AD_TRACKING], and [DNT] macros in VAST tags. It's granted at install with no prompt. Declare advertising-ID use in the Play Console Data safety form, or the submission is rejected. To drop the permission, and with it those macros, add <uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove" />.
• Two activities. BGFullScreenActivity from feed presents fullscreen playback, and WebViewActivity from core-v3 opens CTA landing pages in an in-app browser.

Ad assets travel over HTTPS, so no network-security-config or usesCleartextTraffic is needed. The SDK never shows a consent or tracking prompt. In a GDPR or ePrivacy region, collect consent through your own consent management platform before you request ads.

Step 5: Get your credentials

Keys aren't shared between environments: a Live key with GenuinEnv.QA returns no ads. Keep the key out of source control. Inject it from local.properties into a BuildConfig field, from a Gradle secrets plugin, or from your CI secrets.

Step 6: Initialize the SDK

Call GenuinSDK.initialize once, in Application.onCreate, before any ad slot composes. A slot that composes first throws IllegalStateException: SDK not initialized.

import android.app.Application
import com.begenuin.core.enums.GenuinEnv
import com.begenuin.core.model.AudioBehaviorConfig
import com.begenuin.core.model.AudioFocusLossHandling
import com.begenuin.sdk.GenuinSDK

class MyApp : Application() {
  override fun onCreate() {
    super.onCreate()
    GenuinSDK.initialize(
      context = this,
      apiKey = BuildConfig.GENUIN_API_KEY,   // injected at build time, never a literal
      env = GenuinEnv.PROD,                  // GenuinEnv.QA only with a QA key
      fontFamily = "",                       // optional
      audioBehaviorConfig = AudioBehaviorConfig(
        duckVolumeDuringTransientCanDuck = 0.15f,
        focusLossHandling = AudioFocusLossHandling.MUTE_OUTPUT
      )
    )
    GenuinSDK.setLoggingEnabled(BuildConfig.DEBUG)
  }
}

AudioBehaviorConfig has two fields:

setLoggingEnabled(true) turns on the SDK's diagnostic log under the GenuinSDK logcat tag. The log is off in every published build whatever your own build type, and errors are logged either way. Gate it on debug builds, because the log names your tag IDs.

Step 7: Display an ad

Pick the composable that matches the slot size, place it in your layout, and pass the tag ID. The SDK requests the feed, renders the creative, and tracks the impression.

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import com.begenuin.feed.views.BG300x250AdView

@Composable
fun ArticleScreen() {
  Column {
    ArticleBody()
    BG300x250AdView(
      tagId = "{{TAG_ID}}",
      modifier = Modifier.fillMaxWidth(),
    )
  }
}

All eight ad views share one signature:

@Composable
fun BG300x250AdView(
  tagId: String,
  modifier: Modifier = Modifier,
  uniqueId: String = "",
  geoLocation: BGGeoLocationInfo? = null,
  onEvent: (BGInstreamAdEvent) -> Unit = {},
)

The slot keeps its declared size in every state, so your layout doesn't shift while the ad resolves. It shows a shimmer while loading, the ad pager once the feed resolves, and a dark box reading "No ads available" when it doesn't. The SDK never collapses an empty slot. To reclaim the space, handle NoAds in onEvent and hide the container yourself.

Host an ad in a View-based screen

Wrap the composable in a ComposeView. Your module still needs the Compose plugin and buildFeatures { compose = true } from Step 3.

<androidx.compose.ui.platform.ComposeView
    android:id="@+id/adSlot"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

findViewById<ComposeView>(R.id.adSlot).setContent {
  BG320x50AdView(tagId = "{{TAG_ID}}")
}

The composition must run inside an Activity. Fullscreen and the CTA link-out read LocalContext as an Activity; with an application context the fullscreen button has no effect and the link-out throws.

Ad formats

Seven formats render at their IAB size in dp regardless of the container. A host narrower than the slot clamps it rather than letting it overflow. Give each placement at least the slot's width: 320 dp for the 320-wide slots and 300 dp for the 300-wide ones.

BGFSLandscapeAdView honours the ratio you ask for between 1.25:1 and 2.4:1. A box outside that band is letter-boxed or pillar-boxed to the nearest allowed ratio, so the slot can render smaller than its box.

The eight formats map to three presentations, chosen by the composable you place:

Fullscreen, mute, and play/pause controls appear in every size unless the tag's configuration in Brand Control Center hides them. The two landscape formats skip the loading shimmer and stay on a plain backdrop until the ad is ready.

Step 8: Supply geo targeting (Optional)

By default, the SDK derives the viewer's location from the request IP, so there's nothing to do. If your app knows the location more precisely, pass it, and each field you set replaces the IP-derived value. Most apps set it once, app-wide, wherever the location becomes known:

import com.begenuin.core.model.BGGeoLocationInfo
import com.begenuin.sdk.GenuinSDK

GenuinSDK.setGeoLocation(
  BGGeoLocationInfo(
    country = "US",
    region = "NY",
    city = "New York",
    dmaCode = "501",
    latitude = 40.7128,
    longitude = -74.0060,
  )
)

setGeoLocation is independent of initialize: call it before or after slots compose, from any thread, as often as the value changes. Pass null to clear it. For one placement that needs different targeting, pass geoLocation to that ad view; its fields win over the app-wide value one by one.

Three rules govern how values resolve. The slot's geoLocation wins over the app-wide value, which wins over the IP lookup, field by field; a null or blank field falls through to the next source. Each ad request reads the geo current when it builds its URL, so a late location still reaches every request that hasn't gone out, prefetched ones included. Requests already in flight keep their geo; no ad is re-requested.

Setting both latitude and longitude also reports the geo type ([USER_GEO_TYPE], [DEVICE_GEO_TYPE]) as device location rather than IP-derived. The SDK never asks for the location permission and never reads device location itself. If you pass coordinates, your app owns the permission, the consent, and the matching Data safety declaration.

Step 9: Observe lifecycle events

Pass an onEvent lambda to any ad view. The SDK emits BGInstreamAdEvent values as the slot loads its feed and plays through its ads:

BG300x250AdView(
  tagId = "{{TAG_ID}}",
  onEvent = { event ->
    when (event) {
      BGInstreamAdEvent.Loading -> {}                 // feed request started
      is BGInstreamAdEvent.Loaded -> {}               // event.count ads to play
      BGInstreamAdEvent.NoAds -> hideAdContainer()    // reclaim the space yourself
      is BGInstreamAdEvent.Appeared -> {}             // ad event.index of event.total is on screen
      is BGInstreamAdEvent.Started -> {}              // playback began
      is BGInstreamAdEvent.Completed -> {}            // this ad played to the end
      is BGInstreamAdEvent.Changed -> {}              // pager moved event.from -> event.to
      is BGInstreamAdEvent.LoadTimeout -> {}          // still loading after event.timeoutMs
      is BGInstreamAdEvent.NoFill -> {}               // this ad's waterfall produced nothing
      is BGInstreamAdEvent.AllAdsCompleted -> {}      // nothing left to play in the slot
      is BGInstreamAdEvent.Collapsed -> {}            // event.isCollapsed is the new state
    }
  },
)

BGInstreamAdEvent is a sealed interface with 11 cases. Ad positions are 1-based.

type labels the kind of ad the slot led with. The values are audio (a VAST audio ad), external (filled by Pangle or Google Mobile Ads), sponsored (a sponsored post), video (a video-content ad), and unknown. Mute changes, Watch and CTA taps, and fullscreen enter and exit aren't surfaced as events; the SDK reports them through its own analytics (see Analytics events).

Step 10: Keep ads working in release builds

The 0.v3.11 AARs ship no consumer ProGuard rules; their proguard.txt files are empty. Two mechanisms inside the SDK break under R8 full mode, the default since AGP 8. The ServiceLoader registrations in META-INF/services name provider classes as text, and Retrofit reflects on generic signatures that R8 strips. The symptom is "No ads available" in release builds only, with ClassCastException: java.lang.Class cannot be cast to java.lang.reflect.ParameterizedType in logcat and an "Ad feed request returned no data" line after a few milliseconds.

Add these rules to your app's proguard-rules.pro:

#--- iAB Standard Size Experience SDK: providers and serializers are resolved by class name
-keep class com.begenuin.** { *; }
-keep interface com.begenuin.** { *; }
-dontwarn com.begenuin.**

#--- Google IMA (VAST playback)
-keep class com.google.ads.interactivemedia.** { *; }
-dontwarn com.google.ads.interactivemedia.**

#--- Retrofit under R8 full mode: keep the generic signatures it reflects on
-keep,allowobfuscation,allowshrinking interface retrofit2.Call
-keep,allowobfuscation,allowshrinking class retrofit2.Response
-keep,allowobfuscation,allowshrinking class kotlin.coroutines.Continuation
-keepattributes Signature, InnerClasses, EnclosingMethod, RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface <1>

These are the rules the React Native wrapper ships as consumer rules and checks against a minified release build. The broad com.begenuin.** keep trades APK size for certainty. Verify ad rendering in a build with isMinifyEnabled = true before you release.

Troubleshooting

App size

Media3 and the Google IMA SDK add to that, and are shared if your app already uses them. The optional pangle-ads and gma-ads modules each add their network's SDK. Enabling R8 reduces all of these figures.

Analytics events

The SDK reports the ad lifecycle through its own analytics pipeline (RudderStack) with no wiring on your side. It sends 21 events, which appear in Brand Control Center reporting and in any analytics destination you connect.

Limitations

• Android only, API 24 and later: there's no View-based ad view; View apps host the composables in a ComposeView.
• One version for all artifacts: genuin-sdk, feed, instream-ads, and core-v3 must share a version, and a + range resolves to the wrong artifact.
• Fixed slot sizes: seven formats draw at their IAB dp size and clamp in a narrower host; only BGFSLandscapeAdView adapts, and only between 1.25:1 and 2.4:1.
• No pause or resume API: playback follows the Android lifecycle of the host Activity.
• No consumer ProGuard rules in 0.v3.11: add the rules in Step 10 or release builds show no ads.
• Pangle is arm-only and always personalised: it never fills on x86 emulators, and the module requests personalised ads without a consent signal. Talk to Genuin before shipping Pangle in a consent region.
• Empty slots stay on screen: the SDK doesn't collapse a slot with no ads; handle NoAds yourself.

See also

• Add iAB Standard Size Experiences to a React Native app
• Add iAB Standard Size Experiences to an iOS app
• Integrate the Genuin Android SDK
• How the Genuin SDK renders ads