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. You can see a working IMA implementation with the UMP SDK in either the Objective-C or Swift UMP sample apps.

Create a message type

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

For more details, see About privacy and messaging.

Import the SDK

The UMP SDK is not included as a dependency of the IMA SDK, so you must explicitly add it yourself.

CocoaPods (preferred)

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 'GoogleUserMessagingPlatform'

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.

Swift Package Manager

The UMP SDK also supports the Swift Package Manager. Follow these steps to import the Swift package.

In Xcode, install the UMP SDK Swift Package by navigating to File > Add Packages....

In the prompt that appears, search for the UMP SDK Swift Package GitHub repository:

https://github.com/googleads/swift-package-manager-google-user-messaging-platform.git

Select the version of the UMP SDK Swift Package you want to use. For new projects, we recommend using the Up to Next Major Version.

Xcode then resolves your package dependencies and downloads them in the background. For more details on how to add package dependencies, see Apple's article.

Add the application ID

You can find your application ID in the Ad Manager UI. Add the ID to your Info.plist with the following code snippet:

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

You should request an update of the user's consent information at every app launch, using requestConsentInfoUpdateWithParameters:completionHandler:. 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 from a UIViewController in the viewDidLoad() method.

Swift

override func viewDidLoad() {
  super.viewDidLoad()

  // Request an update for the consent information.
  UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: nil) {
    [weak self] requestConsentError in
    guard let self else { return }

    if let consentError = requestConsentError {
      // Consent gathering failed.
      return print("Error: \(consentError.localizedDescription)")
    }

    // TODO: Load and present the privacy message form.
  }
}

Objective-C

- (void)viewDidLoad {
  [super viewDidLoad];

  // Request an update for the consent information.
  [UMPConsentInformation.sharedInstance
      requestConsentInfoUpdateWithParameters:nil
          completionHandler:^(NSError *_Nullable requestConsentError) {
            if (requestConsentError) {
              // Consent gathering failed.
              NSLog(@"Error: %@", requestConsentError.localizedDescription);
              return;
            }

            // TODO: Load and present the privacy message form.
          }];
}

Load and present a privacy message form if required

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

Swift

override func viewDidLoad() {
  super.viewDidLoad()

  // Request an update for the consent information.
  UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: nil) {
    [weak self] requestConsentError in
    guard let self else { return }

    if let consentError = requestConsentError {
      // Consent gathering failed.
      return print("Error: \(consentError.localizedDescription)")
    }

    UMPConsentForm.loadAndPresentIfRequired(from: self) {
      [weak self] loadAndPresentError in
      guard let self else { return }

      if let consentError = loadAndPresentError {
        // Consent gathering failed.
        return print("Error: \(consentError.localizedDescription)")
      }

      // Consent has been gathered.
    }
  }
}

Objective-C

- (void)viewDidLoad {
  [super viewDidLoad];

  __weak __typeof__(self) weakSelf = self;
  // Request an update for the consent information.
  [UMPConsentInformation.sharedInstance
      requestConsentInfoUpdateWithParameters:nil
          completionHandler:^(NSError *_Nullable requestConsentError) {
            if (requestConsentError) {
              // Consent gathering failed.
              NSLog(@"Error: %@", requestConsentError.localizedDescription);
              return;
            }

            __strong __typeof__(self) strongSelf = weakSelf;
            if (!strongSelf) {
              return;
            }

            [UMPConsentForm loadAndPresentIfRequiredFromViewController:strongSelf
                completionHandler:^(NSError *loadAndPresentError) {
                  if (loadAndPresentError) {
                    // Consent gathering failed.
                    NSLog(@"Error: %@", loadAndPresentError.localizedDescription);
                    return;
                  }

                  // Consent has been gathered.
                }];
          }];
}

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 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:

Check UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus.
If a privacy options entry point is required, add a visible and interactable UI element to your app.
Trigger the privacy options form using presentPrivacyOptionsFormFromViewController:completionHandler:.

The following code example demonstrates these steps:

Swift

@IBOutlet weak var privacySettingsButton: UIBarButtonItem!

var isPrivacyOptionsRequired: Bool {
  return UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus == .required
}

override func viewDidLoad() {
  // ...

  // Request an update for the consent information.
  UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: parameters) {
    // ...

    UMPConsentForm.loadAndPresentIfRequired(from: self) {
      //...

      // Consent has been gathered.

      // Show the button if privacy options are required.
      self.privacySettingsButton.isEnabled = isPrivacyOptionsRequired
    }
  }
  // ...
}

// Present the privacy options form when a user interacts with the
// privacy settings button.
@IBAction func privacySettingsTapped(_ sender: UIBarButtonItem) {
  UMPConsentForm.presentPrivacyOptionsForm(from: self) {
    [weak self] formError in
    guard let self, let formError else { return }

    // Handle the error.
  }
}

Objective-C

@interface ViewController ()
@property(weak, nonatomic) IBOutlet UIBarButtonItem *privacySettingsButton;
@end

- (BOOL)isPrivacyOptionsRequired {
  return UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus ==
         UMPPrivacyOptionsRequirementStatusRequired;
}

- (void)viewDidLoad {
  // ...

  __weak __typeof__(self) weakSelf = self;
  // Request an update for the consent information.
  [UMPConsentInformation.sharedInstance
      requestConsentInfoUpdateWithParameters:parameters
          completionHandler:^(NSError *_Nullable requestConsentError) {
            // ...

            [UMPConsentForm loadAndPresentIfRequiredFromViewController:strongSelf
                completionHandler:^(NSError *loadAndPresentError) {
                  // ...

                  // Consent has been gathered.

                  // Show the button if privacy options are required.
                  strongSelf.privacySettingsButton.enabled = isPrivacyOptionsRequired;
                }];
          }];
}

// Present the privacy options form when a user interacts with your
// privacy settings button.
- (IBAction)privacySettingsTapped:(UIBarButtonItem *)sender {
  [UMPConsentForm presentPrivacyOptionsFormFromViewController:self
                                completionHandler:^(NSError *_Nullable formError) {
                                  if (formError) {
                                    // Handle the error.
                                  }
                                }];
}

Request ads

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

After consent has been gathered in the current session.
Immediately after you have called requestConsentInfoUpdateWithParameters:completionHandler:. 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.

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.

Swift

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    // Request an update for the consent information.
    UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: nil) {
      [weak self] requestConsentError in
      guard let self else { return }

      if let consentError = requestConsentError {
        // Consent gathering failed.
        return print("Error: \(consentError.localizedDescription)")
      }

      UMPConsentForm.loadAndPresentIfRequired(from: self) {
        [weak self] loadAndPresentError in
        guard let self else { return }

        if let consentError = loadAndPresentError {
          // Consent gathering failed.
          return print("Error: \(consentError.localizedDescription)")
        }

        // Consent has been gathered.
        if UMPConsentInformation.sharedInstance.canRequestAds {
          self.startImaSdk()
        }
      }
    }
    
    // Check if you can initialize the IMA SDK in parallel
    // while checking for new consent information. Consent obtained in
    // the previous session can be used to request ads.
    if UMPConsentInformation.sharedInstance.canRequestAds {
      startImaSdk()
    }
  }
  
  private func startImaSdk() {
    // Create an IMAAdsLoader instance.
    adsLoader = IMAAdsLoader(settings: nil)

    // TODO: Create an IMAAdDisplayContainer and IMAAdsRequest, then make
    // a request for ads.
  }
}

Objective-C

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  __weak __typeof__(self) weakSelf = self;
  // Request an update for the consent information.
  [UMPConsentInformation.sharedInstance
      requestConsentInfoUpdateWithParameters:nil
          completionHandler:^(NSError *_Nullable requestConsentError) {
            if (requestConsentError) {
              // Consent gathering failed.
              NSLog(@"Error: %@", requestConsentError.localizedDescription);
              return;
            }
            __strong __typeof__(self) strongSelf = weakSelf;
            if (!strongSelf) {
              return;
            }

            [UMPConsentForm loadAndPresentIfRequiredFromViewController:strongSelf
                completionHandler:^(NSError *loadAndPresentError) {
                  if (loadAndPresentError) {
                    // Consent gathering failed.
                    NSLog(@"Error: %@", loadAndPresentError.localizedDescription);
                    return;
                  }

                  // Consent has been gathered.
                  __strong __typeof__(self) strongSelf = weakSelf;
                  if (!strongSelf) {
                    return;
                  }

                  if (UMPConsentInformation.sharedInstance.canRequestAds) {
                    [strongSelf startImaSdk];
                  }
                }];
          }];

  // Check if you can initialize the Google IMA SDK in parallel
  // while checking for new consent information. Consent obtained in
  // the previous session can be used to request ads.
  if (UMPConsentInformation.sharedInstance.canRequestAds) {
    [self startImaSdk];
  }
}

- (void)startImaSdk {
  static dispatch_once_t onceToken;
  dispatch_once(&onceToken, ^{
    // Create an IMAAdsLoader instance.
    self.adsLoader = [[IMAAdsLoader alloc] init];

    // TODO: Create an IMAAdDisplayContainer and IMAAdsRequest, then make
    // a request for ads.
  });
}

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.

Call requestConsentInfoUpdateWithParameters:completionHandler:.
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:
```
<UMP SDK>To enable debug mode for this device, set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]
```
Copy your test device ID to your clipboard.

Modify your code to call UMPDebugSettings().testDeviceIdentifiers and pass in a list of your test device IDs.

Swift

let parameters = UMPRequestParameters()
let debugSettings = UMPDebugSettings()
debugSettings.testDeviceIdentifiers = ["TEST-DEVICE-HASHED-ID"]
parameters.debugSettings = debugSettings
// Include the UMPRequestParameters in your consent request.
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" ];
parameters.debugSettings = debugSettings;
// Include the UMPRequestParameters in your consent request.
[UMPConsentInformation.sharedInstance
    requestConsentInfoUpdateWithParameters:parameters
                        completionHandler:^(NSError *_Nullable error){
                          ...
}];

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 UMPDebugGeography. Note that debug settings only work on test devices.

Swift

let parameters = UMPRequestParameters()
let debugSettings = UMPDebugSettings()
debugSettings.testDeviceIdentifiers = ["TEST-DEVICE-HASHED-ID"]
debugSettings.geography = .EEA
parameters.debugSettings = debugSettings
// Include the UMPRequestParameters in your consent request.
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;
// Include the UMPRequestParameters in your consent request.
[UMPConsentInformation.sharedInstance
    requestConsentInfoUpdateWithParameters:parameters
                         completionHandler:^(NSError *_Nullable error){
                           ...
}];

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];

EU consent and GDPR

Get started

Create a message type

Import the SDK

CocoaPods (preferred)

Swift Package Manager

Add the application ID

Request for consent information

Swift

Objective-C

Load and present a privacy message form if required

Swift

Objective-C

Privacy options

Swift

Objective-C

Request ads

Swift

Objective-C

Testing

Swift

Objective-C

Force a geography

Swift

Objective-C

Reset consent state

Swift

Objective-C