defold/extension-levelplay/levelplay
Functions and constants for Unity LevelPlay mediation on Android and iOS.
- GitHub: defold/extension-levelplay — pinned to
2.0.1(released while Defold 1.13.1 was current)- Pick a release from defold/extension-levelplay releases and add its Source code (zip) URL (or a packaged
.zipasset, if the library ships one) togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as levelplay from "levelplay"
- Pick a release from defold/extension-levelplay releases and add its Source code (zip) URL (or a packaged
Functions
levelplay.set_callback(callback?: function)levelplay.init(app_key: string, user_id?: string)levelplay.get_sdk_version(): stringlevelplay.set_gdpr_consent(consent: boolean)levelplay.set_ccpa(opted_out: boolean)levelplay.set_coppa(child_directed: boolean)levelplay.set_metadata(key: string, value: string)levelplay.set_meta_limited_data_use(enabled: boolean, country?: number, state?: number): booleanlevelplay.set_meta_advertiser_tracking(enabled: boolean): booleanlevelplay.set_dynamic_user_id(user_id: string): booleanlevelplay.set_adapters_debug(enabled: boolean)levelplay.validate_integration()levelplay.launch_test_suite()levelplay.request_tracking_authorization()levelplay.get_tracking_authorization_status(): numberlevelplay.create_interstitial_ad(ad_unit_id: string, bid_floor?: number): numberlevelplay.destroy_interstitial_ad(handle: number)levelplay.load_interstitial_ad(handle: number)levelplay.is_interstitial_ad_ready(handle: number): booleanlevelplay.show_interstitial_ad(handle: number, placement?: string)levelplay.is_interstitial_placement_capped(placement: string): booleanlevelplay.create_rewarded_ad(ad_unit_id: string, bid_floor?: number): numberlevelplay.destroy_rewarded_ad(handle: number)levelplay.load_rewarded_ad(handle: number)levelplay.is_rewarded_ad_ready(handle: number): booleanlevelplay.show_rewarded_ad(handle: number, placement?: string)levelplay.is_rewarded_placement_capped(placement: string): booleanlevelplay.get_reward(handle: number, placement?: string): tablelevelplay.create_banner_ad(ad_unit_id: string, options?: table): numberlevelplay.load_banner_ad(handle: number)levelplay.show_banner_ad(handle: number)levelplay.hide_banner_ad(handle: number)levelplay.pause_banner_auto_refresh(handle: number)levelplay.resume_banner_auto_refresh(handle: number)levelplay.destroy_banner_ad(handle: number)
levelplay.set_callback(callback?: function)
Sets the callback used for all LevelPlay events. Pass nil to remove it.
Parameters
callback?:functionself:object— The script instance that installed the callback.message_id:number— One of MSG_INIT, MSG_INTERSTITIAL, MSG_REWARDED, MSG_BANNER, or MSG_TRACKING.message:table— Event data. Every asynchronous SDK event containsevent. Events from a created ad object also containhandle; pre-creation validation errors do not.event:number— An EVENT_* constant, or a TRACKING_STATUS_* constant for MSG_TRACKING.handle?:number— The ad object that emitted the event.error_code?:numbererror_message?:stringerror_domain?:string— Native error domain when supplied by iOS.operation?:string— Bridge operation associated with a validation error.error?:string— Serialization error detail for EVENT_JSON_ERROR.ad_quality_enabled?:boolean— Whether Ad Quality is enabled, when reported during initialization.ad_id?:stringad_unit_id?:stringad_unit_name?:stringad_format?:stringplacement_name?:stringauction_id?:stringcountry?:stringab?:stringsegment_name?:stringad_network?:stringinstance_name?:stringinstance_id?:stringrevenue?:numberprecision?:stringencrypted_cpm?:stringcreative_id?:stringconversion_value?:number— Conversion value when supplied by iOS.reward_name?:stringreward_amount?:numberad_width?:numberad_height?:numberad_size_description?:stringad_size_is_adaptive?:boolean
levelplay.init(app_key: string, user_id?: string)
Initializes LevelPlay. Configure privacy before calling this function. Create ad objects only after EVENT_INIT_SUCCEEDED.
Parameters
app_key:string— Application key from the LevelPlay dashboard. This is not an ad-unit ID.user_id?:string— Stable application user ID included in the initialization request.
levelplay.get_sdk_version(): string
Returns the native LevelPlay SDK version.
Returns
version?:string
levelplay.set_gdpr_consent(consent: boolean)
Passes the user's GDPR consent choice to LevelPlay and supported mediated networks. It does not display a consent form or read another extension's private state. For a custom or non-compatible CMP, call it before init with the collected choice. LevelPlay SDK 7.7.0 and newer automatically reads Google UMP and compatible Google Additional Consent signals, so do not also pass the same choice with this function in that setup.
Parameters
consent:boolean
levelplay.set_ccpa(opted_out: boolean)
Passes a US privacy "do not sell or share" choice. True means the user opted out. Call before init.
Parameters
opted_out:boolean
levelplay.set_coppa(child_directed: boolean)
Sets whether the user is child-directed for COPPA treatment. True flags the user as child-directed. Call before init.
Parameters
child_directed:boolean
levelplay.set_metadata(key: string, value: string)
Sets an SDK or mediated-network metadata value. Set network-required values before init.
Parameters
key:stringvalue:string
levelplay.set_meta_limited_data_use(enabled: boolean, country?: number, state?: number): boolean
Configures Meta Audience Network Limited Data Use before init. This calls Meta's SDK directly and returns false if the Meta adapter is not linked or initialization already started.
Parameters
enabled:boolean— True supplies the LDU option; false clears Meta data-processing options.country?:number— Meta country code. Zero, the default, asks Meta to geolocate.state?:number— Meta state code. Zero, the default, asks Meta to geolocate.
Returns
applied:boolean
levelplay.set_meta_advertiser_tracking(enabled: boolean): boolean
Sets Meta Audience Network's iOS advertiser-tracking flag before init. Returns false on Android, when Meta is not linked, or after initialization starts.
Parameters
enabled:boolean
Returns
applied:boolean
levelplay.set_dynamic_user_id(user_id: string): boolean
Sets the dynamic user ID used by server-to-server rewarded callbacks. The value must contain 1–64 alphanumeric characters. Call before showing the rewarded ad it should apply to.
Parameters
user_id:string
Returns
accepted:boolean
levelplay.set_adapters_debug(enabled: boolean)
Enables or disables mediated-network debug logging. Disable it in production.
Parameters
enabled:boolean
levelplay.validate_integration()
Runs the native LevelPlay integration validator.
levelplay.launch_test_suite()
Opens the LevelPlay integration test suite after initialization succeeds. Enable the is_test_suite metadata before init and call this before creating ad objects or invoking other LevelPlay SDK operations.
levelplay.request_tracking_authorization()
Requests App Tracking Transparency authorization on iOS 14 or newer. Request it before init when mediation partners should receive the IDFA. The result is sent through MSG_TRACKING. It is a no-op on Android and unsupported iOS versions.
levelplay.get_tracking_authorization_status(): number
Returns the current App Tracking Transparency state on iOS, or nil when unsupported.
Returns
status?:number— One of TRACKING_STATUS_NOT_DETERMINED, TRACKING_STATUS_RESTRICTED, TRACKING_STATUS_DENIED, or TRACKING_STATUS_AUTHORIZED.
levelplay.create_interstitial_ad(ad_unit_id: string, bid_floor?: number): number
Creates a reusable interstitial ad object after successful initialization. Its ad-unit ID and optional bid floor are fixed for the object's lifetime. Create it once, then use the returned handle for multiple load/show cycles with the same ad-unit ID and creation configuration.
Parameters
ad_unit_id:string— Interstitial ad-unit ID from the LevelPlay dashboard.bid_floor?:number— Optional minimum eCPM in USD. It applies to every load by this object; changing it requires destroying the handle and creating a new object.
Returns
handle?:number— Positive handle, or nil when native creation is rejected.
levelplay.destroy_interstitial_ad(handle: number)
Permanently releases an interstitial ad object, invalidates its handle, and stops callbacks for it. Do not destroy between ordinary impressions or during load/display when terminal callbacks are still required.
Parameters
handle:number
levelplay.load_interstitial_ad(handle: number)
Loads the next interstitial impression into an existing object. After an impression closes, call this again on the same handle instead of creating another object.
Parameters
handle:number
levelplay.is_interstitial_ad_ready(handle: number): boolean
Returns whether the interstitial object has an ad ready to display.
Parameters
handle:number
Returns
ready:boolean
levelplay.show_interstitial_ad(handle: number, placement?: string)
Shows one loaded interstitial impression. The optional placement is a dashboard presentation point, not an ad object, and can be selected separately on every show.
Parameters
handle:numberplacement?:string
levelplay.is_interstitial_placement_capped(placement: string): boolean
Returns whether the named interstitial placement has reached its configured cap.
Parameters
placement:string
Returns
capped:boolean
levelplay.create_rewarded_ad(ad_unit_id: string, bid_floor?: number): number
Creates a reusable rewarded ad object after successful initialization. Its ad-unit ID and optional bid floor are fixed for the object's lifetime. Create it once, then use the returned handle for multiple load/show cycles with the same ad-unit ID and creation configuration.
Parameters
ad_unit_id:string— Rewarded ad-unit ID from the LevelPlay dashboard.bid_floor?:number— Optional minimum eCPM in USD. It applies to every load by this object; changing it requires destroying the handle and creating a new object.
Returns
handle?:number— Positive handle, or nil when native creation is rejected.
levelplay.destroy_rewarded_ad(handle: number)
Permanently releases a rewarded ad object, invalidates its handle, and stops callbacks for it. Do not destroy between ordinary impressions, and never destroy a displayed rewarded ad before its reward and close callbacks are received.
Parameters
handle:number
levelplay.load_rewarded_ad(handle: number)
Loads the next rewarded impression into an existing object. After reward and close callbacks complete, call this again on the same handle instead of creating another object.
Parameters
handle:number
levelplay.is_rewarded_ad_ready(handle: number): boolean
Returns whether the rewarded object has an ad ready to display.
Parameters
handle:number
Returns
ready:boolean
levelplay.show_rewarded_ad(handle: number, placement?: string)
Shows one loaded rewarded impression. The optional placement is a dashboard presentation point, not an ad object, and can be selected separately on every show.
Parameters
handle:numberplacement?:string
levelplay.is_rewarded_placement_capped(placement: string): boolean
Returns whether the named rewarded placement has reached its configured cap.
Parameters
placement:string
Returns
capped:boolean
levelplay.get_reward(handle: number, placement?: string): table
Returns the configured reward for the object's default placement or for the supplied placement.
Parameters
handle:numberplacement?:string
Returns
reward?:tablename:stringamount:number
levelplay.create_banner_ad(ad_unit_id: string, options?: table): number
Creates a reusable banner ad view after successful initialization. Its ad-unit ID and all options are fixed for the view's lifetime. Create it once, then load, hide, show, and auto-refresh the same handle until it is permanently destroyed.
Parameters
ad_unit_id:string— Banner ad-unit ID from the LevelPlay dashboard.options?:table— Creation-time banner configuration. These fields apply to every load and show; changing one requires destroying the handle and creating a new banner.size?:number— A BANNER_SIZE_* constant. Defaults to BANNER_SIZE_ADAPTIVE.position?:number— BANNER_POSITION_TOP or BANNER_POSITION_BOTTOM. Defaults to BANNER_POSITION_BOTTOM.placement?:string— Dashboard placement used for reporting by this banner object.bid_floor?:number— Minimum eCPM in USD applied to every load by this banner object.respect_safe_area?:boolean— Whether the banner avoids system bars and display cutouts. Defaults to true.
Returns
handle?:number— Positive handle, or nil when native creation is rejected.
levelplay.load_banner_ad(handle: number)
Loads and displays a banner because the native LevelPlay banner view is visible by default.
Parameters
handle:number
levelplay.show_banner_ad(handle: number)
Makes the banner view visible.
Parameters
handle:number
levelplay.hide_banner_ad(handle: number)
Hides the banner without destroying it.
Parameters
handle:number
levelplay.pause_banner_auto_refresh(handle: number)
Pauses automatic refresh for the banner.
Parameters
handle:number
levelplay.resume_banner_auto_refresh(handle: number)
Resumes automatic refresh for the banner.
Parameters
handle:number
levelplay.destroy_banner_ad(handle: number)
Removes and destroys the banner view and invalidates its handle.
Parameters
handle:number
Constants
levelplay.MSG_INIT
Initialization events.
levelplay.MSG_INTERSTITIAL
Interstitial-object events.
levelplay.MSG_REWARDED
Rewarded-object events.
levelplay.MSG_BANNER
Banner-object events.
levelplay.MSG_TRACKING
App Tracking Transparency status events.