tocaRepo/defold-androidextension-ump/ump
Google User Messaging Platform consent API for Android. The table is absent on other platforms.
- GitHub: tocaRepo/defold-androidextension-ump — pinned to
v4.0.2(released while Defold 1.13.2 was current)- Pick a release from tocaRepo/defold-androidextension-ump 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 ump from "ump"
- Pick a release from tocaRepo/defold-androidextension-ump releases and add its Source code (zip) URL (or a packaged
- Asset Portal: defold-androidextension-ump
Functions
ump.request_consent_info_update(test_device: boolean, test_device_hashed_id: string, callback?: function, defer_form?: boolean)ump.show_consent_form_if_required(callback?: function)ump.show_privacy_options_form(callback?: function)ump.is_privacy_options_required(): booleanump.can_request_ads(): booleanump.get_consent_status(): numberump.get_request_state(): numberump.was_consent_form_required(): booleanump.get_privacy_options_state(): numberump.get_gdpr_applies(): numberump.get_purpose_consents(): stringump.reset_consent_information()ump.initialize_mobile_ads_sdk()
ump.request_consent_info_update(test_device: boolean, test_device_hashed_id: string, callback?: function, defer_form?: boolean)
Request fresh consent information and show a consent form if required. Call on every launch. The callback runs on the Defold update thread after the update and any required form finish unless defer_form is true. In deferred mode the callback runs after the information update, before any form opens; call show_consent_form_if_required to finish the flow. A successful callback means no UMP error, not consent to personalized ads.
ump.request_consent_info_update(false, "", function(self, success)
if success and ump.can_request_ads() then
print("Ads can be requested")
end
end)Parameters
test_device:boolean— Enable UMP debug mode and force EEA geography for the registered test device.test_device_hashed_id:string— Hashed test device ID. Pass an empty string when test_device is false.callback?:function— Called when the update and any required form finish.self:object— Calling script instance.success:boolean— False if the consent information update or form failed.
defer_form?:boolean— Pause after the information update so an application notice can precede a required form. Defaults to false.
ump.show_consent_form_if_required(callback?: function)
Continue a successful deferred consent-information update. Check was_consent_form_required() to decide whether to show an application notice first. Call only once, after that notice has closed. The callback runs after the required form closes or fails, or immediately if no form is required. Advertising must wait for this callback.
Parameters
callback?:function— Called when the form step finishes.self:object— Calling script instance.success:boolean— False if the form could not be loaded or shown.
ump.show_privacy_options_form(callback?: function)
Open the UMP privacy-options form in response to user input. Check is_privacy_options_required() first. A successful callback means the form closed without an error, not that the user granted consent.
if ump.is_privacy_options_required() then
ump.show_privacy_options_form(function(self, success)
if success then print("Privacy options closed") end
end)
endParameters
callback?:function— Called after the privacy-options form is dismissed or fails.self:object— Calling script instance.success:boolean— False if the form could not be shown or completed.
ump.is_privacy_options_required(): boolean
Whether UMP requires a privacy-options entry point. Returns false before consent information is available.
Returns
required:boolean— True when a privacy-options entry point is required.
ump.can_request_ads(): boolean
UMP ad-request eligibility. Check after the current update callback. Before then, this can reflect consent stored from an earlier session.
Returns
allowed:boolean— True when UMP allows ad requests.
ump.get_consent_status(): number
Google consent status: 0 unknown, 1 not required, 2 required, 3 obtained. Returns -1 before the consent-information object exists. Status 3 does not distinguish personalized from non-personalized advertising.
Returns
status:number— UMP consent status or -1 if unavailable.
ump.get_request_state(): number
Diagnostic state of the latest consent information update and form. Prefer the request callback to polling this value.
Returns
state:number— One of ump.REQUEST_STATE_UPDATING, ump.REQUEST_STATE_FORM_PENDING, ump.REQUEST_STATE_COMPLETE, or ump.REQUEST_STATE_FAILED.
ump.was_consent_form_required(): boolean
Whether the latest successful information update found a required normal consent form. Resets when a new update starts. May remain true if that form later fails.
Returns
required:boolean— True if the latest successful update required a form.
ump.get_privacy_options_state(): number
Diagnostic state of the latest privacy-options form.
Returns
ump.get_gdpr_applies(): number
Read IABTCF_gdprApplies from Android default preferences after a successful UMP update. This is a GDPR applicability signal, not a country code or vendor consent.
Returns
value:number— ump.GDPR_APPLIES_NO, ump.GDPR_APPLIES_YES, or ump.GDPR_APPLIES_UNKNOWN if missing or invalid.
ump.get_purpose_consents(): string
Read the raw IABTCF_PurposeConsents bit string from Android default preferences. Call after a successful UMP update or privacy-options callback. The third character represents TCF Purpose 3 consent.
Returns
value:string— Raw purpose-consent bit string, or nil if unavailable.
ump.reset_consent_information()
Clear UMP consent information for testing if its object has been created. Start a new request afterward. Diagnostic request/form states are not reset by this call.
ump.initialize_mobile_ads_sdk()
Legacy, nonfunctional export. Its required Java method is absent from this extension. Do not call it. If using the Defold AdMob extension, call admob.initialize() after the UMP flow instead.
Constants
ump.REQUEST_STATE_UPDATING
0; initial state or consent information update in progress.
ump.REQUEST_STATE_COMPLETE
1; update and form step finished without a UMP error.
ump.REQUEST_STATE_FAILED
2; information update or form failed.
ump.REQUEST_STATE_FORM_PENDING
3; update succeeded and the form step is waiting or in progress.
ump.PRIVACY_OPTIONS_STATE_NOT_SHOWN
0; initial privacy-options state.
ump.PRIVACY_OPTIONS_STATE_SHOWING
1; privacy-options request in progress.
ump.PRIVACY_OPTIONS_STATE_DISMISSED
2; privacy-options form closed without a UMP error.
ump.PRIVACY_OPTIONS_STATE_ERROR
3; privacy-options form failed.
ump.GDPR_APPLIES_UNKNOWN
-1; IAB TCF GDPR applicability value missing or invalid.
ump.GDPR_APPLIES_NO
0; IAB TCF value says GDPR does not apply.
ump.GDPR_APPLIES_YES
1; IAB TCF value says GDPR applies.