interstitial

Interstitial

Functions for loading and showing interstitial ads - full-screen ads shown at natural transition points in your game. Handle-based: create as many concurrent interstitial ads as you want, each with its own handle.

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.

• levelplay_interstitial_create
• levelplay_interstitial_load
• levelplay_interstitial_set_callback
• levelplay_interstitial_is_ready
• levelplay_interstitial_is_placement_capped
• levelplay_interstitial_show
• levelplay_interstitial_destroy
• levelplay_interstitial_get_live_handles

---

Back To Top

levelplay_interstitial_create

Constructs an interstitial ad instance for the given ad unit and returns a handle to it, attaching callback as its listener for the handle's whole lifetime. The handle is reusable across many load/show cycles - call levelplay_interstitial_destroy when you're truly done with it.

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:

levelplay_interstitial_create(ad_unit_id, callback)

Argument	Type	Description
ad_unit_id	String	The interstitial ad unit ID, from the LevelPlay dashboard.
callback	Function	The function to call for every lifecycle event on this handle.

Returns:

Real

A handle for use with the other levelplay_interstitial_* functions.

Triggers:

Callback

Fires once per lifecycle event: Loaded, LoadFailed, Displayed, DisplayFailed, Closed, Clicked, or InfoChanged.

Key	Type	Description
result	LevelPlayResult	The event's result. success is false only for LoadFailed/DisplayFailed.
type	LevelPlayCallbackEvent	Which lifecycle event this is.
ad_info	LevelPlayAdInfo	Information about the ad. Absent only if the SDK provided no ad-info object at all for this event.

Example:

on_interstitial_event = function(_result, _type, _ad_info)
{
    switch (_type)
    {
        case LevelPlayCallbackEvent.Loaded:
            levelplay_interstitial_show(handle);
            break;
        case LevelPlayCallbackEvent.LoadFailed:
            show_debug_message($"Interstitial failed to load: {_result.error_message}");
            break;
        case LevelPlayCallbackEvent.Closed:
            levelplay_interstitial_load(handle); // reload for next time
            break;
    }
};

handle = levelplay_interstitial_create("your_ad_unit_id", on_interstitial_event);
levelplay_interstitial_load(handle);

---

Back To Top

levelplay_interstitial_load

Requests a (re)load of the interstitial ad for this handle, using the callback given to levelplay_interstitial_create (or the last one set via levelplay_interstitial_set_callback).

Syntax:

levelplay_interstitial_load(handle)

Argument	Type	Description
handle	Real	A handle from levelplay_interstitial_create.

Returns:

LevelPlayError

LevelPlayError.Ok if the request was accepted, LevelPlayError.NotInitialized if levelplay_init hasn't completed, or LevelPlayError.InvalidHandle if handle isn't a live handle from levelplay_interstitial_create (or has already been destroyed).

---

Back To Top

levelplay_interstitial_set_callback

Replaces this handle's active callback - the one originally given to levelplay_interstitial_create - without reloading the ad. Only needed if you want a different callback than the one the handle already has; most usage never needs this.

Syntax:

levelplay_interstitial_set_callback(handle, callback)

Argument	Type	Description
handle	Real	A handle from levelplay_interstitial_create.
callback	Function	The function to use from now on for this handle's lifecycle events.

Returns:

LevelPlayError

LevelPlayError.Ok if the callback was replaced, or LevelPlayError.InvalidHandle if handle isn't a live handle.

---

Back To Top

levelplay_interstitial_is_ready

Returns whether the interstitial ad for this handle has finished loading and is ready to show. Returns false for an invalid handle.

Syntax:

levelplay_interstitial_is_ready(handle)

Argument	Type	Description
handle	Real	A handle from levelplay_interstitial_create.

Returns:

Boolean

---

Back To Top

levelplay_interstitial_is_placement_capped

Returns whether the given placement has reached its daily cap. Returns false for an empty or invalid placement.

Syntax:

levelplay_interstitial_is_placement_capped(placement_id)

Argument	Type	Description
placement_id	String	The placement to check.

Returns:

Boolean

---

Back To Top

levelplay_interstitial_show

Shows the interstitial ad for this handle. The handle stays valid after showing - call levelplay_interstitial_load again to reload it for another show.

Syntax:

levelplay_interstitial_show(handle, placement_id=undefined)

Argument	Type	Description
handle	Real	A handle from levelplay_interstitial_create.
placement_id	String	The placement to show the ad for. Omit for no specific placement.

Returns:

LevelPlayError

LevelPlayError.Ok if the show request was accepted, or one of LevelPlayError.ActivityUnavailable/InvalidHandle/AdNotReady/PlacementCapped otherwise.

---

Back To Top

levelplay_interstitial_destroy

Releases this handle's interstitial ad instance. No-op if the handle is already invalid.

Syntax:

levelplay_interstitial_destroy(handle)

Argument	Type	Description
handle	Real	A handle from levelplay_interstitial_create.

Returns:

N/A

---

Back To Top

levelplay_interstitial_get_live_handles

Returns every currently-live interstitial handle (created via levelplay_interstitial_create but not yet destroyed). Intended for leak detection during development - e.g. logging array_length(...) periodically to catch handles that are never destroyed.

Syntax:

levelplay_interstitial_get_live_handles()

Returns:

Array of Real

---