Get started

The Google User Messaging Platform (UMP) SDK is a privacy and messaging tool to help you manage privacy choices. For more information, see About Privacy & messaging.

Create a message type

Create user messages with one of the Available user message types under the Privacy & messaging tab of your AdMob account. The UMP SDK attempts to display a privacy message created from the AdMob Application ID set in your project.

For more details, see About privacy and messaging.

Add the application ID

You can find your application ID in the AdMob UI. Add the ID to your with the following code snippet:

Request for consent information

You should request an update of the user's consent information at every app launch, using requestConsentInfoUpdate(). This request checks the following:

• Whether consent is required. For example, consent is required for the first time, or the previous consent decision expired.
• Whether a privacy options entry point is required. Some privacy messages require apps to allow users to modify their privacy options at any time.

Here is an example of how to check the status on app start:

@override
void initState() {
  super.initState();

  // Create a ConsentRequestParameters object.
  final params = ConsentRequestParameters();

  // Request an update for the consent information.
  ConsentInformation.instance.requestConsentInfoUpdate(
    params,
    () async {
      // TODO: Load and present the privacy message form.
    },
    (FormError error) {
      // Handle the error.
    },
  );
}

Warning: Using other ways of checking consent status, such as the cache on your app or a previously saved consent string, could lead to a TCF 3.3 error if consent is expired.

Load and present a privacy message form if required

Important: The following APIs are compatible with UMP SDK version 2.1.0 or higher.

After you have received the most up-to-date consent status, call loadAndShowConsentFormIfRequired() to load any forms required to collect user consent. After loading, the forms present immediately.

@override
void initState() {
  super.initState();

  // Create a ConsentRequestParameters object.
  final params = ConsentRequestParameters();

  // Request an update for the consent information.
  ConsentInformation.instance.requestConsentInfoUpdate(
    params,
    () async {
      ConsentForm.loadAndShowConsentFormIfRequired((loadAndShowError) {
        if (loadAndShowError != null) {
          // Consent gathering failed.
        }

        // Consent has been gathered.
      });
    },
    (FormError error) {
      // Handle the error.
    },
  );
}

Key Point: If no privacy message forms require collection of user consent prior to requesting ads, the callback is invoked immediately.

If you need to perform any actions after the user has made a choice or dismissed the form, place that logic in the callback for your form.

Privacy options

Some privacy message forms are presented from a publisher-rendered privacy options entry point, letting users manage their privacy options at any time. To learn more about which message your users see at the privacy options entry point, see Available user message types.

To implement a privacy options entry point, complete the following steps:

1. Check getPrivacyOptionsRequirementStatus().
2. If a privacy options entry point is required, add a visible and interactable UI element to your app.
3. Trigger the privacy options form using showPrivacyOptionsForm().

The following code example demonstrates these steps:

class AppExampleState extends State<AppExample> {
  static const _privacySettingsText = 'Privacy Settings';

  // Use a bool to initialize the Mobile Ads SDK and load ads once.
  var _isMobileAdsInitializeCalled = false;

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'App Example',
      home: Scaffold(
          appBar: AppBar(
            title: const Text('App Example'),
            actions: _isMobileAdsSDKInitialized
                // Regenerate the options menu to include a privacy setting.
                ? _privacySettingsAppBarAction()
                : null
          ),
          body: // ...
      ),
    );
  }

  List<Widget> _privacySettingsAppBarAction() {
    return <Widget>[
      FutureBuilder(
          future: ConsentInformation.instance.isPrivacyOptionsRequired(),
          builder: (context, snapshot) {
            final bool visibility = snapshot.data ?? false;
            return Visibility(
                visible: visibility,
                child: PopupMenuButton<String>(
                  onSelected: (String result) {
                    if (result == _privacySettingsText) {
                      ConsentForm.showPrivacyOptionsForm((formError) {
                        if (formError != null) {
                          debugPrint(
                              "${formError.errorCode}: ${formError.message}");
                        }
                      });
                    }
                  },
                  itemBuilder: (BuildContext context) =>
                      <PopupMenuEntry<String>>[
                    const PopupMenuItem<String>(
                        value: _privacySettingsText,
                        child: Text(_privacySettingsText))
                  ],
                ));
          })
    ];
  }
}

Request ads

Before requesting ads in your app, check if you have obtained consent from the user using canRequestAds(). There are two places to check while gathering consent:

• After consent has been gathered in the current session.
• Immediately after you have called requestConsentInfoUpdate(). It is possible consent has been obtained in the previous session. As a latency best practice, we recommend not waiting for the callback to complete so you can start loading ads as soon as possible after your app launches.

Note: canRequestAds() always returns false until you have called requestConsentInfoUpdate()

If an error occurs during the consent gathering process, you should still attempt to request ads. The UMP SDK uses the consent status from the previous session.

class AppExampleState extends State<AppExample> {

  // Use a bool to initialize the Mobile Ads SDK and load ads once.
  var _isMobileAdsInitializeCalled = false;

  @override
  void initState() {
    super.initState();

    // Create a ConsentRequestParameters object.
    final params = ConsentRequestParameters();

    // Request an update for the consent information.
    ConsentInformation.instance.requestConsentInfoUpdate(
      params,
      () async {
        ConsentForm.loadAndShowConsentFormIfRequired((loadAndShowError) {
          if (loadAndShowError != null) {
            // Consent gathering failed.
          }

          // Consent has been gathered.
          _initializeMobileAdsSDK();
        });
      },
      (FormError error) {
        // Handle the error.
      },
    );

    // Check if you can initialize the Mobile Ads SDK in parallel while
    // checking for new consent information. Consent obtained in the
    // previous session can be used to request ads.
    _initializeMobileAdsSDK();
  }

  void _initializeMobileAdsSDK() async {
    if (_isMobileAdsInitializeCalled) {
      return;
    }

    // Initialize the Mobile Ads SDK if the SDK has gathered consent aligned with
    // the app's configured messages.
    var canRequestAds = await ConsentInformation.instance.canRequestAds();
    if (canRequestAds) {
      setState(() {
        _isMobileAdsInitializeCalled = true;
      });

      // Initialize the Mobile Ads SDK.
      MobileAds.instance.initialize();

      // TODO: Request an ad.
    }
  }
}

Testing

If you want to test the integration in your app as you're developing, follow these steps to programmatically register your test device. Be sure to remove the code that sets these test device IDs before you release your app.

1. Call requestConsentInfoUpdate().

2. Check the log output for a message similar to the following example, which shows your device ID and how to add it as a test device:

   Android

   Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231")
   to set this as a debug device.
   

   iOS

   <UMP SDK>To enable debug mode for this device,
   set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]
   

3. Copy your test device ID to your clipboard.

4. Modify your code to call ConsentDebugSettings.testIdentifiers and pass in a list of your test device IDs.

   ConsentDebugSettings debugSettings = ConsentDebugSettings(
     testIdentifiers: ["TEST-DEVICE-HASHED-ID"],
   );
   
   ConsentRequestParameters params =
       ConsentRequestParameters(consentDebugSettings: debugSettings);
   
   ConsentInformation.instance.requestConsentInfoUpdate(params, () async {
     // ...
   };
   

Force a geography

The UMP SDK provides a way to test your app's behavior as though the device was located in the EEA or UK using the DebugGeography field on ConsentDebugSettings. Note that debug settings only work on test devices.

ConsentDebugSettings debugSettings = ConsentDebugSettings(
  debugGeography: DebugGeography.debugGeographyEea,
  testIdentifiers: ["TEST-DEVICE-HASHED-ID"],
);

ConsentRequestParameters params =
    ConsentRequestParameters(consentDebugSettings: debugSettings);

ConsentInformation.instance.requestConsentInfoUpdate(params, () async {
  // ...
};

Reset consent state

In testing your app with the UMP SDK, you might find it helpful to reset the state of the SDK so that you can simulate a user's first install experience. The SDK provides the reset() method to do this.

ConsentInformation.instance.reset();

Caution: This method is intended to be used for testing purposes only. You shouldn't call reset() in production code.

Examples on GitHub