applovin

Version: stable

FUNCTIONS
applovin.initialize()
applovin.set_callback()
applovin.is_initialized()
applovin.show_mediation_debugger()
applovin.set_has_user_consent()
applovin.has_user_consent()
applovin.set_do_not_sell()
applovin.is_do_not_sell()
applovin.set_terms_and_privacy_policy_flow_enabled()
applovin.set_privacy_policy_url()
applovin.set_terms_of_service_url()
applovin.set_consent_flow_debug_user_geography()
applovin.show_cmp_for_existing_user()
applovin.has_supported_cmp()
applovin.get_ump_dma_parameters()
applovin.is_tablet()
applovin.set_user_id()
applovin.set_muted()
applovin.is_muted()
applovin.set_verbose_logging_enabled()
applovin.is_verbose_logging_enabled()
applovin.set_creative_debugger_enabled()
applovin.set_test_device_advertising_ids()
applovin.track_event()
applovin.load_interstitial()
applovin.is_interstitial_ready()
applovin.show_interstitial()
applovin.set_interstitial_extra_parameter()
applovin.load_rewarded_ad()
applovin.is_rewarded_ad_ready()
applovin.show_rewarded_ad()
applovin.set_rewarded_ad_extra_parameter()
applovin.create_banner()
applovin.set_banner_background_color()
applovin.set_banner_placement()
applovin.set_banner_extra_parameter()
applovin.update_banner_position()
applovin.start_banner_auto_refresh()
applovin.stop_banner_auto_refresh()
applovin.show_banner()
applovin.hide_banner()
applovin.destroy_banner()
applovin.create_mrec()
applovin.set_mrec_placement()
applovin.set_mrec_extra_parameter()
applovin.update_mrec_position()
applovin.start_mrec_auto_refresh()
applovin.stop_mrec_auto_refresh()
applovin.show_mrec()
applovin.hide_mrec()
applovin.destroy_mrec()

CONSTANTS
CONSENT_FLOW_USER_GEOGRAPHY_UNKNOWN
CONSENT_FLOW_USER_GEOGRAPHY_GDPR
CONSENT_FLOW_USER_GEOGRAPHY_OTHER
APP_TRACKING_TRANSPARENCY_STATUS_UNAVAILABLE
APP_TRACKING_TRANSPARENCY_STATUS_NOT_DETERMINED
APP_TRACKING_TRANSPARENCY_STATUS_RESTRICTED
APP_TRACKING_TRANSPARENCY_STATUS_DENIED
APP_TRACKING_TRANSPARENCY_STATUS_AUTHORIZED

Functions

applovin.initialize()

applovin.initialize(sdk_key)

Initializes MAX asynchronously. Install the callback and apply privacy, consent-flow, user, logging, mute, creative-debugger, and test-device settings first. Do not load or show ads until `OnSdkInitializedEvent`. Calling this function with a placeholder or an SDK key that does not belong to the app is an integration error.

PARAMETERS

sdk_key string SDK key from MAX Dashboard > Account > General > Keys.

EXAMPLES

local function on_max_event(self, name, params)
    if name == "OnSdkInitializedEvent" then
        applovin.load_interstitial("YOUR_AD_UNIT_ID")
    end
end

function init(self)
    applovin.set_callback(on_max_event)
    applovin.set_test_device_advertising_ids({ "YOUR_IDFA_OR_GAID" })
    applovin.initialize("YOUR_SDK_KEY")
end

applovin.set_callback()

applovin.set_callback(callback)

Sets the callback that receives all MAX events on the Defold update thread. Replaces any previously installed callback. Pass `nil` to remove it. The callback signature is `function(self, name, params)`. `name` is one of the events below and `params` is a table. Lifecycle events: `OnSdkInitializedEvent`, `OnCmpCompletedEvent`. Interstitial events: `OnInterstitialAdLoadedEvent`, `OnInterstitialAdLoadFailedEvent`, `OnInterstitialAdDisplayedEvent`, `OnInterstitialAdDisplayFailedEvent`, `OnInterstitialAdHiddenEvent`, `OnInterstitialAdClickedEvent`, `OnInterstitialAdRevenuePaidEvent`. Rewarded events: `OnRewardedAdLoadedEvent`, `OnRewardedAdLoadFailedEvent`, `OnRewardedAdDisplayedEvent`, `OnRewardedAdDisplayFailedEvent`, `OnRewardedAdHiddenEvent`, `OnRewardedAdClickedEvent`, `OnRewardedAdReceivedRewardEvent`, `OnRewardedAdRevenuePaidEvent`. Banner events: `OnBannerAdLoadedEvent`, `OnBannerAdLoadFailedEvent`, `OnBannerAdClickedEvent`, `OnBannerAdExpandedEvent`, `OnBannerAdCollapsedEvent`, `OnBannerAdRevenuePaidEvent`. MREC events: `OnMRecAdLoadedEvent`, `OnMRecAdLoadFailedEvent`, `OnMRecAdClickedEvent`, `OnMRecAdExpandedEvent`, `OnMRecAdCollapsedEvent`, `OnMRecAdRevenuePaidEvent`. `OnSdkInitializedEvent` params: `countryCode` (string), `consentFlowUserGeography` (number), `isTestModeEnabled` (boolean), and `appTrackingStatus` (number, iOS only). `OnCmpCompletedEvent` has an empty params table on success. On failure it contains `code` (number), `message` (string), `cmpCode` (number), and `cmpMessage` (string). Successful ad, display, click, hide, expand, collapse, reward, and revenue events include ad information: `adUnitIdentifier`, `format`, `networkName`, `networkPlacement`, `creativeIdentifier`, `placement`, `revenue`, `revenuePrecision`, `requestLatencyMillis`, `dspName`, and `dspIdentifier`. Values unavailable from a mediated network may be empty or absent. Revenue is in USD and may be `0`; use `revenuePrecision` before interpreting it. `OnRewardedAdReceivedRewardEvent` additionally includes `label` (string) and `amount` (number). Load failures include `adUnitIdentifier`, `code`, `message`, and `requestLatencyMillis`. Display failures include available ad information plus `code`, `message`, `mediatedNetworkErrorCode`, and `mediatedNetworkErrorMessage`; their `requestLatencyMillis` is the ad request latency. Error codes and messages come from MAX and, for display failures, the mediated network.

PARAMETERS

callback

function

Event callback, or `nil` to remove the callback.

`self`	`object`	Script instance that installed the callback.
`name`	`string`	Event name.
`params`	`table`	Event payload.

applovin.is_initialized()

applovin.is_initialized()

Returns whether asynchronous SDK initialization has completed.

PARAMETERS

None

RETURNS

boolean

applovin.show_mediation_debugger()

applovin.show_mediation_debugger()

Shows the MAX Mediation Debugger. Use this only after SDK initialization and from a user action.

PARAMETERS

None

applovin.set_has_user_consent()

applovin.set_has_user_consent(has_user_consent)

Sets the user's legally obtained consent state for interest-based advertising. Apply the value before `initialize()`. This API does not collect consent.

PARAMETERS

has_user_consent boolean

applovin.has_user_consent()

applovin.has_user_consent()

Returns the current user-consent value. The API cannot distinguish an explicit `false` from a value your application never set, so persist and apply your consent decision.

PARAMETERS

None

RETURNS

boolean

applovin.set_do_not_sell()

applovin.set_do_not_sell(do_not_sell)

Sets whether the user opted out of sale or sharing of personal information. Apply the legally obtained value before `initialize()`.

PARAMETERS

do_not_sell boolean

applovin.is_do_not_sell()

applovin.is_do_not_sell()

Returns the current do-not-sell value. The API cannot distinguish an explicit `false` from a value your application never set.

PARAMETERS

None

RETURNS

boolean

applovin.set_terms_and_privacy_policy_flow_enabled()

applovin.set_terms_and_privacy_policy_flow_enabled(enabled)

Enables or disables MAX's Terms and Privacy Policy Flow. Configure the required CMP dependencies, dashboard message, privacy-policy URL, and iOS/Android app metadata first. Set this before `initialize()`.

PARAMETERS

enabled boolean

applovin.set_privacy_policy_url()

applovin.set_privacy_policy_url(url)

Sets the public HTTPS privacy-policy URL used by the MAX consent flow before initialization.

PARAMETERS

url string

applovin.set_terms_of_service_url()

applovin.set_terms_of_service_url(url)

Sets the optional public HTTPS Terms of Service URL used by the MAX consent flow before initialization.

PARAMETERS

url string

applovin.set_consent_flow_debug_user_geography()

applovin.set_consent_flow_debug_user_geography(geography)

Overrides geography for consent-flow testing. Pass `"GDPR"` or `"OTHER"`. Use only in development and set it before initialization.

PARAMETERS

geography string

applovin.show_cmp_for_existing_user()

applovin.show_cmp_for_existing_user()

Shows the integrated CMP for an existing user. Offer this from a privacy-settings action only when `has_supported_cmp()` is true; completion arrives as `OnCmpCompletedEvent`.

PARAMETERS

None

applovin.has_supported_cmp()

applovin.has_supported_cmp()

Returns whether a supported CMP is integrated and available.

PARAMETERS

None

RETURNS

boolean

applovin.get_ump_dma_parameters()

applovin.get_ump_dma_parameters()

Returns DMA consent parameters from the current Google UMP/IAB TCF storage on Android and iOS. Read after the consent flow completes and again after consent changes. This function does not display a consent form or update any SDK's consent settings. Missing or unreadable consent values are treated as false. All fields are false unless Adjust (ATP ID 2822) appears in the Additional Consent consented-provider list.

PARAMETERS

None

RETURNS

table Boolean fields: `adjustConsent` indicates consent for Adjust; `adUserData` also requires TCF purpose 1; `adPersonalization` also requires TCF purposes 2 and 4.

applovin.is_tablet()

applovin.is_tablet()

Returns whether the current device uses the SDK's tablet classification.

PARAMETERS

None

RETURNS

boolean

applovin.set_user_id()

applovin.set_user_id(user_id)

Sets your internal user identifier. Do not use personally identifiable information. Set it before initialization when it must be available to mediated networks.

PARAMETERS

user_id string

applovin.set_muted()

applovin.set_muted(muted)

Requests muted audio for mediated networks that support the setting.

PARAMETERS

muted boolean

applovin.is_muted()

applovin.is_muted()

Returns the current mute setting.

PARAMETERS

None

RETURNS

boolean

applovin.set_verbose_logging_enabled()

applovin.set_verbose_logging_enabled(enabled)

Enables or disables verbose MAX logging. Enable it for integration testing, not production.

PARAMETERS

enabled boolean

applovin.is_verbose_logging_enabled()

applovin.is_verbose_logging_enabled()

Returns the current verbose-logging setting.

PARAMETERS

None

RETURNS

boolean

applovin.set_creative_debugger_enabled()

applovin.set_creative_debugger_enabled(enabled)

Enables or disables the MAX Creative Debugger for QA builds.

PARAMETERS

enabled boolean

applovin.set_test_device_advertising_ids()

applovin.set_test_device_advertising_ids(advertising_ids)

Sets devices that should receive test ads. Pass an array of IDFAs on iOS or GAIDs on Android before `initialize()`. Never ship another user's advertising identifier.

PARAMETERS

advertising_ids array Array of advertising-identifier strings.

applovin.track_event()

applovin.track_event(event_name,parameters)

Tracks a custom AppLovin event after SDK initialization with JSON string parameters. `event_name` must be non-empty. Invalid JSON or a non-object value is logged and sent as an empty parameter map.

PARAMETERS

`event_name`	`string`	Non-empty event name.
`parameters`	`string`	JSON object encoded as a string, for example `"{\"level\":\"5\"}"`.

applovin.load_interstitial()

applovin.load_interstitial(ad_unit_id)

Starts loading an interstitial. Call only after `OnSdkInitializedEvent`.

PARAMETERS

ad_unit_id string

applovin.is_interstitial_ready()

applovin.is_interstitial_ready(ad_unit_id)

Returns whether an interstitial is ready for the ad unit.

PARAMETERS

ad_unit_id string

RETURNS

boolean

applovin.show_interstitial()

applovin.show_interstitial(ad_unit_id,placement)

Shows a loaded interstitial, optionally attributing it to a placement.

PARAMETERS

`ad_unit_id`	`string`
`placement`	`string`	MAX placement name.

applovin.set_interstitial_extra_parameter()

applovin.set_interstitial_extra_parameter(ad_unit_id,key,value)

Sets a MAX-supported extra parameter on an interstitial ad object.

PARAMETERS

`ad_unit_id`	`string`
`key`	`string`
`value`	`string`

applovin.load_rewarded_ad()

applovin.load_rewarded_ad(ad_unit_id)

Starts loading a rewarded ad. Call only after `OnSdkInitializedEvent`.

PARAMETERS

ad_unit_id string

applovin.is_rewarded_ad_ready()

applovin.is_rewarded_ad_ready(ad_unit_id)

Returns whether a rewarded ad is ready for the ad unit.

PARAMETERS

ad_unit_id string

RETURNS

boolean

applovin.show_rewarded_ad()

applovin.show_rewarded_ad(ad_unit_id,placement)

Shows a loaded rewarded ad, optionally attributing it to a placement.

PARAMETERS

`ad_unit_id`	`string`
`placement`	`string`	MAX placement name.

applovin.set_rewarded_ad_extra_parameter()

applovin.set_rewarded_ad_extra_parameter(ad_unit_id,key,value)

Sets a MAX-supported extra parameter on a rewarded ad object.

PARAMETERS

`ad_unit_id`	`string`
`key`	`string`
`value`	`string`

applovin.create_banner()

applovin.create_banner(ad_unit_id,position)

Creates and starts loading a banner at the requested screen position.

PARAMETERS

`ad_unit_id`	`string`
`position`	`string`	`top_left`, `top_center`, `top_right`, `centered`, `bottom_left`, `bottom_center`, or `bottom_right`.

applovin.set_banner_background_color()

applovin.set_banner_background_color(ad_unit_id,hex_color)

Sets a banner's background color.

PARAMETERS

`ad_unit_id`	`string`
`hex_color`	`string`	Color in `#RRGGBB` or `#AARRGGBB` form.

applovin.set_banner_placement()

applovin.set_banner_placement(ad_unit_id,placement)

Sets the MAX placement name for a banner ad unit. Call this before `create_banner()` so the placement is attached to the first load; calling it later updates the existing view.

PARAMETERS

`ad_unit_id`	`string`
`placement`	`string`

applovin.set_banner_extra_parameter()

applovin.set_banner_extra_parameter(ad_unit_id,key,value)

Sets a MAX-supported extra parameter on an existing banner.

PARAMETERS

`ad_unit_id`	`string`
`key`	`string`
`value`	`string`

applovin.update_banner_position()

applovin.update_banner_position(ad_unit_id,position)

Moves an existing banner to a supported screen position.

PARAMETERS

`ad_unit_id`	`string`
`position`	`string`	`top_left`, `top_center`, `top_right`, `centered`, `bottom_left`, `bottom_center`, or `bottom_right`.

applovin.start_banner_auto_refresh()

applovin.start_banner_auto_refresh(ad_unit_id)

Starts auto-refresh on an existing banner.

PARAMETERS

ad_unit_id string

applovin.stop_banner_auto_refresh()

applovin.stop_banner_auto_refresh(ad_unit_id)

Stops auto-refresh on an existing banner.

PARAMETERS

ad_unit_id string

applovin.show_banner()

applovin.show_banner(ad_unit_id)

Shows an existing banner.

PARAMETERS

ad_unit_id string

applovin.hide_banner()

applovin.hide_banner(ad_unit_id)

Hides an existing banner without destroying it.

PARAMETERS

ad_unit_id string

applovin.destroy_banner()

applovin.destroy_banner(ad_unit_id)

Destroys a banner and releases its native view.

PARAMETERS

ad_unit_id string

applovin.create_mrec()

applovin.create_mrec(ad_unit_id,position)

Creates and starts loading an MREC at the requested screen position.

PARAMETERS

`ad_unit_id`	`string`
`position`	`string`	`top_left`, `top_center`, `top_right`, `centered`, `bottom_left`, `bottom_center`, or `bottom_right`.

applovin.set_mrec_placement()

applovin.set_mrec_placement(ad_unit_id,placement)

Sets the MAX placement name for an MREC ad unit. Call this before `create_mrec()` so the placement is attached to the first load; calling it later updates the existing view.

PARAMETERS