Get started

Stay organized with collections Save and categorize content based on your preferences.

Under the Google EU User Consent Policy, you must make certain disclosures to your users in the European Economic Area (EEA) along with the UK and obtain their consent to use cookies or other local storage, where legally required, and to use personal data (such as AdID) to serve ads. This policy reflects the requirements of the EU ePrivacy Directive and the General Data Protection Regulation (GDPR).

To support publishers in meeting their duties under this policy, Google offers the User Messaging Platform (UMP) SDK. The UMP SDK has been updated to support the latest IAB standards. All of these configurations can now conveniently be handled in Ad Manager privacy & messaging.

Prerequisites

User message types

See User message types for a full list of supported messages. For specific instructions on implementing each message type, see the left navigation bar.

Import the SDK

CocoaPods (preferred)

The UMP SDK is included as a dependency of the Google Mobile Ads SDK Pod starting with Google Mobile Ads SDK 7.64.0.

The easiest way to import the SDK into an iOS project is to use CocoaPods. Open your project's Podfile and add this line to your app's target:

pod 'Google-Mobile-Ads-SDK'

Then, run the following command:

pod install --repo-update

If you're new to CocoaPods, see Using CocoaPods for details on how to create and use Podfiles.

Manual download

The other way of importing the SDK is doing it manually.

Download the SDK

Then, drag the framework into your Xcode project, ensuring you select Copy items if needed.

You can then include the framework in any file you need using:

Swift

import UserMessagingPlatform

Objective-C

#include <UserMessagingPlatform/UserMessagingPlatform.h>

Update your Info.plist

Obtain your app ID from the Mobile apps section of Ad Manager:

and add it to your Info.plist:

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy</string>

Determine if a message needs to be displayed

You should request an update of the user's consent information at every app launch, using requestConsentInfoUpdateWithParameters:completionHandler: before loading a form. This can determine whether or not your user needs to provide consent if they hadn't done so already or if their consent has expired.

If needed, you can present the form later on.

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

Swift

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
   // Create a UMPRequestParameters object.
   let parameters = UMPRequestParameters()
   // Set tag for under age of consent. Here false means users are not under age.
   parameters.tagForUnderAgeOfConsent = false

   // Request an update to the consent information.
   UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(
      with: parameters,
      completionHandler: { error in
        if error != nil {
           // Handle the error.
        } else {
           // The consent information state was updated.
           // You are now ready to check if a form is
           // available.
        }
       })
}

Objective-C

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

// Create a UMPRequestParameters object.
UMPRequestParameters *parameters = [[UMPRequestParameters alloc] init];
// Set tag for under age of consent. Here NO means users are not under age.
parameters.tagForUnderAgeOfConsent = NO;

// Request an update to the consent information.
[UMPConsentInformation.sharedInstance
    requestConsentInfoUpdateWithParameters:parameters
                         completionHandler:^(NSError *_Nullable error) {
                           if (error) {
                             // Handle the error.
                           } else {
                             // The consent information state was updated.
                             // You are now ready to check if a form is
                             // available.
                           }
                         }];
}

Load a form if available

Before displaying a form, you first need to determine if one is available. Unavailable forms can be due to the user enabling limited ad tracking or if you’ve tagged them as under the age of consent.

To check the availability of a form, use the formStatus property on the UMPConsentInformation instance you created earlier.

Then, add a wrapper method to load the form:

Swift

// Request an update to the consent information.
UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(
    withParameters: parameters,
    completionHandler: { [self] error in

      // The consent information has updated.
      if error != nil {
        // Handle the error.
      } else {
        // The consent information state was updated.
        // You are now ready to see if a form is available.
        let formStatus = UMPConsentInformation.sharedInstance.formStatus
        if formStatus == UMPFormStatus.available {
          loadForm()
        }
      }
    })
...
func loadForm() {

}

Objective-C

// Request an update to the consent information.
[UMPConsentInformation.sharedInstance
    requestConsentInfoUpdateWithParameters:parameters
                         completionHandler:^(NSError* _Nullable error) {

                           // The consent information has updated.
                           if (error) {
                             // Handle the error.
                           } else {
                             // The consent information state was updated.
                             // You are now ready to see if a form is available.
                             UMPFormStatus formStatus =
                                 UMPConsentInformation.sharedInstance
                                     .formStatus;
                             if (formStatus == UMPFormStatusAvailable) {
                               [self loadForm];
                             }
                           }
                         }];
...
- (void) loadForm {

}

To load the form, use the static loadWithCompletionHandler: method on the UMPConsentForm class.

Swift

func loadForm() {
  // Loads a consent form. Must be called on the main thread.
  UMPConsentForm.load(
      withCompletionHandler: { form, loadError in
        if loadError != nil {
          // Handle the error
        } else {
          // Present the form
        }
      })
}

Objective-C

- (void)loadForm {
  [UMPConsentForm
      loadWithCompletionHandler:^(UMPConsentForm *form, NSError *loadError) {
        if (loadError) {
          // Handle the error
        } else {
          // Present the form
        }
      }];
}

Present the form if required

After you’ve determined the form's availability and loaded it, use the presentFromViewController:completionHandler: method on the UMPConsentForm instance to present the form.

Use the UMPConsentInformation object from earlier to check the consent status and update your loadForm method:

Swift

func loadForm() {
  UMPConsentForm.load(withCompletionHandler: { form, loadError in
    if loadError != nil {
      // Handle the error.
    } else {
      // Present the form. You can also hold on to the reference to present
      // later.
      if UMPConsentInformation.sharedInstance.consentStatus == UMPConsentStatus.required {
        form?.present(
            from: self,
            completionHandler: { dismissError in
              if UMPConsentInformation.sharedInstance.consentStatus == UMPConsentStatus.obtained {
                // App can start requesting ads.
              }
                // Handle dismissal by reloading form.
                loadForm();
            })
      } else {
        // Keep the form available for changes to user consent.
      }
    }
  })
}

Objective-C

- (void)loadForm {
  [UMPConsentForm loadWithCompletionHandler:^(UMPConsentForm *form,
                                              NSError *loadError) {
    if (loadError) {
      // Handle the error.
    } else {
      // Present the form. You can also hold on to the reference to present
      // later.
      if (UMPConsentInformation.sharedInstance.consentStatus ==
          UMPConsentStatusRequired) {
        [form
            presentFromViewController:self
                    completionHandler:^(NSError *_Nullable dismissError) {
                      if (UMPConsentInformation.sharedInstance.consentStatus ==
                          UMPConsentStatusObtained) {
                        // App can start requesting ads.
                      }
                        // Handle dismissal by reloading form.
                        [self loadForm];
                    }];
      } else {
        // Keep the form available for changes to user consent.
      }
    }
  }];
}

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

Testing

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 property of type UMPDebugGeography on UMPDebugSettings.

You must provide your test device's hashed ID in your app's debug settings to use the debug functionality. If you call requestConsentInfoUpdateWithParameters:completionHandler: without setting this value, your app logs the required ID hash when run.

Swift

let parameters = UMPRequestParameters()
let debugSettings = UMPDebugSettings()
debugSettings.testDeviceIdentifiers = ["TEST-DEVICE-HASHED-ID"]
debugSettings.geography = UMPDebugGeography.EEA
parameters.debugSettings = debugSettings
UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(
    with: parameters,
    completionHandler: { error in
      ...
    })

Objective-C

UMPRequestParameters *parameters = [[UMPRequestParameters alloc] init];
UMPDebugSettings *debugSettings = [[UMPDebugSettings alloc] init];
debugSettings.testDeviceIdentifiers = @[ @"TEST-DEVICE-HASHED-ID" ];
debugSettings.geography = UMPDebugGeographyEEA;
parameters.debugSettings = debugSettings;
[UMPConsentInformation.sharedInstance
    requestConsentInfoUpdateWithParameters:parameters
                         completionHandler:^(NSError *_Nullable error){
                           ...
}];

With the UMPDebugGeography, you have the option to force the geography to one of these options:

DebugGeography Description
UMPDebugGeographyDisabled Debug geography disabled.
UMPDebugGeographyEEA Geography appears as in EEA for debug devices.
UMPDebugGeographyNotEEA Geography appears as not in the EEA for debug devices.

Note that debug settings only work on test devices. Emulators don't need to be added to your device ID list as they already have testing enabled by default.

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.

Swift

UMPConsentInformation.sharedInstance.reset()

Objective-C

[UMPConsentInformation.sharedInstance reset];

You should also call reset if you decide to remove the UMP SDK completely from your project.