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 AdMob privacy & messaging.
Prerequisites
- Complete the Get Started guide.
- Configure your messages under the Privacy & messaging tab of your AdMob account. For more details, see About privacy and messaging,
- If you’re working on GDPR-related requirements, read How IAB requirements affect EU consent messages.
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.
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
Find your app ID and add it to yourInfo.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.
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.
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.
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.