Configurar o SDK da plataforma de mensagens aos usuários (UMP, na sigla em inglês) do Google

O SDK da plataforma de mensagens de usuários (UMP) do Google é uma ferramenta de privacidade e mensagens que ajuda você a gerenciar as opções de privacidade. Para mais informações, consulte Sobre a ferramenta Privacidade e mensagens.

Criar um tipo de mensagem

Crie mensagens do usuário com um dos tipos disponíveis na guia Privacidade e mensagens da sua conta da AdMob. O SDK da UMP tenta mostrar uma mensagem de privacidade criada com base no ID do aplicativo da AdMob definido no seu projeto.

Solicite uma atualização das informações de consentimento do usuário sempre que o app for iniciado, usando requestConsentInfoUpdate(). Essa solicitação verifica o seguinte:

  • Se o consentimento é obrigatório. Por exemplo, o consentimento é necessário pela primeira vez ou a decisão de consentimento anterior expirou.
  • Se um ponto de entrada de opções de privacidade é necessário. Algumas mensagens de privacidade exigem que os apps permitam que os usuários modifiquem as opções de privacidade a qualquer momento.
/**
 * 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);
  });
}

Carregar e apresentar o formulário de mensagem de privacidade

Depois de receber o status de consentimento mais atualizado, chame loadAndShowConsentFormIfRequired() para carregar os formulários necessários para coletar o consentimento do usuário. Depois de carregados, os formulários são apresentados imediatamente.

/**
 * 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?.();
  });
}

Opções de privacidade

Alguns formulários de mensagem de privacidade são apresentados em um ponto de entrada de opções de privacidade renderizado pelo editor, permitindo que os usuários gerenciem as opções de privacidade a qualquer momento. Para saber mais sobre qual mensagem os usuários veem no ponto de entrada das opções de privacidade, consulte Tipos de mensagens disponíveis para o usuário.

Verificar se um ponto de entrada de opções de privacidade é necessário

Depois de chamar requestConsentInfoUpdate(), verifique getPrivacyOptionsRequirementStatus() para determinar se um ponto de entrada de opções de privacidade é necessário para seu app. Se for, adicione um elemento de interface visível e interativo ao app que apresente o formulário de opções de privacidade. Se um ponto de entrada de privacidade não for necessário, configure o elemento da interface para que ele não fique visível nem interativo.

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

Para ver a lista completa de status de requisitos das opções de privacidade, consulte PrivacyOptionsRequirementStatus.

Apresentar o formulário de opções de privacidade

Quando o usuário interagir com seu elemento, apresente o formulário de opções de privacidade:

/**
 * 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} />;
}

Solicitar anúncios com o consentimento do usuário

Antes de solicitar anúncios, use canRequestAds() para verificar se você recebeu o consentimento do usuário:

/**
 * 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);
      });
    }
  }
}

Confira os seguintes lugares para verificar se você pode solicitar anúncios enquanto coleta o consentimento:

  • Depois que o SDK da UMP coletar o consentimento na sessão atual.
  • Imediatamente após chamar requestConsentInfoUpdate(). O SDK da UMP pode ter recebido consentimento na sessão anterior do app.

Se ocorrer um erro durante o processo de coleta de consentimento, verifique se é possível solicitar anúncios. O SDK da UMP usa o status de consentimento da sessão anterior do app.

Evitar trabalho repetitivo na solicitação de anúncio

Ao verificar canRequestAds() depois de coletar o consentimento e chamar requestConsentInfoUpdate(), verifique se a lógica impede solicitações de anúncios redundantes que podem fazer com que as duas verificações retornem true. Por exemplo, com uma variável booleana.

Teste

Se você quiser testar a integração no app durante o desenvolvimento, siga estas etapas para registrar seu dispositivo de teste de maneira programática. Remova o código que define esses IDs de dispositivo de teste antes de lançar o app.

  1. Ligue para a requestConsentInfoUpdate().

  2. Procure uma mensagem semelhante a esta na saída do registro. Ela mostra o ID do dispositivo e como adicioná-lo como um dispositivo de teste:

    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. Copie o ID do dispositivo de teste para a área de transferência.

  4. Modifique o código para chamar consentDebugSettings.testDeviceIdentifiers e transmita uma lista dos IDs dos dispositivos de teste.

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

Forçar uma região geográfica

O SDK da UMP permite testar o comportamento do app como se o dispositivo estivesse localizado em várias regiões, como o Espaço Econômico Europeu (EEE), o Reino Unido e a Suíça, usando DebugGeography. As configurações de depuração só funcionam em dispositivos de teste.

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

Ao testar seu app com o SDK da UMP, pode ser útil redefinir o estado do SDK para simular a primeira experiência de instalação de um usuário. O SDK fornece o método reset() para fazer isso.

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