Как настроить UMP SDK

Google User Messaging Platform (UMP) SDK – это инструмент для управления настройками конфиденциальности и сообщениями. Дополнительную информацию вы найдете в статье О странице "Конфиденциальность и сообщения".

Как создать тип сообщения

Создайте сообщения для пользователей, выбрав один из доступных типов на вкладке Конфиденциальность и сообщения в аккаунте AdMob. UMP SDK пытается показать сообщение о конфиденциальности, созданное на основе идентификатора приложения AdMob, заданного в вашем проекте.

Импортируйте SDK

CocoaPods (рекомендуется)

Проще всего импортировать SDK в проект iOS с помощью CocoaPods. Откройте файл Podfile проекта и добавьте в цель приложения следующую строку:

pod 'GoogleUserMessagingPlatform'

Затем выполните следующую команду:

pod install --repo-update

Если вы не знакомы с CocoaPods, прочитайте статью Использование CocoaPods, чтобы узнать, как создавать и использовать файлы Podfile.

Swift Package Manager

UMP SDK также поддерживает Swift Package Manager. Чтобы импортировать пакет Swift, выполните следующие действия:

1. В Xcode установите пакет UMP SDK Swift, выбрав File (Файл) > Add Packages (Добавить пакеты).

2. В появившемся окне найдите хранилище пакета Swift для UMP SDK на GitHub:

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

3. Выберите версию пакета Swift для UMP SDK, которую вы хотите использовать. Для новых проектов рекомендуется использовать Up to Next Major Version.

После этого Xcode распознает зависимости пакета и скачает их в фоновом режиме. Подробнее о том, как добавлять зависимости пакетов, читайте в статье Apple.

Скачивание вручную

Другой способ импорта SDK – вручную.

Скачать SDK

Затем перетащите фреймворк в проект Xcode, выбрав Copy items if needed (Копировать элементы, если необходимо).

Затем вы можете включить фреймворк в любой нужный файл, используя следующий код:

import UserMessagingPlatform

#include <UserMessagingPlatform/UserMessagingPlatform.h>

Добавьте идентификатор приложения

Идентификатор приложения можно найти в интерфейсе AdMob. Добавьте идентификатор в Info.plist с помощью следующего фрагмента кода:

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

Как получить информацию о согласии пользователя

Запрашивайте обновление информации о согласии пользователя при каждом запуске приложения с помощью метода requestConsentInfoUpdate(with:completionHandler:). При этом проверяется следующее:

• Требуется ли согласие. Например, если согласие запрашивается впервые или срок действия предыдущего согласия истек.
• Нужна ли точка входа для настроек конфиденциальности. Некоторые сообщения о конфиденциальности требуют, чтобы приложения позволяли пользователям в любое время изменять настройки конфиденциальности.

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

Загрузка и показ формы сообщения о конфиденциальности

Получив актуальный статус согласия, вызовите loadAndPresentIfRequired(from:), чтобы загрузить формы, необходимые для получения согласия пользователя. После загрузки формы сразу же показываются.

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

Настройки конфиденциальности

Некоторые формы сообщений о конфиденциальности показываются в точке входа для настроек конфиденциальности, которую создает издатель. Это позволяет пользователям в любой момент изменить свои настройки конфиденциальности. Подробнее о том, какое сообщение увидят пользователи, выбравшие вариант конфиденциальности, читайте в статье Доступные типы сообщений для пользователей.

Как проверить, требуется ли точка входа для параметров конфиденциальности

После вызова requestConsentInfoUpdate(with:completionHandler:) проверьте UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus, чтобы определить, требуется ли для вашего приложения точка входа для настроек конфиденциальности. Если да, добавьте в приложение видимый и интерактивный элемент интерфейса, который будет открывать форму настроек конфиденциальности. Если точка доступа к настройкам конфиденциальности не требуется, сделайте элемент интерфейса невидимым и неактивным.

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

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

Полный список статусов требований к настройкам конфиденциальности приведен в UMPPrivacyOptionsRequirementStatus.

Покажите форму с настройками конфиденциальности

Когда пользователь взаимодействует с вашим элементом, покажите ему форму с настройками конфиденциальности:

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

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

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

Как запрашивать объявления с согласия пользователя

Прежде чем запрашивать объявления, используйте UMPConsentInformation.sharedInstance.canRequestAds, чтобы проверить, получено ли согласие пользователя:

ConsentInformation.shared.canRequestAds

UMPConsentInformation.sharedInstance.canRequestAds;

Ниже перечислены места, в которых можно проверить, запрашивается ли реклама во время сбора согласия.

• После того как UMP SDK получит согласие в текущем сеансе.
• Сразу после вызова requestConsentInfoUpdate(with:completionHandler:). Возможно, UMP SDK получил согласие в предыдущем сеансе приложения.

Если в процессе получения согласия возникает ошибка, проверьте, можете ли вы запрашивать объявления. UMP SDK использует статус согласия из предыдущего сеанса приложения.

Как избежать лишних запросов объявлений

При проверке UMPConsentInformation.sharedInstance.canRequestAds после получения согласия и вызова requestConsentInfoUpdate(with:completionHandler:) убедитесь, что ваша логика предотвращает избыточные запросы объявлений, которые могут привести к тому, что обе проверки вернут true. Например, с помощью логической переменной.

Тестирование

Чтобы протестировать интеграцию в приложении во время разработки, выполните следующие действия для программной регистрации тестового устройства. Перед публикацией приложения не забудьте удалить код, который задает эти идентификаторы тестовых устройств.

1. Позвоните в компанию " requestConsentInfoUpdate(with:completionHandler:)".

2. Найдите в журнале сообщение, похожее на приведенное ниже. В нем будет указан идентификатор устройства и инструкции по его добавлению в качестве тестового.

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

3. Скопируйте идентификатор тестового устройства в буфер обмена.

4. Измените код, чтобы вызвать UMPDebugSettings().testDeviceIdentifiers и передать список идентификаторов тестовых устройств.

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

Принудительное указание местоположения

UMP SDK позволяет проверить, как будет работать приложение для пользователей из разных регионов, например из Европейской экономической зоны (ЕЭЗ), Великобритании и Швейцарии. Для этого используется geography. Обратите внимание, что настройки отладки работают только на тестовых устройствах.

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

Сбросить статус согласия

При тестировании приложения с UMP SDK может быть полезно сбросить состояние SDK, чтобы смоделировать первый запуск приложения пользователем. Для этого в SDK предусмотрен метод reset.

ConsentInformation.shared.reset()

[UMPConsentInformation.sharedInstance reset];

Примеры на GitHub

Полный пример интеграции UMP SDK, описанный на этой странице, можно найти в

• Пример баннера на Swift
• SwiftUIDemo
• Objective-C BannerExample