Начать

SDK Google User Messaging Platform (UMP) – это инструмент конфиденциальности и обмена сообщениями, который поможет вам управлять настройками конфиденциальности. Дополнительную информацию см. в разделе «О конфиденциальности и обмене сообщениями» . Рабочую реализацию IMA с UMP SDK можно увидеть в примере приложения UMP .

Предварительные условия

• Android API уровня 21 или выше

Создайте тип сообщения

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

Дополнительные сведения см. в разделе О конфиденциальности и обмене сообщениями .

Установить с помощью Gradle

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

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

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

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

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

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

Получите согласие

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

1. Запрос самой последней информации о согласии пользователя.
2. Загрузите и при необходимости предоставьте форму согласия.

Запрос информации о согласии

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

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

Предупреждение. Использование других способов проверки статуса согласия, таких как кеш в вашем приложении или ранее сохраненная строка согласия, может привести к ошибке TCF 3.3, если срок действия согласия истек.

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

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

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

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

Ява

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
    activity,
    params,
    () ->
        UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            activity, onConsentGatheringCompleteListener::consentGatheringComplete),
    onConsentGatheringCompleteListener::consentGatheringComplete);
ConsentManager.java

Котлин

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
  activity,
  params,
  {
    UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
      // Consent has been gathered.
      onConsentGatheringCompleteListener.consentGatheringComplete(formError)
    }
  },
  { requestConsentError ->
    onConsentGatheringCompleteListener.consentGatheringComplete(requestConsentError)
  },
)

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

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

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

После вызова requestConsentInfoUpdate() проверьте ConsentInformation.PrivacyOptionsRequirementStatus , чтобы определить, требуется ли для вашего приложения точка входа параметров конфиденциальности:

Ява

/** Helper function to determine if a privacy options entry point is required. */
public boolean isPrivacyOptionsRequired() {
  return consentInformation.getPrivacyOptionsRequirementStatus()
      == PrivacyOptionsRequirementStatus.REQUIRED;
}
ConsentManager.java

Котлин

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

Добавьте видимый элемент в свое приложение

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

Ява

// Check ConsentInformation.getPrivacyOptionsRequirementStatus() to see the button should
// be shown or hidden.
if (consentManager.isPrivacyOptionsRequired()) {
  privacyButton.setVisibility(View.VISIBLE);
}
MyActivity.java

Котлин

// Check ConsentInformation.getPrivacyOptionsRequirementStatus() to see the button should
// be shown or hidden.
if (consentManager.isPrivacyOptionsRequired) {
  privacyButton.visibility = View.VISIBLE
}

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

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

Ява

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

Котлин

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)

Запросить рекламу

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

• После того, как согласие было получено в текущем сеансе.
• Сразу после вызова requestConsentInfoUpdate() . Возможно, согласие было получено на предыдущем сеансе. В целях снижения задержки мы рекомендуем не дожидаться завершения обратного вызова, чтобы вы могли начать загрузку рекламы как можно скорее после запуска приложения.

Примечание. canRequestAds() всегда возвращает false , пока вы не вызовете requestConsentInfoUpdate()

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

Следующий код проверяет, можете ли вы запрашивать рекламу в процессе сбора согласия:

Ява

consentManager.gatherConsent(
    consentError -> {
      if (consentError != null) {
        // Consent not obtained in current session.
        Log.i(
            LOGTAG,
            "Consent Error: "
                + String.format(
                    "%s: %s", consentError.getErrorCode(), consentError.getMessage()));
      }

      if (consentManager.canRequestAds()) {
        initializeImaSdk();
      } else {
        Log.i(LOGTAG, "Consent not available to request ads");
      }
      // ...
    });

// This sample attempts to load ads using consent obtained in the previous session.
if (consentManager.canRequestAds()) {
  initializeImaSdk();
}
MyActivity.java

Котлин

consentManager.gatherConsent(this) { error ->
  if (error != null) {
    // Consent not obtained in current session.
    Log.d(LOGTAG, "${error.errorCode}: ${error.message}")
  }
  if (consentManager.canRequestAds) {
    initializeImaSdk()
  } else {
    Log.i(LOGTAG, "Consent not available to request ads")
  }
  // ...
}
// This sample attempts to load ads using consent obtained in the previous session.
if (consentManager.canRequestAds) {
  initializeImaSdk()
}

Следующий код устанавливает IMA DAI SDK после получения согласия пользователя:

Ява

private void initializeImaSdk() {
  if (sdkFactory != null) {
    // If the SDK is already initialized, do nothing.
    return;
  }

  sdkFactory = ImaSdkFactory.getInstance();

  adDisplayContainer =
      ImaSdkFactory.createAdDisplayContainer(videoPlayerContainer, videoAdPlayerAdapter);

  createAdsLoader();
  setUpPlayButton();
}
MyActivity.java

Котлин

private fun initializeImaSdk() {
  sdkFactory = ImaSdkFactory.getInstance()
  adDisplayContainer = ImaSdkFactory.createAdDisplayContainer(videoPlayerContainer, videoAdPlayerAdapter)
  createAdsLoader()
  setUpPlayButton()
}

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

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

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

1. Вызовите requestConsentInfoUpdate() .

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

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

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

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

   Ява

   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,
       // ...
   );
   

   Котлин

   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 предоставляет возможность протестировать поведение вашего приложения, как если бы устройство находилось в различных регионах, например в ЕЭЗ или Великобритании, с помощью DebugGeography . Обратите внимание, что настройки отладки работают только на тестовых устройствах.

Ява

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,
    ...
);

Котлин

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() .

Ява

consentInformation.reset();

Котлин

consentInformation.reset()

Внимание: этот метод предназначен для использования только в целях тестирования. Вам не следует вызывать reset() в производственном коде.

Примеры на GitHub

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