Integrate the Genuin Ad SDK for Android

Integrate IAB-compliant, tag-driven advertisements into your Android application using the Genuin Ad SDK.

The SDK enables publishers and brands to seamlessly display interactive advertising experiences within their native applications while maintaining complete control over ad placement, campaign management, and user engagement.

Whether you're embedding a compact banner, a medium rectangle, a half-page unit, or a collapsible rich media unit, the SDK provides a lightweight integration that automatically handles ad delivery, rendering, playback, and lifecycle management.

This guide walks through every step, from adding the SDK to displaying your first advertisement and monitoring ad events.

Who should use this guide?

This guide is intended for:

- Android developers integrating Genuin advertising into mobile applications

- Engineering teams implementing IAB-compliant advertising

- Publishers monetizing applications with managed advertising inventory

- Brands delivering sponsored experiences across their mobile properties

What you'll learn

By the end of this guide, you'll know how to:

- Add the Genuin Ad SDK to your project with Gradle

- Configure the required Google Interactive Media Ads (Media3 IMA) prerequisites

- Initialize the SDK correctly

- Display responsive advertisement units

- Deliver campaigns using Tag IDs

- Observe advertisement lifecycle events

- Handle loading failures gracefully

- Integrate advertisements into both Jetpack Compose and View/XML-based applications

Before you begin

Throughout this guide you'll encounter two placeholder values that should be replaced with credentials from your own Genuin account.

These credentials authenticate your application and determine which advertisements are displayed.

Table of contents

1. Requirements

2. What the SDK provides

3. Add the SDK with Gradle

4. Configure the Google Interactive Media Ads prerequisites

5. Verify the dependency wiring

6. Configure your application

7. Retrieve your credentials

8. Initialize the SDK and protect your API key

9. Display an ad

10. Supported ad formats

11. Tag-based advertisement delivery

12. Observe advertisement lifecycle events

13. Error handling

14. Using the SDK from a View or XML-based app

15. App size impact

16. Troubleshooting

17. Support

18. Appendix: Analytics events

1. Requirements

Before integrating the SDK, verify that your development environment satisfies the following requirements.

2. What the SDK provides

The SDK is distributed as a set of Android library modules. Four are relevant to an IAB ads integration.

All four must be declared as dependencies. iab-ads exposes no public API of its own: it is resolved at runtime through Java's ServiceLoader , so it must be on the runtime classpath even though your code never references it. Everything you write goes through the ad views.

Once integrated, the SDK provides six ready-to-use Compose advertisement components, one per IAB size.

Each view fixes its own size, so you never pass a size argument — you pick the composable that matches the placement. All six share the same parameter list and automatically manage:

- Advertisement retrieval

- Media playback

- Creative rendering

- Impression and viewability tracking

- User interaction (mute, play/pause, fullscreen, collapse)

- Lifecycle management

allowing developers to integrate advertising with minimal implementation effort.

3. Add the SDK with Gradle

Step 1: Declare the repositories in settings.gradle.kts. The SDK is served from JitPack, and its transitive dependencies (Media3/IMA, Compose, etc.) come from Google's and Maven Central repositories:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { setUrl("https://jitpack.io") }
    }
}

Step 2: Add the SDK artifacts to your app module's build file. All four modules share a single version — use the latest available release.

Kotlin DSL (build.gradle.kts):

val genuinVersion = "<latest-version>"

dependencies {
    implementation("com.begenuin:genuin-sdk:$genuinVersion")   // initialization
    implementation("com.begenuin:feed:$genuinVersion")         // the ad views
    implementation("com.begenuin:iab-ads:$genuinVersion")      // ad runtime (ServiceLoader-discovered)
    implementation("com.begenuin:core-v3:$genuinVersion")      // BGInstreamAdEvent, GenuinEnv
}

Groovy DSL (build.gradle):

def genuinVersion = "<latest-version>"

dependencies {
    implementation "com.begenuin:genuin-sdk:$genuinVersion"
    implementation "com.begenuin:feed:$genuinVersion"
    implementation "com.begenuin:iab-ads:$genuinVersion"
    implementation "com.begenuin:core-v3:$genuinVersion"
}

All four are required. core-v3 carries the public types you reference in your own code, and iab-ads is never imported directly but must be on the classpath or no ads will resolve.

Step 3: Sync Gradle. The remaining transitive dependencies (Media3 / Google IMA, Compose runtime, etc.) resolve automatically.

4. Configure the Google Interactive Media Ads prerequisites

Advertisement playback relies on Google Interactive Media Ads (IMA). IMA arrives transitively through androidx.media3:media3-exoplayer-ima:1.9.1 , which the SDK already depends on - so you do not add a separate IMA dependency or link anything by hand.

What you do have to add is Java 8+ core-library desugaring. This is a build-configuration setting, and Gradle cannot inherit it transitively from a library - each app module must enable it itself. This step is mandatory.

If desugaring is missing, the build fails or the app crashes when an ad renders, with an error similar to:

Invoke-customs are only supported starting with Android O (--min-api 26)

java.lang.NoClassDefFoundError: Failed resolution of: Ljava/time/Duration;

Enable desugaring in your app module's build.gradle.kts :

android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

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

Why this dependency is required

The Google IMA SDK is responsible for:

- Video advertisement playback

- Audio advertisement playback

- Interactive advertisement rendering

- Media controls

- Playback lifecycle

Without it, Genuin advertisement components cannot function.

5. Verify the dependency wiring

After a successful Gradle sync, confirm that the SDK modules and their transitive dependencies resolved:

./gradlew :app:dependencies --configuration releaseRuntimeClasspath

Confirm the following appear in the tree:

• com.begenuin:genuin-sdk
• com.begenuin:feed
• com.begenuin:iab-ads
• com.begenuin:core-v3
• androidx.media3:media3-exoplayer-ima

No additional embedding or packaging configuration is necessary — Gradle handles AAR merging, manifest merging, and resource merging during the build.

6. Configure your application

Add the internet permission

The SDK requires network access, and the library modules do not declare these for you. Add both to your app's AndroidManifest.xml :

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

ACCESS_NETWORK_STATE backs the SDK’s connectivity check. It currently also arrives transitively from the advertising dependencies, so an app can appear to work without declaring it — declare it anyway, so the SDK keeps working if those transitive dependencies change.

Advertising ID

The com.google.android.gms.permission.AD_ID permission is declared by the BGInstreamAds module and merged into your manifest automatically. It is used to resolve the advertising-ID macros ([DID], [LIMITED_AD_TRACKING], [DNT]) in VAST tags for measurement and attribution. It is granted at install time with no runtime prompt.

If your app’s privacy posture requires it, you may remove the permission with a manifest-merger override — but doing so degrades ad measurement:

<uses-permission android:name="com.google.android.gms.permission.AD_ID"
    tools:node="remove" />

Activities

The SDK’s activities (fullscreen ad presentation, in-app web view for CTA landing pages) are declared in the library manifests and merge into your app automatically. Nothing needs to be added.

Network configuration

Advertisement assets are delivered securely over HTTPS. Because Android blocks cleartext traffic by default on API 28+ and the SDK makes no cleartext requests:

• No custom network-security-config is required.
• android:usesCleartextTraffic="true" should not be enabled for standard advertisement delivery.

Privacy and consent

The SDK does not present any tracking-permission prompt, and Android requires none. Instead:

• Declare your advertising-ID usage in your Play Console Data safety form.
• If you operate in a region requiring consent (GDPR/ePrivacy, and similar), surface that consent through your own CMP and privacy policy before requesting ads.

7. Retrieve your credentials

Before initializing the SDK, obtain your application credentials. You’ll need two values.

8. Initialize the SDK and protect your API key

Although the SDK API Key is intended for client-side authentication, it should still be stored securely. Recommended approaches include:

• local.properties → BuildConfig fields
• Gradle build types / product flavors, or a secrets Gradle plugin
• Environment-specific configuration
• CI/CD secrets

Avoid committing API keys directly into source repositories.

Call GenuinSDK.initialize(...) exactly once during the application launch sequence. The natural place is your Application subclass:

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

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()

        GenuinSDK.initialize(
            context = this,
            apiKey = BuildConfig.GENUIN_API_KEY, // injected at build time — do not hardcode
            env = GenuinEnv.PROD,                // GenuinEnv.PROD or GenuinEnv.QA
        )
    }
}

Register your Application subclass in the manifest:

<application android:name=".MyApp" ...>

initialize accepts two optional parameters:

Display your first IAB advertisement

After initializing the SDK, displaying an advertisement only requires adding one of the ad views to your Compose hierarchy. Each ad slot automatically:

• Connects to the Genuin platform
• Retrieves creatives associated with the supplied Tag ID
• Handles media playback
• Tracks impressions and engagement
• Manages the complete ad lifecycle

Simply place the ad view wherever you want advertisements to appear inside your layout.

9. Display an ad

The ad views are ordinary composables. Pick the one matching the size you want, place it anywhere in your UI, pass a Tag ID, and the SDK fetches and renders the associated creative without any additional implementation:

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.BGInstream300x250AdView

@Composable
fun ArticleScreen() {
    Column {
        // ... your content ...

        BGInstream300x250AdView(
            tagId = "YOUR_TAG_ID",
            modifier = Modifier.fillMaxWidth(),
        )

        // ... more content ...
    }
}

All six ad views share the same signature:

@Composable
fun BGInstream300x250AdView(                        // or Collapsible / 320x480 / 300x600 / 320x100 / 320x50
    tagId: String,                                  // required — the IAB tag to load
    modifier: Modifier = Modifier,
    uniqueId: String = "",                          // disambiguates multiple slots for the same tag on one screen
    onEvent: (BGInstreamAdEvent) -> Unit = {},      // optional lifecycle callback sink
)

10. Supported ad formats

The SDK provides six built-in ad sizes, one composable per size, optimized for different placement scenarios.

Each slot renders at its declared IAB size in dp — a BGInstream320x50AdView occupies exactly 320 × 50 dp regardless of how wide its container is. You don't compute a height or set a size; just place the view where the ad belongs. A host narrower than the slot clamps it rather than letting it overflow, so give the placement at least the slot's width — 320 dp for the 320-wide slots (including the new 320 × 480 half-page) and 300 dp for the 300-wide ones.

Collapse is user-initiated only — there is no auto-collapse timer, and only BGInstreamCollapsibleAdView collapses. The half-page slots (320 × 480, 300 × 600) render at a fixed height like every other non-collapsible size.

How each size presents a creative
The six sizes route to two presentations. You don't choose the presentation — it follows from the composable you place.

The two half-page sizes use the same full-bleed presentation as the 300 × 250, scaled to the taller slot — the caption width and the control-bar buttons are sized from the slot's own dimensions, so nothing is cropped or stretched. Fullscreen, mute, and play/pause are available in every size.

Examples:

BGInstream300x250AdView(tagId = "YOUR_TAG_ID")

BGInstreamCollapsibleAdView(tagId = "YOUR_TAG_ID")

BGInstream320x480AdView(tagId = "YOUR_TAG_ID")

BGInstream300x600AdView(tagId = "YOUR_TAG_ID")

BGInstream320x100AdView(tagId = "YOUR_TAG_ID")

BGInstream320x50AdView(tagId = "YOUR_TAG_ID")

No manual size calculations are required.

11. Tag-based advertisement delivery

Advertisements are loaded using a Tag ID generated from the Genuin platform. Every ad view takes a tagId and the creative is resolved server-side:

// Resolve a feed from a Genuin ad tag:
BGInstream300x250AdView(tagId = "YOUR_TAG_ID")

There is no direct-ad-URL parameter on the ad view. Tag IDs let advertisements be managed entirely from the Brand Control Center without requiring application updates.

Benefits include:

• Dynamic campaign management
• Remote creative updates
• Audience targeting
• Placement optimization
• Campaign reporting

12. Observe advertisement lifecycle events

Applications often need to react to advertisement events such as an ad loading, an impression starting, or the active creative changing.

Pass an onEvent lambda to any ad view; the SDK emits a stream of BGInstreamAdEvent values as the slot loads its feed and plays through the reels:

BGInstream300x250AdView(
    tagId = "YOUR_TAG_ID",
    onEvent = { event ->
        when (event) {
            BGInstreamAdEvent.Loading -> { /* feed began loading */ }
            is BGInstreamAdEvent.Loaded -> { /* event.count renderable reels */ }
            BGInstreamAdEvent.NoAds -> { /* no renderable ads — collapse the slot, etc. */ }
            is BGInstreamAdEvent.Appeared -> { /* reel event.index of event.total became active */ }
            is BGInstreamAdEvent.Started -> { /* playback started for reel event.index */ }
            is BGInstreamAdEvent.Changed -> { /* active reel moved event.from -> event.to */ }
            is BGInstreamAdEvent.NoFill -> { /* reel event.index tried but did not fill */ }
        }
    },
)

Full event reference

BGInstreamAdEvent is a sealed interface with seven cases:

Reel positions are 1-based. type is a human-readable label for the reel kind — "audio" for an audio ad reel, "sponsored" for a sponsored post, "video" for a video-content ad, or "unknown" if the SDK doesn't recognise the reel type.

Scope of the public event set. These seven events cover feed loading and reel transitions. Media completion, mute-state changes, Watch and CTA taps, fullscreen enter/exit, and expand/collapse are handled internally by the SDK and reported through its own analytics pipeline; they are not surfaced as public events.

Because onEvent is a Compose lambda rather than a retained delegate, there is no weak/strong-reference bookkeeping to manage — you don’t need to hold a reference to a listener object.

13. Error handling

The SDK is designed to fail gracefully and preserve your layout rather than surface error objects to the host app.

What the slot renders in each state

The ad slot always occupies its declared size in dp, in every state, so your layout does not shift as the ad resolves:

If you don’t want an empty slot occupying space, handle NoAds in onEvent and hide or resize the container yourself — the SDK will not collapse it for you.

Failure causes

14. Using the SDK from a View or XML-based app

Although the ad view is built with Jetpack Compose, View/XML applications can integrate it using ComposeView.

Display the ad view inside a View hierarchy

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

// In an Activity or Fragment:
findViewById<ComposeView>(R.id.adSlot).setContent {
    BGInstream320x50AdView(
        tagId = "YOUR_TAG_ID",
    )
}

Your app module still needs the Compose Gradle plugin and buildFeatures { compose = true } even if the rest of your UI is Views.

Initialize the SDK in your Application class

SDK initialization still belongs in your Application subclass.

15. App size impact

Integrating the Genuin Ad SDK introduces a modest increase in application size.

If your app already integrates Google IMA or ExoPlayer/Media3 elsewhere, that portion is shared. The figures come from an unminified release build; enabling R8 reduces them.

16. Troubleshooting

Build fails or the app crashes when an ad renders

Error — messages mentioning Invoke-customs, java.time, or a NoClassDefFoundError for a java.* class.

Cause — core-library desugaring is not enabled in the app module.

Resolution — enable isCoreLibraryDesugaringEnabled and add the coreLibraryDesugaring(...) dependency.

“No ads available” placeholder appears

1. Confirm the com.begenuin:iab-ads dependency is declared — without it, no ad runtime is discovered.
2. Confirm GenuinSDK.initialize(...) runs at app launch, before any ad slot composes.
3. Confirm your apiKey is correct and non-empty, and that env matches the environment your tag lives in.
4. Confirm the tagId is non-blank, valid, and active in your dashboard.
5. Add an onEvent handler and log the events — NoAds with no preceding Loading indicates a blank tagId; NoFill indicates the tag resolved but a reel’s waterfall produced no fill.

Ads never load and no network requests are made

Cause — the INTERNET permission is missing. The SDK’s library manifests do not declare it.

Resolution — add <uses-permission android:name="android.permission.INTERNET" /> to your app manifest.

Ads work in debug but not in a minified release build

Cause — R8 removed the ServiceLoader provider implementations or the META-INF/services registrations used for module discovery. The SDK currently ships empty consumer-rules.pro files, so it contributes no keep rules to protect them.

Resolution — verify ad rendering in a minified build early. If slots go empty only when isMinifyEnabled = true, retain the ads provider registration and implementation classes in your app’s proguard-rules.pro, and report the case to Genuin support so the rules can be shipped with the SDK.

Fullscreen doesn’t open when the user taps the expand control

Cause — the composable is hosted in a Compose tree whose context is not an Activity.

Resolution — host the ad slot inside an Activity-backed composition.

Build error: unresolved reference to BGInstreamAdEvent

Cause — the core-v3 artifact is missing. The public event type lives there and is not re-exported by feed.

Resolution — add the com.begenuin:core-v3 dependency.

Dependency resolution fails

Cause — google(), mavenCentral(), or the Genuin repository is missing from settings.gradle.kts.

Resolution — declare all required repositories in settings.gradle.kts.

17. Support

For additional assistance during integration:

Documentation

Access your organization’s Genuin documentation and developer resources at begenuin.com/developers.

Dashboard

Retrieve credentials, manage ad tags, and configure placements through the Brand Control Center at brands.begenuin.com.

Contact support

When opening a support request, include:

• Project / Brand ID
• SDK version
• Android Gradle Plugin and Gradle versions
• Android OS version and device model (or emulator image)
• The Tag ID and the ad view (size) of the affected slot
• Complete error message
• Relevant Logcat output

Providing this information helps the Genuin engineering team diagnose and resolve issues more efficiently.

18. Appendix: Analytics events

The SDK automatically reports IAB ad lifecycle analytics through its telemetry pipeline (RudderStack) — you don’t wire anything up. The 15 events are: