Начать

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

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

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

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

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

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

Установите SDK

1. Следуйте инструкциям по установке Google Mobile Ads (GMA) C++ SDK . UMP C++ SDK включен в GMA C++ SDK.

2. Прежде чем продолжить, убедитесь, что вы настроили идентификатор приложения AdMob в проекте.

3. В своем коде инициализируйте UMP SDK, вызвав ConsentInfo::GetInstance() .

   • На Android вам необходимо передать JNIEnv и Activity предоставленные NDK. Вам нужно сделать это только при первом вызове GetInstance() .
   • В качестве альтернативы, если вы уже используете Firebase C++ SDK в своем приложении, вы можете передать firebase::App при первом вызове GetInstance() .

   #include "firebase/gma/ump.h"
   
   namespace ump = ::firebase::gma::ump;
   
   // Initialize using a firebase::App
   void InitializeUserMessagingPlatform(const firebase::App& app) {
     ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance(app);
   }
   
   // Initialize without a firebase::App
   #ifdef ANDROID
   void InitializeUserMessagingPlatform(JNIEnv* jni_env, jobject activity) {
     ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance(jni_env, activity);
   }
   #else  // non-Android
   void InitializeUserMessagingPlatform() {
     ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
   }
   #endif
   

Последующие вызовы ConsentInfo::GetInstance() возвращают один и тот же экземпляр.

Примечание. Методы GetInstance() имеют дополнительный выходной параметр firebase::InitResult , который возвращает firebase::kInitResultSuccess , если SDK был успешно инициализирован, или firebase::kInitResultFailedMissingDependency если в вашем приложении отсутствуют какие-либо необходимые зависимости. В случае возникновения этой ошибки убедитесь, что вы выполнили все шаги установки для вашей платформы.

Если вы закончили использовать UMP SDK, вы можете закрыть SDK, удалив экземпляр ConsentInfo :

void ShutdownUserMessagingPlatform() {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
  delete consent_info;
}

Примечание. Вам не нужно инициализировать SDK Google Mobile Ads C++ перед инициализацией SDK User Messaging Platform.

Используйте Future для мониторинга асинхронных операций

firebase::Future предоставляет вам возможность определить статус завершения вызовов асинхронных методов.

Все функции и вызовы методов UMP C++, которые работают асинхронно, возвращают Future , а также предоставляют функцию «последнего результата» для получения Future из самой последней операции.

Есть два способа получить результат из Future :

1. Вызовите OnCompletion() , передав собственную функцию обратного вызова, которая вызывается после завершения операции.
2. Периодически проверяйте статус Future status() . Когда статус меняется с kFutureStatusPending на kFutureStatusCompleted , операция завершена.

После завершения асинхронной операции вам следует проверить функцию Future error() чтобы получить код ошибки операции. Если код ошибки равен 0 ( kConsentRequestSuccess или kConsentFormSuccess ), операция завершена успешно; в противном случае проверьте код ошибки и error_message() чтобы определить, что пошло не так.

Примечание. Код ошибки, возвращаемый RequestConsentInfoUpdate() использует перечисление ConsentRequestError ; все остальные операции используют ConsentFormError .

Обратный вызов завершения

Вот пример того, как использовать OnCompletion для установки обратного вызова завершения, который вызывается после завершения асинхронной операции.

void MyApplicationStart() {
  // [... other app initialization code ...]

  ump::ConsentInfo *consent_info = ump::ConsentInfo::GetInstance();

  // See the section below for more information about RequestConsentInfoUpdate.
  firebase::Future<void> result = consent_info->RequestConsentInfoUpdate(...);

  result.OnCompletion([](const firebase::Future<void>& req_result) {
    if (req_result.error() == ump::kConsentRequestSuccess) {
      // Operation succeeded. You can now call LoadAndShowConsentFormIfRequired().
    } else {
      // Operation failed. Check req_result.error_message() for more information.
    }
  });
}

Обновление опроса цикла

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

ump::ConsentInfo *g_consent_info = nullptr;
bool g_waiting_for_request = false;

void MyApplicationStart() {
  // [... other app initialization code ...]

  g_consent_info = ump::ConsentInfo::GetInstance();
  // See the section below for more information about RequestConsentInfoUpdate.
  g_consent_info->RequestConsentInfoUpdate(...);
  g_waiting_for_request = true;
}

// Elsewhere, in the game's update loop, which runs once per frame:
void MyGameUpdateLoop() {
  // [... other game logic here ...]

  if (g_waiting_for_request) {
    // Check whether RequestConsentInfoUpdate() has finished.
    // Calling "LastResult" returns the Future for the most recent operation.
    firebase::Future<void> result =
      g_consent_info->RequestConsentInfoUpdateLastResult();

    if (result.status() == firebase::kFutureStatusComplete) {
      g_waiting_for_request = false;
      if (result.error() == ump::kConsentRequestSuccess) {
        // Operation succeeded. You can call LoadAndShowConsentFormIfRequired().
      } else {
        // Operation failed. Check result.error_message() for more information.
      }
    }
  }
}

Дополнительные сведения о firebase::Future см. в документации Firebase C++ SDK и документации GMA C++ SDK .

Примечание. В SDK UMP C++ все асинхронные операции возвращают firebase::Future<void> .

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

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

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

#include "firebase/gma/ump.h"

namespace ump = ::firebase::gma::ump;

void MyApplicationStart(ump::FormParent parent) {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  consent_info->RequestConsentInfoUpdate(params).OnCompletion(
    [*](const Future<void>& req_result) {
      if (req_result.error() != ump::kConsentRequestSuccess) {
        // req_result.error() is a kConsentRequestError enum.
        LogMessage("Error requesting consent update: %s", req_result.error_message());
      }
      // Consent information is successfully updated.
    });
}

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

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

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

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

#include "firebase/gma/ump.h"

namespace ump = ::firebase::gma::ump;

void MyApplicationStart(ump::FormParent parent) {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  consent_info->RequestConsentInfoUpdate(params).OnCompletion(
    [*](const Future<void>& req_result) {
      if (req_result.error() != ump::kConsentRequestSuccess) {
        // req_result.error() is a kConsentRequestError enum.
        LogMessage("Error requesting consent update: %s", req_result.error_message());
      } else {
        consent_info->LoadAndShowConsentFormIfRequired(parent).OnCompletion(
        [*](const Future<void>& form_result) {
          if (form_result.error() != ump::kConsentFormSuccess) {
            // form_result.error() is a kConsentFormError enum.
            LogMessage("Error showing privacy message form: %s", form_result.error_message());
          } else {
            // Either the form was shown and completed by the user, or consent was not required.
          }
        });
      }
    });
}

См . выше пример проверки завершения с использованием опроса цикла обновления, а не обратного вызова завершения.

Примечание. В зависимости от платформы FormParent — это либо ссылка jobject JNI на Android Activity , либо указатель на iOS UIViewController , приведенный к типу FormParent .

Если вам нужно выполнить какие-либо действия после того, как пользователь сделал выбор или закрыл форму, поместите эту логику в код, который обрабатывает Future , возвращаемый LoadAndShowConsentFormIfRequired() .

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

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

Запросить рекламу с согласия пользователя

Прежде чем запрашивать рекламу, используйте ConsentInfo::GetInstance()‑> CanRequestAds() , чтобы проверить, получили ли вы согласие от пользователя:

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

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

Важно: ConsentInfo::GetInstance()‑> CanRequestAds() всегда возвращает false , пока вы не вызовете RequestConsentInfoUpdate()

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

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

#include "firebase/future.h"
#include "firebase/gma/gma.h"
#include "firebase/gma/ump.h"

namespace gma = ::firebase::gma;
namespace ump = ::firebase::gma::ump;
using firebase::Future;

ump::ConsentInfo* g_consent_info = nullptr;
// State variable for tracking the UMP consent flow.
enum { kStart, kRequest, kLoadAndShow, kInitGma, kFinished, kErrorState } g_state = kStart;
bool g_ads_allowed = false;

void MyApplicationStart() {
  g_consent_info = ump::ConsentInfo::GetInstance(...);

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  g_consent_info->RequestConsentInfoUpdate(params);
  // CanRequestAds() can return a cached value from a previous run immediately.
  g_ads_allowed = g_consent_info->CanRequestAds();
  g_state = kRequest;
}

// This function runs once per frame.
void MyGameUpdateLoop() {
  // [... other game logic here ...]

  if (g_state == kRequest) {
    Future<void> req_result = g_consent_info->RequestConsentInfoUpdateLastResult();

    if (req_result.status() == firebase::kFutureStatusComplete) {
      g_ads_allowed = g_consent_info->CanRequestAds();
      if (req_result.error() == ump::kConsentRequestSuccess) {
        // You must provide the FormParent (Android Activity or iOS UIViewController).
        ump::FormParent parent = GetMyFormParent();
        g_consent_info->LoadAndShowConsentFormIfRequired(parent);
        g_state = kLoadAndShow;
      } else {
        LogMessage("Error requesting consent status: %s", req_result.error_message());
        g_state = kErrorState;
      }
    }
  }
  if (g_state == kLoadAndShow) {
    Future<void> form_result = g_consent_info->LoadAndShowConsentFormIfRequiredLastResult();

    if (form_result.status() == firebase::kFutureStatusComplete) {
      g_ads_allowed = g_consent_info->CanRequestAds();
      if (form_result.error() == ump::kConsentRequestSuccess) {
        if (g_ads_allowed) {
          // Initialize GMA. This is another asynchronous operation.
          firebase::gma::Initialize();
          g_state = kInitGma;
        } else {
          g_state = kFinished;
        }
        // Optional: shut down the UMP SDK to save memory.
        delete g_consent_info;
        g_consent_info = nullptr;
      } else {
        LogMessage("Error displaying privacy message form: %s", form_result.error_message());
        g_state = kErrorState;
      }
    }
  }
  if (g_state == kInitGma && g_ads_allowed) {
    Future<gma::AdapterInitializationStatus> gma_future = gma::InitializeLastResult();

    if (gma_future.status() == firebase::kFutureStatusComplete) {
      if (gma_future.error() == gma::kAdErrorCodeNone) {
        g_state = kFinished;
        // TODO: Request an ad.
      } else {
        LogMessage("Error initializing GMA: %s", gma_future.error_message());
        g_state = kErrorState;
      }
    }
  }
}

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

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

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

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

   Андроид

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

   iOS

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

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

4. Измените свой код, чтобы задать для ConsentRequestParameters.debug_settings.debug_device_ids список идентификаторов тестовых устройств.

   void MyApplicationStart() {
     ump::ConsentInfo consent_info = ump::ConsentInfo::GetInstance(...);
   
     ump::ConsentRequestParameters params;
     params.tag_for_under_age_of_consent = false;
     params.debug_settings.debug_device_ids = {"TEST-DEVICE-HASHED-ID"};
   
     consent_info->RequestConsentInfoUpdate(params);
   }
   

Принудительно использовать географию

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

void MyApplicationStart() {
  ump::ConsentInfo consent_info = ump::ConsentInfo::GetInstance(...);

  ump::ConsentRequestParameters params;
  params.tag_for_under_age_of_consent = false;
  params.debug_settings.debug_device_ids = {"TEST-DEVICE-HASHED-ID"};
  // Geography appears as EEA for debug devices.
  params.debug_settings.debug_geography = ump::kConsentDebugGeographyEEA

  consent_info->RequestConsentInfoUpdate(params);
}

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

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

  ConsentInfo::GetInstance()->Reset();

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