Skip to content

General

Jump to bottom
Francisco Dias edited this page Jul 29, 2026 · 15 revisions

General

Initialization, the shared paid-event stream, server-side verification, and the shared result types every other module's callbacks use.

Functions

Initialization and cross-family functions.

Structs

Shared data types used across every module.

Constants

This module includes a set of predefined constants that can be utilized for various purposes. Browse through the available constants to find values relevant to your needs and enhance the efficiency of your code.


Back To Top

admob_initialize

Initializes the Google Mobile Ads SDK. Call this once, before any other AdMob function (other than admob_set_test_device_id, which must be called before this one if you need test ads on the current device). Every other function in this extension fails with AdMobError.NotInitialized until this has completed successfully.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Callback.


Syntax:

admob_initialize(callback)
Argument Type Description
callback Function The function to call once initialization completes or fails.

Returns:

AdMobError

AdMobError.Ok if the initialization request was accepted, an error code if it was rejected outright (e.g. already initialized).


Triggers:

Callback

Fires once, when the SDK finishes starting up (or fails to).

Key Type Description
result AdMobResult The initialization outcome.

Example:

admob_initialize(function(_result)
{
    if (_result.success)
        show_debug_message("AdMob initialized");
    else
        show_debug_message($"AdMob failed to initialize: {_result.error_message}");
});

Back To Top

admob_set_test_device_id

Marks the current device as a test device, so every ad request from this session returns a Google test ad instead of a live ad. Must be called before admob_initialize - calling it after initialization returns AdMobError.IllegalCall.

Important

Never ship a build with this enabled - it must only be used during development.


Syntax:

admob_set_test_device_id()

Returns:

AdMobError

AdMobError.Ok on success, AdMobError.IllegalCall if the SDK is already initialized.


Back To Top

admob_events_on_paid_event

Subscribes to (or unsubscribes from) Google's paid-event stream, shared across every ad family this extension wraps. Once subscribed, callback fires once per ad impression that earns revenue, for every banner/interstitial/rewarded video/rewarded interstitial/app open ad shown - check AdMobPaidEvent.ad_type to tell which family it came from.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Callback.


Syntax:

admob_events_on_paid_event(enabled, callback)
Argument Type Description
enabled Boolean true to subscribe, false to unsubscribe (in which case callback is
ignored and can be undefined).
callback Function The function to call for every paid impression.

Returns:

N/A


Triggers:

Callback

Fires once per ad impression that earns revenue, across every ad family.

Key Type Description
event AdMobPaidEvent The paid-event details.

Example:

admob_events_on_paid_event(true, function(_event)
{
    show_debug_message($"Earned {_event.value_micros / 1000000} {_event.currency_code} from {_event.ad_type}");
});

Back To Top

admob_server_side_verification_set

Configures the custom data Google's Server-Side Verification feature attaches to the reward callback your backend receives when a rewarded video or rewarded interstitial ad is completed. Applies to every rewarded ad loaded after this call.


Syntax:

admob_server_side_verification_set(user_id, custom_data)
Argument Type Description
user_id String An opaque identifier for the current user, echoed back to your server in
the SSV callback.
custom_data String Arbitrary custom data, echoed back to your server in the SSV callback.

Returns:

N/A


Back To Top

admob_server_side_verification_clear

Clears the server-side-verification data previously set with admob_server_side_verification_set. Rewarded ads loaded after this call carry no SSV custom data.


Syntax:

admob_server_side_verification_clear()

Returns:

N/A


Back To Top

AdMobError

Extension-defined error codes returned synchronously by most functions in this extension. These are not raw Google Mobile Ads SDK error codes - a Google SDK failure is instead reported asynchronously via AdMobResult.sdk_error_code in the relevant callback.

These constants are referenced by the following functions:


Member Description
Ok The call succeeded.
NotInitialized admob_initialize has not completed successfully yet.
InvalidAdId No ad unit ID has been set for this ad family (or it is empty).
AdLimitReached Reserved for future use.
NoAdsLoaded The requested ad instance has not been loaded (or has already been shown/disposed).
NoActiveBannerAd Reserved for future use.
IllegalCall The call is not valid in the SDK's current state (e.g. calling
admob_set_test_device_id after admob_initialize).
NullViewHandler The game's view is not available yet (too early in the app lifecycle).
InvalidHandle The handle passed does not refer to a currently-loaded ad instance - it may
already have been shown, disposed, or never existed.

Back To Top

AdMobAdType

Distinguishes which ad family a shared admob_events_on_paid_event callback fired for. Extension-owned - Google's own AdValue type carries no ad-family concept.

These constants are referenced by the following structs:


Member Description
Banner
Interstitial
RewardedVideo
RewardedInterstitial
AppOpen

Back To Top

AdMobPrecisionType

How precisely AdMobPaidEvent.value_micros is known. Mirrors Android AdValue.PrecisionType/iOS GADAdValuePrecision directly - both platforms already use these same ordinals, so no translation is needed.

These constants are referenced by the following structs:


Member Description
Unknown
Estimated
PublisherProvided
Precise

Back To Top

AdMobResult

The uniform success/failure envelope delivered to every async callback in this extension. error_message and sdk_error_code are both absent on success. sdk_error_code carries Google's own LoadAdError/AdError code verbatim when the failure came from the ad SDK itself; it is absent when the extension rejected the call before ever reaching Google (see AdMobError instead).

This struct is referenced by the following functions:


Member Type Description
success Boolean Whether the operation succeeded.
error_message String The SDK's own error message. Only present on failure.
sdk_error_code Real Google's raw LoadAdError/AdError code. Only present when the
failure came from the SDK (not from this extension rejecting the call outright).

Back To Top

AdMobReward

The reward earned from a rewarded video or rewarded interstitial ad. Mirrors Google's RewardItem.getAmount()/getType() directly.

This struct is referenced by the following functions:


Member Type Description
amount Real The reward amount.
type String The reward type, as configured for the ad unit in the AdMob dashboard.

Back To Top

AdMobPaidEvent

Delivered by Google's OnPaidEventListener - always a success signal (the underlying SDK event has no failure case), so unlike AdMobResult there is no success/error_message pair. ad_type and ad_unit_id are enrichment this extension adds so a single shared subscription (see admob_events_on_paid_event) can tell which ad family and unit the impression came from; the rest mirrors Google's AdValue/AdapterResponseInfo directly.

This struct is referenced by the following functions:


Member Type Description
ad_type AdMobAdType Which ad family the impression came from.
ad_unit_id String The ad unit ID the impression came from.
value_micros Real The estimated earned value, in micro-units of currency_code.
currency_code String The ISO 4217 currency code (e.g. "USD").
precision AdMobPrecisionType How precisely value_micros is known.
mediation_adapter_class_name String The class name of the mediation adapter that served
the ad, or the AdMob network's own class name if no mediation was involved.
ad_source_name String The name of the ad source (network) that served the ad. Only
present when Google's AdapterResponseInfo was available for this impression.
ad_source_id String The ID of the ad source that served the ad.
ad_source_instance_name String The name of the specific ad source instance/placement.
ad_source_instance_id String The ID of the specific ad source instance/placement.

YoYoGames 2026

AdMob Extension

Guides

Modules

Clone this wiki locally