Começar

O SDK da plataforma de mensagens de usuários (UMP, na sigla em inglês) do Google é uma ferramenta de privacidade e mensagens para ajudar você a gerenciar as escolhas de privacidade. Para mais informações, consulte Sobre a página "Privacidade e mensagens".

Pré-requisitos

• Android API de nível 21 ou mais recente

Criar um tipo de mensagem

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

Para mais detalhes, consulte Sobre privacidade e mensagens.

Instalar com o Gradle

Adicione a dependência do SDK da plataforma de mensagens de usuários do Google ao arquivo Gradle do módulo no nível do app, normalmente app/build.gradle:

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

Depois de fazer as mudanças na build.gradle do app, sincronize o projeto com os arquivos do Gradle.

Adicionar o ID do aplicativo

Você encontra o ID do aplicativo na interface do Ad Manager. Adicione o ID ao seu AndroidManifest.xml com o seguinte snippet de código:

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

Coletar consentimento

Para coletar o consentimento, siga estas etapas:

1. Solicitar as informações mais recentes de consentimento do usuário.
2. Carregue e apresente um formulário de consentimento, se necessário.

Solicitação de informações de consentimento

Peça uma atualização das informações de consentimento do usuário em cada inicialização do app 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 anterior expirou.
• Define se um ponto de entrada de opções de privacidade é obrigatório. Algumas mensagens de privacidade exigem que os apps permitam que os usuários modifiquem as opções de privacidade a qualquer momento.

Aviso: usar outras maneiras de verificar o status de consentimento, como o cache no app ou uma string de consentimento salva anteriormente, pode levar a um erro do TCF 3.3 se o consentimento estiver vencido.

Carregue e apresente um formulário de mensagem de privacidade, se necessário

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

Importante :se nenhum formulário de mensagem de privacidade exigir o consentimento do usuário antes de solicitar anúncios, o callback será invocado imediatamente.

O código abaixo demonstra como solicitar as informações de consentimento mais recentes do usuário. Se necessário, o código é carregado e apresenta um formulário de mensagem de privacidade:

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));
GoogleMobileAdsConsentManager.java

Kotlin

// 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)
  },
)
GoogleMobileAdsConsentManager.kt

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 é exibida aos usuários no ponto de entrada das opções de privacidade, consulte Tipos de mensagens do usuário disponíveis.

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

Depois de chamar requestConsentInfoUpdate(), consulte ConsentInformation.PivacyOptionsRequirementStatus para determinar se um ponto de entrada de opções de privacidade é necessário para o app:

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

Adicionar um elemento visível ao app

Se um ponto de entrada de privacidade for necessário, 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 não ser visível e interativo.

Java

if (googleMobileAdsConsentManager.isPrivacyOptionsRequired()) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu();
}
MyActivity.java

Kotlin

if (googleMobileAdsConsentManager.isPrivacyOptionsRequired) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu()
}
MainActivity.kt

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

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

Java

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

Kotlin

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

Solicitar anúncios

Antes de solicitar anúncios no seu app, verifique se você recebeu o consentimento do usuário usando canRequestAds(). Há dois lugares para verificar ao coletar o consentimento:

• Depois que o consentimento foi coletado na sessão atual.
• Imediatamente após chamar requestConsentInfoUpdate(). É possível que o consentimento tenha sido dado na sessão anterior. Como prática recomendada para latência, recomendamos não esperar a conclusão do callback para que você possa começar a carregar anúncios assim que possível após o lançamento do app.

Observação: canRequestAds() sempre retorna false até que você chame requestConsentInfoUpdate()

.

Se ocorrer um erro durante o processo de coleta de consentimento, ainda será necessário verificar se você pode solicitar anúncios. O SDK do UMP usa o status de consentimento da sessão anterior.

O código a seguir verifica se você pode solicitar anúncios durante o processo de solicitação de consentimento:

Java

googleMobileAdsConsentManager.gatherConsent(
    this,
    consentError -> {
      if (consentError != null) {
        // Consent not obtained in current session.
        Log.w(
            TAG,
            String.format("%s: %s", consentError.getErrorCode(), consentError.getMessage()));
      }

      if (googleMobileAdsConsentManager.canRequestAds()) {
        initializeMobileAdsSdk();
      }
      // ...
    });

// This sample attempts to load ads using consent obtained in the previous session.
if (googleMobileAdsConsentManager.canRequestAds()) {
  initializeMobileAdsSdk();
}

Kotlin

googleMobileAdsConsentManager.gatherConsent(this) { error ->
  if (error != null) {
    // Consent not obtained in current session.
    Log.d(TAG, "${error.errorCode}: ${error.message}")
  }

  if (googleMobileAdsConsentManager.canRequestAds) {
    initializeMobileAdsSdk()
  }
  // ...
}

// This sample attempts to load ads using consent obtained in the previous session.
if (googleMobileAdsConsentManager.canRequestAds) {
  initializeMobileAdsSdk()
}

O código abaixo configura o SDK dos anúncios para dispositivos móveis do Google depois que o consentimento do usuário é coletado:

Java

private void initializeMobileAdsSdk() {
  if (isMobileAdsInitializeCalled.getAndSet(true)) {
    return;
  }
  new Thread(
          () -> {
            // Initialize the Google Mobile Ads SDK on a background thread.
            MobileAds.initialize(this, initializationStatus -> {});

            // Load an ad on the main thread.
            runOnUiThread(this::loadBanner);
          })
      .start();
}
MyActivity.java

Kotlin

private fun initializeMobileAdsSdk() {
  if (isMobileAdsInitializeCalled.getAndSet(true)) {
    return
  }
  CoroutineScope(Dispatchers.IO).launch {
    // Initialize the Google Mobile Ads SDK on a background thread.
    MobileAds.initialize(this@MainActivity) {}

    runOnUiThread {
      // Load an ad on the main thread.
      loadBanner()
    }
  }
}
MainActivity.kt

Teste

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

Observação: A partir da versão 2.2.0, os emuladores não precisam ser adicionados à lista de IDs de dispositivos, porque são dispositivos de teste por padrão.

1. Ligue para a requestConsentInfoUpdate().

2. Verifique se há uma mensagem semelhante ao exemplo abaixo na saída do registro, que mostra o ID do dispositivo e como adicioná-lo como um dispositivo de teste:

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

3. Copie o ID do dispositivo de teste para a área de transferência.

4. Modifique seu código para chamar ConsentDebugSettings.Builder().TestDeviceHashedIds e transmita uma lista dos IDs do dispositivo de teste.

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

Forçar uma região geográfica

O SDK da UMP oferece uma maneira de testar o comportamento do app como se o dispositivo estivesse localizado em várias regiões, como o EEE ou o Reino Unido, usando DebugGeography. As configurações de depuração só funcionam em dispositivos de teste.

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

Redefinir o estado de consentimento

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

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

Cuidado: esse método é destinado apenas a testes. Não chame reset() no código de produção.

Exemplos no GitHub

Confira um exemplo completo da integração do SDK da UMP abordada nesta página em Java BannerExample e Kotlin BannerExample.