admob-cmp-core/dev.avinya.ads

Package-level declarations

Types

data class AdAppIds(val android: String, val ios: String)

Per-platform AdMob app IDs (not ad-unit IDs). Required for AdConfig initialization. Obtain your app IDs from the AdMob dashboard.

AdapterInitializationStatus

data class AdapterInitializationStatus(val adapterName: String, val initialized: Boolean, val latencyMillis: Long? = null, val description: String? = null)

Initialization status of a mediation adapter.

AdAvailability

data class AdAvailability(val isReady: Boolean, val cachedCount: Int = 0, val expiresIn: Duration? = null)

Availability information for cached ads.

AdCachePolicy

data class AdCachePolicy(val maxSize: Int = 1, val expirationPolicy: AdExpirationPolicy = AdExpirationPolicy(), val reloadAfterShow: Boolean = false)

Caching policy for ad formats that support multiple cached ads (native, full-screen). Cache is FIFO; ads are evicted when maxSize is exceeded or when TTL (from expirationPolicy) expires.

AdConfig

data class AdConfig(val appIds: AdAppIds, val globalRequestConfiguration: GlobalRequestConfiguration = GlobalRequestConfiguration(), val debugOptions: AdDebugOptions = AdDebugOptions(), val consentTagForUnderAgeOfConsent: Boolean = false, val initializationHooks: List<AdInitializationHook> = emptyList())

Top-level SDK configuration for the Google Mobile Ads SDK. Passed to AdManager.initialize. The secondary constructor provides a convenient surface for the most common fields.

AdDebugOptions

data class AdDebugOptions(val testMode: Boolean = false, val consentDebugGeography: ConsentDebugGeography = ConsentDebugGeography.Disabled, val consentTestDeviceIds: List<String> = emptyList(), val enableAdInspectorEntryPoints: Boolean = true)

Debug and test options for the SDK. testMode does not force GMA to serve test ads by itself — it only enables UMP's debug consent-gathering settings. Google's SDK determines whether a request is a test request from the device's registration in GlobalRequestConfiguration.testDeviceIds (Android/iOS emulators and simulators qualify automatically; physical devices require the device's hashed test-device ID, printed to logcat/console on an unregistered request). If testMode is true and no test device IDs are configured, the SDK logs a warning at initialization rather than silently doing nothing — see dev.avinya.ads.TestAdIds for a ready-made safe configuration.

AdDiagnostics

interface AdDiagnostics

Diagnostics and debug tools for the Google Mobile Ads SDK.

AdError

data class AdError(val code: String? = null, val message: String, val domain: String? = null, val responseInfo: AdResponseInfo? = null)

Represents an error from the ad SDK. code carries the SDK's own error code string (e.g. AdErrorCode.CONSENT_REQUIRED) or a numeric GMA error code as a string. message is a human-readable description. domain identifies the source subsystem.

AdErrorCode

object AdErrorCode

SDK-defined error code constants used by AdError. GMA numeric error codes appear as strings in AdError.code but are not listed here.

AdEvent

sealed interface AdEvent

Lifecycle events emitted by ad controllers and pools. Subscribe via AdManager.events or individual controller/pool events flows.

AdExpirationPolicy

data class AdExpirationPolicy(val fullScreenTtl: Duration = 1.hours, val appOpenTtl: Duration = 4.hours, val nativeTtl: Duration = 1.hours)

Time-to-live policy for cached ads. Defaults: full-screen 1 hour, app-open 4 hours, native 1 hour.

AdFormat

enum AdFormat : Enum<AdFormat>

Supported ad formats in the SDK. Each format has a corresponding controller type on AdManager.

AdInitializationHook

interface AdInitializationHook

Hook invoked at each phase of the SDK initialization lifecycle. Implementations can perform side effects (e.g., server-side config fetch, GDPR consent platform integration) at specific AdInitializationPhases.

AdInitializationPhase

enum AdInitializationPhase : Enum<AdInitializationPhase>

Phases of the SDK initialization sequence during which AdInitializationHook.onPhase is called.

AdLoadState

sealed interface AdLoadState

Represents the current load state of an ad or ad pool.

AdLogger

object AdLogger

AdManager

interface AdManager

Entry point to the ads SDK. Provides controllers for every ad format, consent lifecycle management, diagnostics, and a flow of AdEvents. Obtain the process-wide singleton via rememberAdManager (Compose) or AdMob.manager(context) (Android, outside Compose).

AdManagerStatus

sealed interface AdManagerStatus

Represents the current state of the AdManager. Emitted via AdManager.status as a StateFlow.

AdMob

object AdMob

AdNetworkResponseInfo

data class AdNetworkResponseInfo(val adapterClassName: String? = null, val latencyMillis: Long? = null, val error: AdError? = null, val adSourceName: String? = null, val adSourceId: String? = null, val adSourceInstanceName: String? = null, val adSourceInstanceId: String? = null)

Response info for a single ad network in the mediation chain.

AdPlacement

data class AdPlacement(val id: String, val format: AdFormat, val adUnitIds: AdUnitIds, val requestOptions: AdRequestOptions = AdRequestOptions(), val cachePolicy: AdCachePolicy = AdCachePolicy(), val retryPolicy: AdRetryPolicy = AdRetryPolicy(), val timeoutPolicy: AdTimeoutPolicy = AdTimeoutPolicy(), val bannerSizePolicy: AdSizePolicy = AdSizePolicy.LargeAnchoredAdaptive(), val bannerRefreshPolicy: BannerRefreshPolicy = BannerRefreshPolicy.AdServerManaged, val nativeOptions: NativeAdOptions = NativeAdOptions(), val fullScreenOptions: FullScreenAdOptions = FullScreenAdOptions(), val enabled: Boolean = true, val strictTestMode: Boolean = false)

Defines a single ad placement — the complete configuration needed to request and render ads of a given format. Every controller factory on AdManager takes an AdPlacement and caches the resulting controller by id.

AdPlatform

enum AdPlatform : Enum<AdPlatform>

Supported mobile ad platforms. Used to resolve platform-specific IDs and behavior.

AdRequestOptions

data class AdRequestOptions(val keywords: Set<String> = emptySet(), val contentUrl: String? = null, val neighboringContentUrls: Set<String> = emptySet(), val requestAgent: String? = null, val categoryExclusions: Set<String> = emptySet(), val customTargeting: Map<String, List<String>> = emptyMap(), val googleExtras: Map<String, String> = emptyMap(), val publisherProvidedId: String? = null, val placementId: Long? = null, val skipUninitializedAdapters: Boolean = false)

Per-request targeting and configuration options for ad loads. Android-only fields are silently ignored on iOS.

AdResponseInfo

data class AdResponseInfo(val responseId: String? = null, val adapterClassName: String? = null, val extras: Map<String, String> = emptyMap(), val loadedAdNetworkResponseInfo: AdNetworkResponseInfo? = null, val adNetworkResponseInfos: List<AdNetworkResponseInfo> = emptyList())

Information about an ad response, including mediation chain details.

AdRetryPolicy

data class AdRetryPolicy(val maxAttempts: Int = 2, val initialDelay: Duration = 2.seconds, val maxDelay: Duration = 30.seconds, val backoffMultiplier: Double = 2.0)

Capped exponential-backoff retry policy for ad load failures. Only retryable failures (network, timeout, internal) are retried; non-retryable failures (no fill, consent) are not.

AdReward

data class AdReward(val amountMicros: Long, val type: String)

Reward granted to the user after watching a rewarded ad.

AdShowResult

sealed interface AdShowResult

Result of a full-screen ad show operation.

AdSizePolicy

sealed interface AdSizePolicy

Defines the size of a banner ad. Choice depends on the desired ad format and container constraints.

AdTimeoutPolicy

data class AdTimeoutPolicy(val loadTimeout: Duration = 30.seconds, val presentationHandOffTimeout: Duration = 10.seconds)

Bounds on how long a suspending ad operation may take.

AdTrackingAuthorization

enum AdTrackingAuthorization : Enum<AdTrackingAuthorization>

App Tracking Transparency authorisation state (iOS 14.5+).

AdTrackingController

interface AdTrackingController

Reads and requests App Tracking Transparency authorisation.

AdUnitIds

data class AdUnitIds(val android: String, val ios: String)

Per-platform AdMob ad-unit IDs (not app IDs). Provide an ID for each platform the app targets; the correct ID is resolved at runtime via forPlatform.

AdValue

data class AdValue(val valueMicros: Long, val currencyCode: String, val precision: AdValuePrecision)

Monetary value of an ad event, specified in micro-units of a currency.

AdValuePrecision

enum AdValuePrecision : Enum<AdValuePrecision>

Precision of an AdValue report.

AgeRestrictedTreatment

enum AgeRestrictedTreatment : Enum<AgeRestrictedTreatment>

Age treatment applied to Google Mobile Ads requests.

AppOpenAdController

interface AppOpenAdController : FullScreenAdController

Full-screen ad controller for app-open format. Shows an ad when the app returns to the foreground. For automated lifecycle management use AppOpenAdCoordinator.

BannerAdController

interface BannerAdController

Controls a single banner ad placement. Handles loading, refresh, and lifecycle. For Compose UI, prefer BannerAdView which manages the controller automatically.

BannerGeometry

data class BannerGeometry(val widthDp: Int)

Layout geometry supplied by the host for a banner request.

BannerRefreshPolicy

sealed interface BannerRefreshPolicy

Controls how banner ads are refreshed. Choose based on whether you want server-driven, client-timer, or manual refresh.

CollapsiblePlacement

enum CollapsiblePlacement : Enum<CollapsiblePlacement>

Placement for a collapsible banner ad. Top collapses upward, Bottom collapses downward when the ad is not visible.

ConsentController

interface ConsentController

Controls the consent lifecycle via Google's User Messaging Platform (UMP). Call requestConsentInfoUpdate on every app launch and gatherConsent to show the consent form when required. Gate ad requests on canRequestAds.

ConsentDebugGeography

enum ConsentDebugGeography : Enum<ConsentDebugGeography>

UMP debug geography for testing consent flows. Forces the SDK to behave as if the device is in a specific region for consent purposes. Disabled uses real geography; Eea forces EEA behavior; NotEea forces non-EEA behavior. Never use in production builds.

ConsentMode

enum ConsentMode : Enum<ConsentMode>

Strategy for handling user consent via Google's UMP before SDK initialization. Choose based on your app's consent requirements and target regions.

ConsentStatus

sealed interface ConsentStatus

Consent status reported by Google's UMP. Mirrors the UMP consent status and is distinct from ConsentController.canRequestAds — canRequestAds may be true even when consent was not explicitly obtained (e.g., in non-EEA regions).

FullScreenAdController

interface FullScreenAdController

Controls a full-screen ad format (interstitial, rewarded, rewarded interstitial, or app-open). Full-screen ads are single-use: show consumes the ad. Successfully presented rewarded ads deliberately remain callback-owned after dismissal so a mediated reward callback may arrive later. Cache and TTL are managed by AdCachePolicy.

FullScreenAdOptions

data class FullScreenAdOptions(val immersiveMode: Boolean = false, val serverSideVerification: ServerSideVerificationOptions? = null)

Display options for full-screen ads (interstitial, rewarded, app-open).

FullScreenAdSlot

typealias FullScreenAdSlot = FullScreenAdController

Typealias for FullScreenAdController. Use this type when you need a slot that can hold any full-screen format (interstitial, rewarded, etc.).

GlobalRequestConfiguration

data class GlobalRequestConfiguration(val testDeviceIds: List<String> = emptyList(), val maxAdContentRating: MaxAdContentRating = MaxAdContentRating.Unspecified, val ageRestrictedTreatment: AgeRestrictedTreatment = AgeRestrictedTreatment.Unspecified, val publisherPrivacyPersonalizationState: PublisherPrivacyPersonalizationState = PublisherPrivacyPersonalizationState.Default, val publisherFirstPartyIdEnabled: Boolean? = null, val appMuted: Boolean? = null, val appVolume: Float? = null)

Global request configuration applied to every ad request made through the SDK. Fields mirror the GMA SDK request configuration.

InternalAdMobCmpApi

@RequiresOptIn(message = "This API connects AdMob CMP implementation artifacts and is not a stable consumer API.", level = RequiresOptIn.Level.ERROR)

@Target(allowedTargets = [AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY])

annotation class InternalAdMobCmpApi

InterstitialAdController

interface InterstitialAdController : FullScreenAdController

Full-screen ad controller for interstitial format.

IosAdMob

object IosAdMob

Public entry point for the process-wide iOS AdManager singleton.

MaxAdContentRating

enum MaxAdContentRating : Enum<MaxAdContentRating>

Maximum ad content rating filter. Corresponds to GMA MaxAdContentRating.

NativeAdPool

interface NativeAdPool

Manages a pool of preloaded native ads for a single placement. Ads are acquired via acquire and must be returned via release. The composable NativeAdView handles acquire/release automatically. Use the pool directly for manual native ad rendering.

NoOpAdManager

object NoOpAdManager : AdManager

Default no-op manager used when ads aren't configured. All loads fail with AdError.sdkNotReady and the status is always AdManagerStatus.Disabled.

PaidEvent

data class PaidEvent(val placementId: String, val value: AdValue, val responseInfo: AdResponseInfo? = null)

Impression-level paid event with revenue data. Emitted via AdEvent.Paid.

PrivacyOptionsRequirementStatus

enum PrivacyOptionsRequirementStatus : Enum<PrivacyOptionsRequirementStatus>

Whether the user must be given the option to review their privacy settings. Gating: show a privacy-settings entry point only when this is Required; then call ConsentController.showPrivacyOptions.

PublisherPrivacyPersonalizationState

enum PublisherPrivacyPersonalizationState : Enum<PublisherPrivacyPersonalizationState>

Publisher privacy personalization state. Controls whether ad personalization is enabled, disabled, or follows the default (user consent) setting.

RewardedAdController

interface RewardedAdController : FullScreenAdController

Full-screen ad controller for rewarded video format.

RewardedInterstitialAdController

interface RewardedInterstitialAdController : FullScreenAdController

Full-screen ad controller for rewarded interstitial format.

ServerSideVerificationOptions

data class ServerSideVerificationOptions(val userId: String? = null, val customData: String? = null)

Server-side verification options for rewarded and rewarded-interstitial ads. Provides userId and customData to the reward server callback for reward validation.

TestAdIds

object TestAdIds

Google's official sample ad-unit and app IDs for testing. Never use these constants in production. Use them in debug builds and test runs only.

Properties

debugAdConfig

val debugAdConfig: AdConfig

Ready-made debug AdConfig using TestAdIds with test mode enabled.

debugAdPlacements

val debugAdPlacements: List<AdPlacement>

Ready-made debug AdPlacements covering every AdFormat using TestAdIds. Suitable for samples, QA, and testing.

Functions

attachAndroidBanner

fun BannerAdController.attachAndroidBanner()

attachIosBanner

fun BannerAdController.attachIosBanner()

currentAndroidBannerAd

fun BannerAdController.currentAndroidBannerAd(): BannerAd?

currentAndroidBannerView

fun BannerAdController.currentAndroidBannerView(): AdView?

currentIosBannerView

fun BannerAdController.currentIosBannerView(): GADBannerView?

detachAndroidBanner

fun BannerAdController.detachAndroidBanner()

detachIosBanner

fun BannerAdController.detachIosBanner()

gatherConsentAndInitialize

suspend fun AdManager.gatherConsentAndInitialize(config: AdConfig): AdManagerStatus

Convenience extension that calls initialize with ConsentMode.GatherBeforeInitialize — the standard consent flow that requests a UMP update, shows the form if required, and initializes ads when permitted.

registerAndroidBannerGeometry

fun BannerAdController.registerAndroidBannerGeometry(geometry: BannerGeometry, sizePolicy: AdSizePolicy, requestOptions: AdRequestOptions)

registerIosBannerGeometry

fun BannerAdController.registerIosBannerGeometry(geometry: BannerGeometry, sizePolicy: AdSizePolicy, requestOptions: AdRequestOptions)

screenWidthDp

fun Activity.screenWidthDp(): Int

showPrivacyOptions

suspend fun AdManager.showPrivacyOptions(): Boolean

Convenience extension that calls ConsentController.showPrivacyOptions on this manager's AdManager.consent controller.

toAndroidAdSize

fun AdSizePolicy.toAndroidAdSize(activity: Activity, widthDp: Int): AdSize