Get started

AI-generated Key Takeaways

outlined_flag

• The Google User Messaging Platform (UMP) SDK is a tool for managing user privacy choices in your app.

• You need to create user messages within your AdMob account under the Privacy & messaging tab.

• Import the UMP SDK into your iOS project using CocoaPods, Swift Package Manager, or manual download.

• Add your AdMob application ID to your Info.plist file.

• Request an update of the user's consent information at every app launch.

• After getting the latest consent status, load and present any required privacy message forms using loadAndPresentIfRequired(from:) .

• Check UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus to see if a privacy options entry point is required, and if so, add a UI element to present the form.

• Before requesting ads, always check UMPConsentInformation.sharedInstance.canRequestAds to confirm that you have obtained user consent.

• For testing purposes, you can register test devices, force a geography, and reset the consent state.

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 & messagingtab 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 .

Import the SDK

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.

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

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

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

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:

  import 
  
 UserMessagingPlatform 
 

  #include <UserMessagingPlatform/UserMessagingPlatform.h> 
 

Add the application ID

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

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

Get the user's consent information

You should request an update of the user's consent information at every app launch, using requestConsentInfoUpdate(with: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.

  // Requesting an update to consent information should be called on every app launch. 
 ConsentInformation 
 . 
 shared 
 . 
 requestConsentInfoUpdate 
 ( 
 with 
 : 
  
 parameters 
 ) 
  
 { 
  
 requestConsentError 
  
 in 
  
 // ... 
 } 
 
  GoogleMobileAdsConsentManager 
 . 
 swift 
 
 
 

  // Requesting an update to consent information should be called on every app launch. 
 ConsentInformation 
 . 
 shared 
 . 
 requestConsentInfoUpdate 
 ( 
 with 
 : 
  
 parameters 
 ) 
  
 { 
  
 requestConsentError 
  
 in 
  
 // ... 
 } 
 
  GoogleMobileAdsConsentManager 
 . 
 swift 
 
 
 

  // Requesting an update to consent information should be called on every app launch. 
 [ 
 UMPConsentInformation 
 . 
 sharedInstance 
  
 requestConsentInfoUpdateWithParameters 
 : 
 parameters 
  
 completionHandler 
 : 
 ^ 
 ( 
 NSError 
  
 * 
 _Nullable 
  
 requestConsentError 
 ) 
  
 { 
  
 // ... 
  
 }]; 
 
  GoogleMobileAdsConsentManager 
 . 
 m 
 
 
 

Load and present the privacy message form

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

  try 
  
 await 
  
 ConsentForm 
 . 
 loadAndPresentIfRequired 
 ( 
 from 
 : 
  
 viewController 
 ) 
 
  GoogleMobileAdsConsentManager 
 . 
 swift 
 
 
 

  try 
  
 await 
  
 ConsentForm 
 . 
 loadAndPresentIfRequired 
 ( 
 from 
 : 
  
 nil 
 ) 
 
  GoogleMobileAdsConsentManager 
 . 
 swift 
 
 
 

  [ 
 UMPConsentForm 
  
 loadAndPresentIfRequiredFromViewController 
 : 
 viewController 
  
 completionHandler 
 : 
 ^ 
 ( 
 NSError 
  
 * 
 _Nullable 
  
 loadAndPresentError 
 ) 
  
 { 
  
 // Consent gathering process is complete. 
  
 }]; 
 
  GoogleMobileAdsConsentManager 
 . 
 m 
 
 
 

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 .

Check if a privacy options entry point is required

After you have called requestConsentInfoUpdate(with:completionHandler:) , check UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus to determine if a privacy options entry point is required for your app. If an entry point is required, add a visible and interactable UI element to your app that presents the privacy options form. If a privacy entry point is not required, configure your UI element to be not visible and interactable.

  var 
  
 isPrivacyOptionsRequired 
 : 
  
 Bool 
  
 { 
  
 return 
  
 ConsentInformation 
 . 
 shared 
 . 
 privacyOptionsRequirementStatus 
  
 == 
  
 . 
 required 
 } 
 
  GoogleMobileAdsConsentManager 
 . 
 swift 
 
 
 

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

For the full list of privacy options requirement statuses, see UMPPrivacyOptionsRequirementStatus .

Present the privacy options form

When the user interacts with your element, present the privacy options form:

  try 
  
 await 
  
 ConsentForm 
 . 
 presentPrivacyOptionsForm 
 ( 
 from 
 : 
  
 viewController 
 ) 
 
  GoogleMobileAdsConsentManager 
 . 
 swift 
 
 
 

  try 
  
 await 
  
 ConsentForm 
 . 
 presentPrivacyOptionsForm 
 ( 
 from 
 : 
  
 nil 
 ) 
 
  GoogleMobileAdsConsentManager 
 . 
 swift 
 
 
 

  [ 
 UMPConsentForm 
  
 presentPrivacyOptionsFormFromViewController 
 : 
 viewController 
  
 completionHandler 
 : 
 completionHandler 
 ]; 
 
  GoogleMobileAdsConsentManager 
 . 
 m 
 
 
 

Request ads with user consent

Before requesting ads, use UMPConsentInformation.sharedInstance.canRequestAds to check if you've obtained consent from the user:

  ConsentInformation 
 . 
 shared 
 . 
 canRequestAds 
 

  UMPConsentInformation 
 . 
 sharedInstance 
 . 
 canRequestAds 
 ; 
 

Listed are the following places to check if you can request ads while gathering consent:

• After the UMP SDK gathers consent in the current session.
• Immediately after you have called requestConsentInfoUpdate(with:completionHandler:) . The UMP SDK might have obtained consent in the previous app session.

If an error occurs during the consent gathering process, check if you can request ads. The UMP SDK uses the consent status from the previous app session.

Prevent redundant ad request work

As you check UMPConsentInformation.sharedInstance.canRequestAds after gathering consent and after calling requestConsentInfoUpdate(with:completionHandler:) , ensure your logic prevents redundant ad requests that might result in both checks returning true . For example, with a boolean variable.

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(with:completionHandler:) .

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:

    <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 UMPDebugSettings().testDeviceIdentifiers and pass in a list of your test device IDs.

   Swift

     let 
     
    parameters 
     
    = 
     
    RequestParameters 
    () 
    let 
     
    debugSettings 
     
    = 
     
    DebugSettings 
    () 
    debugSettings 
    . 
    testDeviceIdentifiers 
     
    = 
     
    [ 
    "TEST-DEVICE-HASHED-ID" 
    ] 
    parameters 
    . 
    debugSettings 
     
    = 
     
    debugSettings 
    // Include the UMPRequestParameters in your consent request. 
    ConsentInformation 
    . 
    shared 
    . 
    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 were located in various regions, such as the EEA or UK, using geography . Note that debug settings only work on test devices.

  let 
  
 parameters 
  
 = 
  
 RequestParameters 
 () 
 let 
  
 debugSettings 
  
 = 
  
 DebugSettings 
 () 
 debugSettings 
 . 
 testDeviceIdentifiers 
  
 = 
  
 [ 
 "TEST-DEVICE-HASHED-ID" 
 ] 
  debugSettings 
 . 
 geography 
  
 = 
  
 . 
 EEA 
 parameters 
 . 
 debugSettings 
  
 = 
  
 debugSettings 
 // Include the UMPRequestParameters in your consent request. 
 ConsentInformation 
 . 
 shared 
 . 
 requestConsentInfoUpdate 
 ( 
  
 with 
 : 
  
 parameters 
 , 
  
 completionHandler 
 : 
  
 { 
  
 error 
  
 in 
  
 // ... 
  
 }) 
 

  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

When 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 
 . 
 shared 
 . 
 reset 
 () 
 

  [ 
 UMPConsentInformation 
 . 
 sharedInstance 
  
 reset 
 ]; 
 

Examples on GitHub

See a full example of the UMP SDK integration covered in this page in

• Swift BannerExample
• SwiftUIDemo
• Objective-C BannerExample