瞭解詳情

Google User Messaging Platform (UMP) SDK 是一項隱私權與訊息傳遞工具，可協助您管理隱私權選擇。詳情請參閱「關於隱私權與訊息」一文。

建立訊息類型

請在 AdMob 帳戶的「隱私權與訊息」分頁中，使用其中一種可用的使用者訊息類型建立使用者訊息。UMP SDK 會嘗試顯示透過專案中設定的 AdMob 應用程式 ID 建立的隱私權訊息。

詳情請參閱「隱私權與訊息簡介」一文。

匯入 SDK

CocoaPods (建議)

如要將 SDK 匯入 iOS 專案，最簡單的方法是使用 CocoaPods。開啟專案的 Podfile，然後將這行程式碼新增至應用程式的目標：

pod 'GoogleUserMessagingPlatform'

然後執行下列指令：

pod install --repo-update

如果您是 CocoaPods 新手，請參閱「使用 CocoaPods」一文，進一步瞭解如何建立及使用 Podfile。

Swift 套件管理工具

UMP SDK 也支援 Swift 套件管理工具。請按照下列步驟匯入 Swift 套件。

  1. 在 Xcode 中依序前往「File」>「Add Packages...」，安裝 UMP SDK Swift 套件。

  2. 在隨即顯示的提示中，搜尋 UMP SDK Swift Package GitHub 存放區：

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

  3. 選取要使用的 UMP SDK Swift 套件版本。對於新專案，建議您使用升級至下一個主要版本。

Xcode 會解析套件依附元件，並在背景下載這些依附元件。如要進一步瞭解如何新增套件依附元件，請參閱 Apple 的文章。

手動下載

您也可以手動匯入 SDK。

下載 SDK

接著，將架構拖曳至 Xcode 專案，並確保選取「Copy items if needed」。

接著，您可以使用以下方式，在所需的任何檔案中加入架構：

Swift

import UserMessagingPlatform

Objective-C

#include <UserMessagingPlatform/UserMessagingPlatform.h>

新增應用程式 ID

您可以在 AdMob 使用者介面中找到應用程式 ID。使用下列程式碼片段，將 ID 新增至 Info.plist：

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

如要收集同意聲明，請完成下列步驟：

  1. 要求取得最新的使用者同意聲明資訊。
  2. 視需要載入及呈現同意聲明表單。

您應在每次應用程式啟動時，使用 requestConsentInfoUpdate(with:completionHandler:) 要求更新使用者的同意聲明資訊。這項要求會檢查下列項目：

  • 是否必須取得同意聲明。例如使用者首次需要取得同意聲明，或先前的同意聲明決定已過期。
  • 是否需要隱私權選項進入點。有些隱私權訊息會要求應用程式讓使用者隨時修改隱私權選項。

視需要載入並顯示隱私權訊息表單

收到最新的同意聲明狀態後，請呼叫 loadAndPresentIfRequired(from:) 來載入收集使用者同意聲明所需的任何表單。載入後，表單會立即顯示。

下列程式碼示範如何要求使用者最新的同意聲明資訊。如有需要，程式碼會載入並顯示隱私權訊息表單：

Swift


// Requesting an update to consent information should be called on every app launch.
UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: parameters) {
  requestConsentError in
  guard requestConsentError == nil else {
    return consentGatheringComplete(requestConsentError)
  }

  Task { @MainActor in
    do {
      try await UMPConsentForm.loadAndPresentIfRequired(from: viewController)
      // Consent has been gathered.
      consentGatheringComplete(nil)
    } catch {
      consentGatheringComplete(error)
    }
  }
}
GoogleMobileAdsConsentManager.swift

Objective-C


// Requesting an update to consent information should be called on every app launch.
[UMPConsentInformation.sharedInstance
    requestConsentInfoUpdateWithParameters:parameters
                         completionHandler:^(NSError *_Nullable requestConsentError) {
                           if (requestConsentError) {
                             consentGatheringComplete(requestConsentError);
                           } else {
                             [UMPConsentForm
                                 loadAndPresentIfRequiredFromViewController:viewController
                                                          completionHandler:^(
                                                              NSError
                                                                  *_Nullable loadAndPresentError) {
                                                            // Consent has been gathered.
                                                            consentGatheringComplete(
                                                                loadAndPresentError);
                                                          }];
                           }
                         }];
GoogleMobileAdsConsentManager.m

隱私權選項

部分隱私權訊息表單是透過發布者算繪的隱私權選項進入點提供，可讓使用者隨時管理隱私權選項。如要進一步瞭解使用者會在隱私權選項進入點看到的訊息，請參閱「可用的使用者訊息類型」。

檢查是否需要設定隱私權選項進入點

呼叫 requestConsentInfoUpdate(with:completionHandler:) 後，請查看 UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus，判斷應用程式是否需要隱私權選項進入點：

Swift


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

Objective-C


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

在應用程式中新增可見元素

如果需要隱私權進入點，請在用於顯示隱私權選項表單的應用程式中加入可見的可互動 UI 元素。如果不需要隱私權進入點，請將 UI 元素設為不可見且無法互動。

Swift


self.privacySettingsButton.isEnabled =
  GoogleMobileAdsConsentManager.shared.isPrivacyOptionsRequired
ViewController.swift

Objective-C


strongSelf.privacySettingsButton.enabled =
    GoogleMobileAdsConsentManager.sharedInstance
        .isPrivacyOptionsRequired;
ViewController.m

顯示隱私權選項表單

當使用者與元素互動時，請顯示隱私權選項表單：

Swift


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

Objective-C


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

請求廣告

在應用程式中請求廣告前，請確認您已使用 UMPConsentInformation.sharedInstance.canRequestAds 取得使用者的同意聲明。收集同意聲明時，需要確認兩個地方：

  • 在目前的工作階段中收集到同意聲明後。
  • 呼叫 requestConsentInfoUpdate(with:completionHandler:) 後立即生效。您可能已在上一個工作階段取得同意聲明。建議您最好不要等待回呼完成，以便在應用程式啟動後盡快載入廣告。

如果在收集同意聲明的過程中發生錯誤，您仍應檢查是否能要求廣告。UMP SDK 會使用上一個工作階段的同意聲明狀態。

以下程式碼會檢查您是否可以在同意聲明收集程序中要求廣告：

Swift


GoogleMobileAdsConsentManager.shared.gatherConsent(from: self) { [weak self] consentError in
  guard let self else { return }

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

  if GoogleMobileAdsConsentManager.shared.canRequestAds {
    self.startGoogleMobileAdsSDK()
  }
  // ...
}

// This sample attempts to load ads using consent obtained in the previous session.
if GoogleMobileAdsConsentManager.shared.canRequestAds {
  startGoogleMobileAdsSDK()
}
ViewController.swift

Objective-C


[GoogleMobileAdsConsentManager.sharedInstance
    gatherConsentFromConsentPresentationViewController:self
                              consentGatheringComplete:^(NSError *_Nullable consentError) {
                                if (consentError) {
                                  // Consent gathering failed.
                                  NSLog(@"Error: %@", consentError.localizedDescription);
                                }

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

                                if (GoogleMobileAdsConsentManager.sharedInstance.canRequestAds) {
                                  [strongSelf startGoogleMobileAdsSDK];
                                }
                                // ...
                              }];

// This sample attempts to load ads using consent obtained in the previous session.
if (GoogleMobileAdsConsentManager.sharedInstance.canRequestAds) {
  [self startGoogleMobileAdsSDK];
}
ViewController.m

以下程式碼會在收集使用者同意聲明後，設定 Google Mobile Ads SDK：

Swift


private func startGoogleMobileAdsSDK() {
  DispatchQueue.main.async {
    guard !self.isMobileAdsStartCalled else { return }

    self.isMobileAdsStartCalled = true

    // Initialize the Google Mobile Ads SDK.
    GADMobileAds.sharedInstance().start()

    if self.isViewDidAppearCalled {
      self.loadBannerAd()
    }
  }
}
ViewController.swift

Objective-C


- (void)startGoogleMobileAdsSDK {
  static dispatch_once_t onceToken;
  dispatch_once(&onceToken, ^{
    // Initialize the Google Mobile Ads SDK.
    [GADMobileAds.sharedInstance startWithCompletionHandler:nil];
    [self loadBannerAd];
  });
}
ViewController.m

測試

如要在開發過程中測試應用程式的整合作業，請按照下列步驟，以程式輔助方式註冊測試裝置。請務必在發布應用程式前，移除設定這些測試裝置 ID 的程式碼。

  1. 歡迎致電 requestConsentInfoUpdate(with:completionHandler:)。

  2. 檢查記錄輸出內容，找出類似下列範例的訊息，其中會顯示裝置 ID 和如何將其新增為測試裝置：

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

  3. 將測試裝置 ID 複製到剪貼簿。

  4. 修改程式碼以呼叫 UMPDebugSettings().testDeviceIdentifiers，並傳入測試裝置 ID 清單。

    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){
                          // ...
}];

強制指定地理區域

UMP SDK 可讓您使用 geography，測試應用程式行為，就像裝置位於不同區域 (例如歐洲經濟區或英國) 一樣。請注意，偵錯設定只適用於測試裝置。

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){
                           // ...
}];

使用 UMP SDK 測試應用程式時，建議您重設 SDK 狀態，以模擬使用者初次安裝的體驗。SDK 提供 reset 方法來執行這項操作。

Swift

UMPConsentInformation.sharedInstance.reset()

Objective-C

[UMPConsentInformation.sharedInstance reset];

GitHub 上的範例

如需本頁提及的 UMP SDK 整合完整範例，請參閱本頁的 Swift BannerExample 和 Objective-C BannerExample。