MobileAds

class MobileAds

MobileAds is the entry point in to the Google Mobile Ads SDK. This class enables you to initialize and configure the SDK, as well as query the state of the SDK.

Summary

Public companion functions
suspend SignalGenerationResult

Generates a signal that can be used as input in a server-to-server ad request.
Unit
generateSignal(
    request: SignalRequest,
    callback: SignalGenerationCallback
)

Generates a signal that can be used as input in a server-to-server ad request.
InitializationStatus

Gets the SDK initialization status.
RequestConfiguration

Gets the global RequestConfiguration.
VersionInfo

Gets the external version (for example, 20.6.0) of the Google Mobile Ads SDK.
Unit
@WorkerThread
@RequiresPermission(value = "android.permission.INTERNET")
initialize(
    context: Context,
    initializationConfig: InitializationConfig,
    listener: OnAdapterInitializationCompleteListener?
)

Initializes the Google Mobile Ads SDK synchronously.
Unit

Opens the ad inspector UI.
Unit
openDebugMenu(activity: Activity, adUnitId: String)

Opens the debug menu.
Boolean

Controls whether the Google Mobile Ads SDK publisher first-party ID, formerly known as the same app key, is enabled.
CustomTabsSession?
registerCustomTabsSession(
    client: CustomTabsClient,
    origin: String,
    callback: CustomTabsCallback?
)

Registers a CustomTabsClient with the Google Mobile Ads SDK to improve in-app ad monetization of ads within this CustomTabsSession.
Unit

Registers a WebView with the Google Mobile Ads SDK to improve in-app ad monetization of ads within this WebView.
Unit

Sets the global RequestConfiguration that will be used for every AdRequest during the app's session.
Unit

Sets the user-controlled application's audio volume.
Unit

Indicates whether the user muted or unmuted the app.

Public companion properties
volatile Boolean

Indicates whether the Google Mobile Ads SDK is ready to handle method calls other than initialize.

Public companion functions

generateSignal

suspend fun generateSignal(request: SignalRequest): SignalGenerationResult

Generates a signal that can be used as input in a server-to-server ad request. Suspends until a SignalGenerationResult is returned.

Parameters
request: SignalRequest

A SignalRequest with targeting information.
Returns
SignalGenerationResult

SignalGenerationResult.Success if signals are successfully generated, otherwise SignalGenerationResult.Failure.

generateSignal

fun generateSignal(
    request: SignalRequest,
    callback: SignalGenerationCallback
): Unit

Generates a signal that can be used as input in a server-to-server ad request.

Parameters
request: SignalRequest

A signal request with targeting information.
callback: SignalGenerationCallback

A callback to be invoked when signal generation completes.

getInitializationStatus

fun getInitializationStatus(): InitializationStatus

Gets the SDK initialization status.

getRequestConfiguration

fun getRequestConfiguration(): RequestConfiguration

Gets the global RequestConfiguration.

getVersion

fun getVersion(): VersionInfo

Gets the external version (for example, 20.6.0) of the Google Mobile Ads SDK.

initialize doesn't need to be called prior to calling this function.

initialize

@WorkerThread
@RequiresPermission(value = "android.permission.INTERNET")
fun initialize(
    context: Context,
    initializationConfig: InitializationConfig,
    listener: OnAdapterInitializationCompleteListener?
): Unit

Initializes the Google Mobile Ads SDK synchronously.

When this method returns, the SDK is ready to accept requests but not all 3P SDKs may be ready yet. listener will be invoked when adapter initialization has finished.

Call this method as early as possible after the app launches to reduce latency on the session's first ad request, but balance doing so with the startup time for your users.

This method must be called prior to interacting with MobileAds, unless explicitly noted (see getVersion). Otherwise, an UninitializedPropertyAccessException may be thrown. Calling initialize will make isInitialized return true.

This method should be called on a background thread, as it may perform disk or network operations. Failure to do so may cause an "application not responding" (ANR) dialog.

Multiple calls before initialization has finished will queue up listeners. Calls after initialization has finished will immediately invoke listener. Calling initialize again with a different application ID is a no-op.

Parameters
context: Context

The Context the SDK is running in.
initializationConfig: InitializationConfig

Options to control SDK initialization.
listener: OnAdapterInitializationCompleteListener?

A callback to be invoked upon initialization completion.

openAdInspector

fun openAdInspector(listener: OnAdInspectorClosedListener): Unit

Opens the ad inspector UI.

openDebugMenu

fun openDebugMenu(activity: Activity, adUnitId: String): Unit

Opens the debug menu.

Parameters
activity: Activity

The Activity the SDK is running in.
adUnitId: String

Any Ad Manager ad unit ID associated with your app.

putPublisherFirstPartyIdEnabled

fun putPublisherFirstPartyIdEnabled(enabled: Boolean): Boolean

Controls whether the Google Mobile Ads SDK publisher first-party ID, formerly known as the same app key, is enabled.

The ID is enabled by default. When disabled, the setting is persisted across app sessions and the ID is cleared.

Parameters
enabled: Boolean

Boolean true if the publisher first-party ID is enabled, false otherwise.
Returns
Boolean

true if the enablement decision has been successfully persisted. False if the decision fails to be persisted.

registerCustomTabsSession

fun registerCustomTabsSession(
    client: CustomTabsClient,
    origin: String,
    callback: CustomTabsCallback?
): CustomTabsSession?

Registers a CustomTabsClient with the Google Mobile Ads SDK to improve in-app ad monetization of ads within this CustomTabsSession. This will only create one instance of CustomTabsSession and re-running this overrides the existing session.

Parameters
client: CustomTabsClient

CustomTabsClient used to create the CustomTabsSession instance.
origin: String

String used as origin on the Digital Asset Link for verification.
callback: CustomTabsCallback?

optional CustomTabsCallback to receive callbacks from CustomTabsSession.
Returns
CustomTabsSession?

CustomTabsSession instance to be used for Custom Tabs Intent when opening a Custom Tabs page. Null if the client failed to return a new session.

registerWebView

fun registerWebView(webView: WebView): Unit

Registers a WebView with the Google Mobile Ads SDK to improve in-app ad monetization of ads within this WebView.

setRequestConfiguration

fun setRequestConfiguration(requestConfiguration: RequestConfiguration): Unit

Sets the global RequestConfiguration that will be used for every AdRequest during the app's session.

setUserControlledAppVolume

fun setUserControlledAppVolume(volume: Float): Unit

Sets the user-controlled application's audio volume. Affects audio volumes of all ads relative to other audio output.

Warning: Lowering your app's audio volume reduces video ad eligibility and may reduce your app's ad revenue. You should only utilize this API if your app provides custom volume controls to the user, and you should reflect the user's volume choice in this API.

Parameters
volume: Float

The volume as a float from 0 (muted) to 1.0 (full media volume). Defaults to 1.0
Throws
java.lang.IllegalArgumentException

if volume is out of the valid range

setUserMutedApp

fun setUserMutedApp(muted: Boolean): Unit

Indicates whether the user muted or unmuted the app. Affects initial mute state for all ads.

Warning: Muting your application reduces video ad eligibility and may reduce your app's ad revenue. You should only utilize this API if your app provides a custom mute control to the user, and you should reflect the user's mute decision in this API.

Parameters
muted: Boolean

True if the app is muted, false otherwise. Defaults to false.

Public companion properties

isInitialized

volatile val isInitialized: Boolean

Indicates whether the Google Mobile Ads SDK is ready to handle method calls other than initialize. This will return true after initialize has been called.

It is important to wait until this property is true prior to interacting with other methods on MobileAds.

Attempting to do so before this property is true may result in an UninitializedPropertyAccessException, unless explicitly noted (see getVersion).