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

Выберите платформу: Android iOS Unity Flutter Android (устаревшая версия)

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

Требования

• Android с уровнем API 21 или более поздней версии.

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

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

Подробнее о конфиденциальности и сообщениях…

Как установить с помощью Gradle

Добавьте зависимость для Google User Messaging Platform SDK в файл Gradle на уровне приложения, обычно это app/build.gradle:

dependencies {
  implementation("com.google.android.ump:user-messaging-platform:4.0.0")
}

После того как вы внесете изменения в файл build.gradle приложения, обязательно синхронизируйте проект с файлами Gradle.

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

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

<manifest>
  <application>
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
  </application>
</manifest>

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

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

Объявите экземпляр ConsentInformation:

Java

private final ConsentInformation consentInformation;

Kotlin

private lateinit var consentInformation: ConsentInformation

Инициализируйте экземпляр ConsentInformation:

Java

consentInformation = UserMessagingPlatform.getConsentInformation(context);

Kotlin

consentInformation = UserMessagingPlatform.getConsentInformation(context)

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

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

Java

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
    activity,
    params,
    () -> // Called when consent information is successfully updated.
    requestConsentError -> // Called when there's an error updating consent information.
GoogleMobileAdsConsentManager.java

Kotlin

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
  activity,
  params,
  {
    // Called when consent information is successfully updated.
  },
  { requestConsentError ->
    // Called when there's an error updating consent information.
  },
)
GoogleMobileAdsConsentManager.kt

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

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

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

Важно! Если ни одна из форм сообщений о конфиденциальности не требует согласия пользователя до запроса объявлений, обратный вызов выполняется немедленно.

Java

UserMessagingPlatform.loadAndShowConsentFormIfRequired(
    activity,
    formError -> {
      // Consent gathering process is complete.
    });
GoogleMobileAdsConsentManager.java

Kotlin

UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
  // Consent gathering process is complete.
}
GoogleMobileAdsConsentManager.kt

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

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

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

После вызова requestConsentInfoUpdate() проверьте getPrivacyOptionsRequirementStatus(), чтобы определить, нужна ли вашему приложению точка входа для настроек конфиденциальности. Если она необходима, добавьте в приложение видимый интерактивный элемент интерфейса, который будет открывать форму настроек конфиденциальности. Если точка входа для настроек конфиденциальности не требуется, настройте элемент интерфейса так, чтобы он был невидим и недоступен для взаимодействия.

Java

/** Helper variable to determine if the privacy options form is required. */
public boolean isPrivacyOptionsRequired() {
  return consentInformation.getPrivacyOptionsRequirementStatus()
      == PrivacyOptionsRequirementStatus.REQUIRED;
}
GoogleMobileAdsConsentManager.java

Kotlin

/** Helper variable to determine if the privacy options form is required. */
val isPrivacyOptionsRequired: Boolean
  get() =
    consentInformation.privacyOptionsRequirementStatus ==
      ConsentInformation.PrivacyOptionsRequirementStatus.REQUIRED
GoogleMobileAdsConsentManager.kt

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

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

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

Java

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener);
GoogleMobileAdsConsentManager.java

Kotlin

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

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

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

Java

consentInformation.canRequestAds();

Kotlin

consentInformation.canRequestAds()

Ниже перечислены места, где можно проверить, можно ли запрашивать объявления при сборе согласия:

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

Важно! canRequestAds() всегда возвращает false, пока вы не вызовете requestConsentInfoUpdate()

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

Предотвращение избыточной работы по запросу объявлений

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

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

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

Примечание. Начиная с версии 2.2.0 эмуляторы не нужно добавлять в список идентификаторов устройств, поскольку по умолчанию они считаются тестовыми устройствами.

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

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

   Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
   

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

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

   Java

   ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this)
       .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
       .build();
   
   ConsentRequestParameters params = new ConsentRequestParameters
       .Builder()
       .setConsentDebugSettings(debugSettings)
       .build();
   
   consentInformation = UserMessagingPlatform.getConsentInformation(this);
   // Include the ConsentRequestParameters in your consent request.
   consentInformation.requestConsentInfoUpdate(
       this,
       params,
       // ...
   );
   

   Kotlin

   val debugSettings = ConsentDebugSettings.Builder(this)
       .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
       .build()
   
   val params = ConsentRequestParameters
       .Builder()
       .setConsentDebugSettings(debugSettings)
       .build()
   
   consentInformation = UserMessagingPlatform.getConsentInformation(this)
   // Include the ConsentRequestParameters in your consent request.
   consentInformation.requestConsentInfoUpdate(
       this,
       params,
       // ...
   )
   

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

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

Java

ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this)
    .setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build();

ConsentRequestParameters params = new ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build();

consentInformation = UserMessagingPlatform.getConsentInformation(this);
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    ...
);

Kotlin

val debugSettings = ConsentDebugSettings.Builder(this)
    .setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build()

val params = ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build()

consentInformation = UserMessagingPlatform.getConsentInformation(this)
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    ...
)

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

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

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

Внимание! Этот метод предназначен только для тестирования. Не вызывайте функцию reset() в рабочем коде.

Примеры на GitHub

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