Android Integration (AdMob)

This guide shows you how to integrate the Orivia SDK with Google AdMob in Android

Import Dependencies

Add the Orivia Maven repository, then the core SDK and AdMob mediation module:

Kotlin DSLGroovy DSL

repositories {
    maven { url = uri("https://raw.githubusercontent.com/orivia-ai/orivia-maven/main") }
}

dependencies {
    implementation("ai.orivia:monetization:1.19.0")
    implementation("ai.orivia:mediation-admob:1.19.0")
}

repositories {
    maven { url "https://raw.githubusercontent.com/orivia-ai/orivia-maven/main" }
}

dependencies {
    implementation "ai.orivia:monetization:1.19.0"
    implementation "ai.orivia:mediation-admob:1.19.0"
}

Define Ad Unit IDs

Declare your Orivia publisher ID and ad unit IDs:

KotlinJava

private const val ADMOB_APP_ID = "YOUR_ADMOB_APP_ID"
private const val ORIVIA_PUBLISHER_ID = "YOUR_ORIVIA_PUBLISHER_ID"

private const val INTERSTITIAL_AD_UNIT_ID = "YOUR_INTERSTITIAL_AD_UNIT_ID"
private const val REWARDED_AD_UNIT_ID = "YOUR_REWARDED_AD_UNIT_ID"
private const val BANNER_AD_UNIT_ID = "YOUR_BANNER_AD_UNIT_ID"

private static final String ADMOB_APP_ID = "YOUR_ADMOB_APP_ID";
private static final String ORIVIA_PUBLISHER_ID = "YOUR_ORIVIA_PUBLISHER_ID";

private static final String INTERSTITIAL_AD_UNIT_ID = "YOUR_INTERSTITIAL_AD_UNIT_ID";
private static final String REWARDED_AD_UNIT_ID = "YOUR_REWARDED_AD_UNIT_ID";
private static final String BANNER_AD_UNIT_ID = "YOUR_BANNER_AD_UNIT_ID";

Initialize AdMob & Orivia

Info

Orivia's AdMob mediation module targets the GMA Next-Gen SDK (com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk), not the legacy com.google.android.gms:play-services-ads. If you're integrating AdMob for the first time, add the Next-Gen SDK dependency to your app.

Init AdMob:

KotlinJava

val initConfig = InitializationConfig.Builder(ADMOB_APP_ID).build()
MobileAds.initialize(context, initConfig) {
    // AdMob SDK initialized
}

InitializationConfig initConfig = new InitializationConfig.Builder(ADMOB_APP_ID).build();
MobileAds.initialize(context, initConfig, initializationStatus -> {
    // AdMob SDK initialized
});

Init Orivia with Mediation.ADMOB (any time after AdMob init, but before requesting ads):

KotlinJava

OriviaSdk.getInstance(context).init(
    OriviaSdk.Config(
        mediation = Mediation.ADMOB,
        publisherId = ORIVIA_PUBLISHER_ID,
        defaultBannerAdUnit = BANNER_AD_UNIT_ID,
        defaultInterstitialAdUnit = INTERSTITIAL_AD_UNIT_ID,
        defaultRewardedAdUnit = REWARDED_AD_UNIT_ID,
        dataCollectionOnly = false // optional, false by default
    ),
    initListener = object : OriviaSdk.InitListener {
        override fun onInitCompleted() {
            Log.d("OriviaSDK", "Orivia SDK initialized.")
        }

        override fun onInitFailed(exception: OriviaException) {
            Log.e("OriviaSDK", "Orivia init failed: ${exception.reason}")
        }
    }
)

OriviaSdk.getInstance(context).init(
    new OriviaSdk.Config(
        Mediation.ADMOB,
        ORIVIA_PUBLISHER_ID,
        BANNER_AD_UNIT_ID,
        INTERSTITIAL_AD_UNIT_ID,
        REWARDED_AD_UNIT_ID,
        false // dataCollectionOnly
    ),
    new OriviaSdk.InitListener() {
        @Override
        public void onInitCompleted() {
            Log.d("OriviaSDK", "Orivia SDK initialized.");
        }

        @Override
        public void onInitFailed(@NonNull OriviaException exception) {
            Log.e("OriviaSDK", "Orivia init failed: " + exception.getReason());
        }
    }
);

Info

Orivia is ready immediately after calling init. You can load or show ads right away. If no config is loaded, default IDs are used.

Info

Unlike MAX, AdMob has no runtime SDK key — its App ID is passed to InitializationConfig.Builder instead. The Google User Messaging Platform (UMP) SDK still reads its App ID from the com.google.android.gms.ads.APPLICATION_ID meta-data in AndroidManifest.xml, so keep that tag even after migrating to the Next-Gen SDK.

Important

onInitCompleted() is triggered after the SDK loads its first config from the server.
To ensure optimal ads performance, it's highly recommended to wait for this callback before starting to load any ads.

Important

Calling init multiple times does not reinitialize the SDK if it's already initialized or currently initializing. The method will only run again if the SDK has previously invoked the onInitFailed callback. If init is called after the SDK has been initialized, onInitCompleted() is invoked immediately for provided listener. If init is called while initialization is in progress, the newly provided listener will be notified as soon as initialization finishes, together with all previous listeners.

If a certain ad type isn't used, just pass the constant OriviaSdk.AD_UNIT_ID_EMPTY instead of ad unit id.

Store AdMob Ad Results

Create a single OriviaAdmobHelper instance at class level:

KotlinJava

private val oriviaAdmobHelper: OriviaAdmobHelper by lazy {
    OriviaAdmobHelper(context)
}

private OriviaAdmobHelper oriviaAdmobHelper = new OriviaAdmobHelper(context);

This helper will remember the last success/failure per ad type and feed it to Orivia SDK.

Interstitial

Load & Show Interstitial

Use OriviaAdmobHelper instance to pick the ad unit id, load via AdMob, then forward the load/revenue events back to the helper:

KotlinJava

private var interstitialAd: InterstitialAd? = null

private fun loadInterstitial() {
    val adUnitId = oriviaAdmobHelper.getAdUnitId(AdType.INTERSTITIAL)
    InterstitialAd.load(
        AdRequest.Builder(adUnitId).build(),
        object : AdLoadCallback<InterstitialAd> {
            override fun onAdLoaded(ad: InterstitialAd) {
                ad.adEventCallback = object : InterstitialAdEventCallback {
                    override fun onAdPaid(value: AdValue) {
                        oriviaAdmobHelper.onPaidEvent(AdType.INTERSTITIAL, adUnitId, value, ad.getResponseInfo())
                    }

                    override fun onAdDismissedFullScreenContent() {
                        // Handle interstitial hidden
                    }

                    override fun onAdFailedToShowFullScreenContent(fullScreenContentError: FullScreenContentError) {
                        // Handle interstitial display failed
                    }
                }
                oriviaAdmobHelper.onAdLoaded(AdType.INTERSTITIAL, adUnitId, ad.getResponseInfo())
                interstitialAd = ad
                // Handle your own interstitial loaded logic
            }

            override fun onAdFailedToLoad(adError: LoadAdError) {
                oriviaAdmobHelper.onAdLoadFailed(AdType.INTERSTITIAL, adUnitId, adError)
                // Handle your own interstitial failed logic
            }
        }
    )
}

private fun showInterstitial() {
    interstitialAd?.show(activity)
}

private InterstitialAd interstitialAd;

private void loadInterstitial() {
    String adUnitId = oriviaAdmobHelper.getAdUnitId(AdType.INTERSTITIAL);
    InterstitialAd.load(
        new AdRequest.Builder(adUnitId).build(),
        new AdLoadCallback<InterstitialAd>() {
            @Override
            public void onAdLoaded(InterstitialAd ad) {
                ad.setAdEventCallback(new InterstitialAdEventCallback() {
                    @Override
                    public void onAdPaid(AdValue value) {
                        oriviaAdmobHelper.onPaidEvent(AdType.INTERSTITIAL, adUnitId, value, ad.getResponseInfo());
                    }

                    @Override
                    public void onAdDismissedFullScreenContent() {
                        // Handle interstitial hidden
                    }

                    @Override
                    public void onAdFailedToShowFullScreenContent(FullScreenContentError fullScreenContentError) {
                        // Handle interstitial display failed
                    }
                });
                oriviaAdmobHelper.onAdLoaded(AdType.INTERSTITIAL, adUnitId, ad.getResponseInfo());
                interstitialAd = ad;
                // Handle your own interstitial loaded logic
            }

            @Override
            public void onAdFailedToLoad(LoadAdError adError) {
                oriviaAdmobHelper.onAdLoadFailed(AdType.INTERSTITIAL, adUnitId, adError);
                // Handle your own interstitial failed logic
            }
        }
    );
}

private void showInterstitial() {
    if (interstitialAd != null) {
        interstitialAd.show(activity);
    }
}

Important

You should call these callbacks in the same place in your code where you handle your own callbacks or MMP callbacks.

It's critical for the SDK to receive all events.

Important

getAdUnitId should NOT be used when dataCollectionOnly is true, as the SDK does not update ad units in this mode — it will only return the values returned from init configuration call.

Rewarded

Load & Show Rewarded

Use OriviaAdmobHelper instance to pick the ad unit id, load via AdMob, then forward the load/revenue events back to the helper:

KotlinJava

private var rewardedAd: RewardedAd? = null

private fun loadRewarded() {
    val adUnitId = oriviaAdmobHelper.getAdUnitId(AdType.REWARDED)
    RewardedAd.load(
        AdRequest.Builder(adUnitId).build(),
        object : AdLoadCallback<RewardedAd> {
            override fun onAdLoaded(ad: RewardedAd) {
                ad.adEventCallback = object : RewardedAdEventCallback {
                    override fun onAdPaid(value: AdValue) {
                        oriviaAdmobHelper.onPaidEvent(AdType.REWARDED, adUnitId, value, ad.getResponseInfo())
                    }

                    override fun onAdDismissedFullScreenContent() {
                        // Handle rewarded hidden
                    }

                    override fun onAdFailedToShowFullScreenContent(fullScreenContentError: FullScreenContentError) {
                        // Handle rewarded display failed
                    }
                }
                oriviaAdmobHelper.onAdLoaded(AdType.REWARDED, adUnitId, ad.getResponseInfo())
                rewardedAd = ad
                // Handle your own rewarded loaded logic
            }

            override fun onAdFailedToLoad(adError: LoadAdError) {
                oriviaAdmobHelper.onAdLoadFailed(AdType.REWARDED, adUnitId, adError)
                // Handle your own rewarded failed logic
            }
        }
    )
}

private fun showRewarded() {
    rewardedAd?.show(activity, object : OnUserEarnedRewardListener {
        override fun onUserEarnedReward(reward: RewardItem) {
            // Handle user rewarded
        }
    })
}

private RewardedAd rewardedAd;

private void loadRewarded() {
    String adUnitId = oriviaAdmobHelper.getAdUnitId(AdType.REWARDED);
    RewardedAd.load(
        new AdRequest.Builder(adUnitId).build(),
        new AdLoadCallback<RewardedAd>() {
            @Override
            public void onAdLoaded(RewardedAd ad) {
                ad.setAdEventCallback(new RewardedAdEventCallback() {
                    @Override
                    public void onAdPaid(AdValue value) {
                        oriviaAdmobHelper.onPaidEvent(AdType.REWARDED, adUnitId, value, ad.getResponseInfo());
                    }

                    @Override
                    public void onAdDismissedFullScreenContent() {
                        // Handle rewarded hidden
                    }

                    @Override
                    public void onAdFailedToShowFullScreenContent(FullScreenContentError fullScreenContentError) {
                        // Handle rewarded display failed
                    }
                });
                oriviaAdmobHelper.onAdLoaded(AdType.REWARDED, adUnitId, ad.getResponseInfo());
                rewardedAd = ad;
                // Handle your own rewarded loaded logic
            }

            @Override
            public void onAdFailedToLoad(LoadAdError adError) {
                oriviaAdmobHelper.onAdLoadFailed(AdType.REWARDED, adUnitId, adError);
                // Handle your own rewarded failed logic
            }
        }
    );
}

private void showRewarded() {
    if (rewardedAd != null) {
        rewardedAd.show(activity, reward -> {
            // Handle user rewarded
        });
    }
}

Important

You should call these callbacks in the same place in your code where you handle your own callbacks or MMP callbacks.

It's critical for the SDK to receive all events.

Important

getAdUnitId should NOT be used when dataCollectionOnly is true, as the SDK does not update ad units in this mode — it will only return the values returned from init configuration call.

Extra Value

Returns a server-configured string value for the given ad type and key.

KotlinJava

val value: String? = OriviaSdk.getInstance(context).getExtraValue(AdType.INTERSTITIAL, "my_key")

String value = OriviaSdk.getInstance(context).getExtraValue(AdType.INTERSTITIAL, "my_key");

Ad Config Update Listener

Get notified whenever the server-driven ad config for a given ad type changes:

KotlinJava

val listener = object : OriviaSdk.AdConfigUpdateListener {
    override fun onAdConfigUpdated(adType: AdType) {
        // ad config for adType was refreshed
    }
}
OriviaSdk.getInstance(context).addAdConfigUpdateListener(AdType.INTERSTITIAL, listener)

// Later, when no longer needed:
OriviaSdk.getInstance(context).removeAdConfigUpdateListener(AdType.INTERSTITIAL, listener)

OriviaSdk.AdConfigUpdateListener listener = adType -> {
    // ad config for adType was refreshed
};
OriviaSdk.getInstance(context).addAdConfigUpdateListener(AdType.INTERSTITIAL, listener);

// Later, when no longer needed:
OriviaSdk.getInstance(context).removeAdConfigUpdateListener(AdType.INTERSTITIAL, listener);

Important

The listener fires on every config refresh, not only when a value actually changed, and is held with a strong reference until removed — always call removeAdConfigUpdateListener (e.g. in onDestroy) to avoid leaking.

Client Parameters

To pass client parameters to the server:

KotlinJava

OriviaSdk.getInstance(context).setClientParams(
    valueMap {
        put("str", "value")
        put("int", 12)
        put("float", 1.3f)
        put("bool", true)
        put("nested", valueMap {
            put("str", "value")
        })
    }
)

OriviaSdk.getInstance(context).setClientParams(
    new ValueMap.Builder()
        .put("str", "value")
        .put("int", 12)
        .put("float", 1.3f)
        .put("bool", true)
        .put("nested", new ValueMap.Builder()
            .put("str", "value")
            .build()
        ).build()
);

If the parameters should be passed in the init request, the setClientParams method must be called before invoking the init method.

Important

Passing null to this method has no effect. To clear the parameters, pass an empty ValueMap.

Logging

Turn on internal logs for debugging:

KotlinJava

OriviaSdk.getInstance(context).setLoggingEnabled(true)

OriviaSdk.getInstance(context).setLoggingEnabled(true);

Privacy

To pass GDPR Applies there are 2 options.

Pass it through CMP IABTCF_gdprApplies property or using SDK method:

KotlinJava

OriviaSdk.getInstance(context).setGdprApplies(true) // or false, or null for unknown

OriviaSdk.getInstance(context).setGdprApplies(true); // or false, or null for unknown

To pass COPPA:

KotlinJava

OriviaSdk.getInstance(context).setCoppa(true) // or false, or null for unknown

OriviaSdk.getInstance(context).setCoppa(true); // or false, or null for unknown

Null values reset properties.