Interstitial

Interstitial

Functions for loading and showing interstitial ads - full-screen ads shown at natural transition points in your game.

Functions

This module offers a collection of functions designed to address specific tasks and provide utilities for various purposes. Explore the available functions to make the most of the functionalities provided by this module.

• admob_interstitial_set_ad_unit
• admob_interstitial_load
• admob_interstitial_is_valid
• admob_interstitial_dispose
• admob_interstitial_show

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.

• AdMobInterstitialShowEvent

---

Back To Top

admob_interstitial_set_ad_unit

Sets the default ad unit ID used by admob_interstitial_load when its own ad_unit_id argument is omitted.

Syntax:

admob_interstitial_set_ad_unit(ad_unit_id)

Argument	Type	Description
ad_unit_id	String	The interstitial ad unit ID, from the AdMob dashboard.

Returns:

N/A

---

Back To Top

admob_interstitial_load

Loads an interstitial ad. Multiple interstitials can be in flight at once - each successful load produces its own independent handle, so you can pre-load several and show them later in any order.

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_interstitial_load(callback, ad_unit_id=undefined)

Argument	Type	Description
callback	Function	The function to call once the load completes or fails.
ad_unit_id	String	The ad unit ID to load. If omitted, uses the unit set by admob_interstitial_set_ad_unit.

Returns:

AdMobError

AdMobError.Ok if the load request was accepted, an error code otherwise.

Triggers:

Callback

Fires once, when the load completes or fails.

Key	Type	Description
result	AdMobResult	The load outcome.
handle	Real	A handle identifying this loaded ad instance, for use with admob_interstitial_show/admob_interstitial_is_valid/ admob_interstitial_dispose. Only present on success.

Example:

admob_interstitial_load(function(_result, _handle)
{
    if (_result.success)
        global.interstitial_handle = _handle;
});

---

Back To Top

admob_interstitial_is_valid

Checks whether a handle still refers to a loaded, unshown interstitial ad instance.

Syntax:

admob_interstitial_is_valid(handle)

Argument	Type	Description
handle	Real	A handle returned by admob_interstitial_load.

Returns:

Boolean

true if the handle is still valid (loaded, not yet shown or disposed).

---

Back To Top

admob_interstitial_dispose

Releases a loaded interstitial ad instance without showing it. Does nothing if the handle is already invalid.

Syntax:

admob_interstitial_dispose(handle)

Argument	Type	Description
handle	Real	A handle returned by admob_interstitial_load.

Returns:

N/A

---

Back To Top

admob_interstitial_show

Shows a loaded interstitial ad full-screen. handle is consumed by this call (whether it succeeds or fails) - it cannot be shown again, even if admob_interstitial_show itself fails.

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_interstitial_show(handle, callback)

Argument	Type	Description
handle	Real	A handle returned by admob_interstitial_load.
callback	Function	The function to call for the ad's show-lifecycle events.

Returns:

AdMobError

AdMobError.Ok if the show request was accepted, AdMobError.InvalidHandle if handle is invalid, already shown, or already disposed, an error code otherwise.

Triggers:

Callback

Fires once per show-lifecycle event on success; fires once with success = false and no type if the ad fails to show.

Key	Type	Description
result	AdMobResult	The event's result.
type	AdMobInterstitialShowEvent	Which show-lifecycle event this is. Absent when result.success is false.

Example:

admob_interstitial_show(global.interstitial_handle, function(_result, _type = undefined)
{
    if (!_result.success)
        show_debug_message($"Interstitial failed to show: {_result.error_message}");
    else if (_type == AdMobInterstitialShowEvent.Dismissed)
        show_debug_message("Interstitial dismissed");
});

---

Back To Top

AdMobInterstitialShowEvent

The show-lifecycle events admob_interstitial_show's callback can fire with on success. Numeric values are extension-owned.

These constants are referenced by the following functions:

• admob_interstitial_show

Member	Description
Shown	The interstitial was displayed.
Dismissed	The user closed the interstitial.
Clicked	The user clicked the interstitial.
Impression	The interstitial recorded an impression.

---