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

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

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

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

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

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

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

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

/**
 * Requests consent information update on app launch.
 */
export function requestConsent(onComplete?: () => void) {
  requestConsentInfoUpdate({}, (error) => {
    if (error) {
      console.warn('Consent info update error:', error.message);
    } else {
      console.log('Consent info update complete.');
    }

    // Load and show consent form if required.
    loadAndPresentConsentForm(onComplete);
  });
}

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

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

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

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

/**
 * Loads and presents the privacy message form if required to collect user consent.
 */
export function loadAndPresentConsentForm(onComplete?: () => void) {
  loadAndShowConsentFormIfRequired((formError) => {
    if (formError) {
      console.warn('Consent form error:', formError.message);
    } else {
      console.log('Consent gathering complete.');
    }

    // Execute logic that depends on consent state (for example, initialize the SDK).
    onComplete?.();
  });
}

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

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

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

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

/**
 * Helper to determine if the privacy options entry point is required.
 */
export function isPrivacyOptionsRequired(): boolean {
  return (
    getPrivacyOptionsRequirementStatus() ===
    PrivacyOptionsRequirementStatus.REQUIRED
  );
}

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

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

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

/**
 * Renders a privacy options button if required by user consent policy.
 */
export function PrivacyOptionsButton({
  onDismissed,
}: {
  onDismissed?: (error?: FormError) => void;
}) {
  const isRequired =
    getPrivacyOptionsRequirementStatus() ===
    PrivacyOptionsRequirementStatus.REQUIRED;

  if (!isRequired) {
    return null;
  }

  const handleShowPrivacyOptions = () => {
    showPrivacyOptionsForm((error) => {
      if (error) {
        console.error('Failed to show privacy options form:', error.message);
      } else {
        console.log('Privacy options form dismissed.');
      }

      // Execute custom logic after form is dismissed.
      onDismissed?.(error);
    });
  };

  return <Button title="Privacy Settings" onPress={handleShowPrivacyOptions} />;
}

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

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

/**
 * Checks whether user consent allows requesting ads and initializes the SDK.
 */
let isMobileAdsInitialized = false;

export function initializeMobileAdsSdkIfConsentGiven() {
  if (canRequestAds()) {
    if (!isMobileAdsInitialized) {
      isMobileAdsInitialized = true;
      initialize({}, (status) => {
        console.log('Google Mobile Ads SDK initialized:', status);
      });
    }
  }
}

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

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

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

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

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

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

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

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

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

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

   Android

   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. Измените код, чтобы вызвать consentDebugSettings.testDeviceIdentifiers и передать список идентификаторов тестовых устройств.

   /**
    * Registers a test device for testing consent flows.
    */
   export function configureTestDevice() {
     requestConsentInfoUpdate(
       {
         consentDebugSettings: {
           debugGeography: DebugGeography.DISABLED,
           testDeviceIdentifiers: ["TEST_DEVICE_HASHED_ID"],
         },
       },
       (error) => {
         if (!error) {
           console.log('Test device registered.');
         }
       },
     );
   }

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

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

/**
 * Configures debug settings to force EEA geography on a test device.
 */
export function configureDebugGeography() {
  requestConsentInfoUpdate(
    {
      consentDebugSettings: {
        debugGeography: DebugGeography.EEA,
        testDeviceIdentifiers: ["TEST_DEVICE_HASHED_ID"],
      },
    },
    (error) => {
      if (!error) {
        console.log('Consent debug test configuration loaded.');
      }
    },
  );
}

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

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

/**
 * Resets consent state for testing purposes.
 */
export function resetConsentState() {
  reset();
}

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