Skip to Content
defold-typescript libraries
tocaRepo

tocaRepo/defold-androidextension-ump/ump

Google User Messaging Platform consent API for Android. The table is absent on other platforms.

Functions

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.

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)
end

Parameters

  • 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.

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

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

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.

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.

On this page