Nativo avançado

Selecione a plataforma: Android iOS

Mostrar um NativeAd

Quando um anúncio nativo é carregado, o SDK dos anúncios para dispositivos móveis do Google invoca o listener do formato de anúncio correspondente. Dessa forma, o app é responsável por exibir o anúncio, embora ele não tenha que fazer isso imediatamente. Para facilitar a exibição de formatos de anúncio definidos pelo sistema, o SDK oferece alguns recursos úteis, conforme descrito abaixo.

Definir a classe NativeAdView

Defina uma classe NativeAdView. Essa classe é uma ViewGroup e é o contêiner de nível superior para uma classe NativeAdView. Cada visualização de anúncio nativo contém recursos, como o elemento de visualização MediaView ou Title, que precisa ser um filho do objeto NativeAdView.

Layout XML

Adicione um NativeAdView XML ao seu projeto:

<com.google.android.gms.ads.nativead.NativeAdView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content">
    <LinearLayout
    android:orientation="vertical">
        <LinearLayout
        android:orientation="horizontal">
          <ImageView
          android:id="@+id/ad_app_icon" />
          <TextView
            android:id="@+id/ad_headline" />
        </LinearLayout>
        <!--Add remaining assets such as the image and media view.-->
    </LinearLayout>
</com.google.android.gms.ads.nativead.NativeAdView>

Jetpack Compose

Inclua o módulo JetpackComposeDemo/compose-util, que inclui helpers para compor o NativeAdView e os recursos dele.

Usando o módulo compose-util, crie um NativeAdView:

  import com.google.android.gms.compose_util.NativeAdAttribution
  import com.google.android.gms.compose_util.NativeAdView

  @Composable
  /** Display a native ad with a user defined template. */
  fun DisplayNativeAdView(nativeAd: NativeAd) {
      NativeAdView {
          // Display the ad attribution.
          NativeAdAttribution(text = context.getString("Ad"))
          // Add remaining assets such as the image and media view.
        }
    }

Processar o anúncio nativo carregado

Quando um anúncio nativo é carregado, processe o evento de callback, aumente a visualização do anúncio nativo e adicione-o à hierarquia de visualização:

Java

AdLoader.Builder builder = new AdLoader.Builder(this, "/21775744923/example/native")
    .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
        @Override
        public void onNativeAdLoaded(NativeAd nativeAd) {
            // Assumes you have a placeholder FrameLayout in your View layout
            // (with ID fl_adplaceholder) where the ad is to be placed.
            FrameLayout frameLayout =
                findViewById(R.id.fl_adplaceholder);
            // Assumes that your ad layout is in a file call native_ad_layout.xml
            // in the res/layout folder
            NativeAdView adView = (NativeAdView) getLayoutInflater()
                .inflate(R.layout.native_ad_layout, null);
            // This method sets the assets into the ad view.
            populateNativeAdView(nativeAd, adView);
            frameLayout.removeAllViews();
            frameLayout.addView(adView);
        }
});

Kotlin

val builder = AdLoader.Builder(this, "/21775744923/example/native")
    .forNativeAd { nativeAd ->
        // Assumes you have a placeholder FrameLayout in your View layout
        // (with ID fl_adplaceholder) where the ad is to be placed.
        val frameLayout: FrameLayout = findViewById(R.id.fl_adplaceholder)
        // Assumes that your ad layout is in a file call native_ad_layout.xml
        // in the res/layout folder
        val adView = layoutInflater
                .inflate(R.layout.native_ad_layout, null) as NativeAdView
        // This method sets the assets into the ad view.
        populateNativeAdView(nativeAd, adView)
        frameLayout.removeAllViews()
        frameLayout.addView(adView)
    }

Jetpack Compose

@Composable
/** Load and display a native ad. */
fun NativeScreen() {
  var nativeAd by remember { mutableStateOf<NativeAd?>(null) }
  val context = LocalContext.current
  var isDisposed by remember { mutableStateOf(false) }

  DisposableEffect(Unit) {
    // Load the native ad when we launch this screen
    loadNativeAd(
      context = context,
      onAdLoaded = { ad ->
        // Handle the native ad being loaded.
        if (!isDisposed) {
          nativeAd = ad
        } else {
          // Destroy the native ad if loaded after the screen is disposed.
          ad.destroy()
        }
      },
    )
    // Destroy the native ad to prevent memory leaks when we dispose of this screen.
    onDispose {
      isDisposed = true
      nativeAd?.destroy()
      nativeAd = null
    }
  }

  // Display the native ad view with a user defined template.
  nativeAd?.let { adValue -> DisplayNativeAdView(adValue) }
}

fun loadNativeAd(context: Context, onAdLoaded: (NativeAd) -> Unit) {
  val adLoader =
    AdLoader.Builder(context, NATIVE_AD_UNIT_ID)
      .forNativeAd { nativeAd -> onAdLoaded(nativeAd) }
      .withAdListener(
        object : AdListener() {
          override fun onAdFailedToLoad(error: LoadAdError) {
            Log.e(TAG, "Native ad failed to load: ${error.message}")
          }

          override fun onAdLoaded() {
            Log.d(TAG, "Native ad was loaded.")
          }

          override fun onAdImpression() {
            Log.d(TAG, "Native ad recorded an impression.")
          }

          override fun onAdClicked() {
            Log.d(TAG, "Native ad was clicked.")
          }
        }
      )
      .build()
  adLoader.loadAd(AdRequest.Builder().build())
}

Todos os recursos de um determinado anúncio nativo precisam ser renderizados no layout NativeAdView. O SDK dos anúncios para dispositivos móveis do Google tenta registrar um aviso quando os recursos nativos são renderizados fora de um layout de visualização de anúncio nativo.

As classes de visualização de anúncio também fornecem métodos usados para registrar a visualização usada em cada recurso individual e um para registrar o objeto NativeAd em si. Ao registrar as visualizações desse modo, o SDK automaticamente realiza tarefas como:

  • Registro de cliques
  • Registro de impressões quando o primeiro pixel fica visível na tela
  • Mostrar a sobreposição do AdChoices para criativos de preenchimento nativo. No momento, isso está limitado a um grupo selecionado de editores.

Sobreposição das Opções de anúncios

Uma sobreposição das Opções de Anúncios é adicionada como uma visualização de anúncio pelo SDK quando um anúncio de preenchimento é retornado. Se o app usar o preenchimento de anúncios nativos, deixe espaço no canto desejado da visualização do anúncio nativo para o logotipo das Opções de Anúncios, que é inserido automaticamente. Além disso, a sobreposição precisa estar visível. Escolha cores de fundo e imagens adequadas. Para mais informações sobre a aparência e a função da sobreposição, consulte as diretrizes de implementação de anúncios nativos programáticos.

Atribuição para anúncios programáticos nativos

Ao veicular anúncios programáticos nativos, você precisa mostrar uma atribuição para indicar que a visualização é uma publicidade. Saiba mais nas nossas diretrizes da política.

Exemplo de código

Estas são as etapas para veicular um anúncio nativo:

  1. Crie uma instância da classe NativeAdView.
  2. Para cada recurso de anúncio que será exibido:

    1. Preencha a visualização de recurso com o recurso no objeto de anúncio.
    2. Registre a visualização de recurso com a classe NativeAdView.
  3. Registre o MediaView se o layout do seu anúncio nativo incluir um recurso de mídia grande.

  4. Registre o objeto de anúncio com a classe NativeAdView.

Confira um exemplo de função que mostra um NativeAd:

Java

private void displayNativeAd(ViewGroup parent, NativeAd ad) {

  // Inflate a layout and add it to the parent ViewGroup.
  LayoutInflater inflater = (LayoutInflater) parent.getContext()
          .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
  NativeAdView adView = (NativeAdView) inflater
          .inflate(R.layout.ad_layout_file, parent);

  // Locate the view that will hold the headline, set its text, and call the
  // NativeAdView's setHeadlineView method to register it.
  TextView headlineView = adView.findViewById<TextView>(R.id.ad_headline);
  headlineView.setText(ad.getHeadline());
  adView.setHeadlineView(headlineView);

  // Repeat the process for the other assets in the NativeAd
  // using additional view objects (Buttons, ImageViews, etc).

  // If the app is using a MediaView, it should be
  // instantiated and passed to setMediaView. This view is a little different
  // in that the asset is populated automatically, so there's one less step.
  MediaView mediaView = (MediaView) adView.findViewById(R.id.ad_media);
  adView.setMediaView(mediaView);

  // Call the NativeAdView's setNativeAd method to register the
  // NativeAdObject.
  adView.setNativeAd(ad);

  // Ensure that the parent view doesn't already contain an ad view.
  parent.removeAllViews();

  // Place the AdView into the parent.
  parent.addView(adView);
}

Kotlin

fun displayNativeAd(parent: ViewGroup, ad: NativeAd) {

  // Inflate a layout and add it to the parent ViewGroup.
  val inflater = parent.getContext().getSystemService(Context.LAYOUT_INFLATER_SERVICE)
          as LayoutInflater
  val adView = inflater.inflate(R.layout.ad_layout_file, parent) as NativeAdView

  // Locate the view that will hold the headline, set its text, and use the
  // NativeAdView's headlineView property to register it.
  val headlineView = adView.findViewById<TextView>(R.id.ad_headline)
  headlineView.text = ad.headline
  adView.headlineView = headlineView

  // Repeat the process for the other assets in the NativeAd using
  // additional view objects (Buttons, ImageViews, etc).

  val mediaView = adView.findViewById<MediaView>(R.id.ad_media)
  adView.mediaView = mediaView

  // Call the NativeAdView's setNativeAd method to register the
  // NativeAdObject.
  adView.setNativeAd(ad)

  // Ensure that the parent view doesn't already contain an ad view.
  parent.removeAllViews()

  // Place the AdView into the parent.
  parent.addView(adView)
}

Jetpack Compose

@Composable
/** Display a native ad with a user defined template. */
fun DisplayNativeAdView(nativeAd: NativeAd) {
  val context = LocalContext.current
  Box(modifier = Modifier.padding(8.dp).wrapContentHeight(Alignment.Top)) {
    // Call the NativeAdView composable to display the native ad.
    NativeAdView {
      // Inside the NativeAdView composable, display the native ad assets.
      Column(Modifier.align(Alignment.TopStart).wrapContentHeight(Alignment.Top)) {
        // Display the ad attribution.
        NativeAdAttribution(text = context.getString(R.string.attribution))
        Row {
          // If available, display the icon asset.
          nativeAd.icon?.let { icon ->
            NativeAdIconView(Modifier.padding(5.dp)) {
              icon.drawable?.toBitmap()?.let { bitmap ->
                Image(bitmap = bitmap.asImageBitmap(), "Icon")
              }
            }
          }
          Column {
            // If available, display the headline asset.
            nativeAd.headline?.let {
              NativeAdHeadlineView {
                Text(text = it, style = MaterialTheme.typography.headlineLarge)
              }
            }
            // If available, display the star rating asset.
            nativeAd.starRating?.let {
              NativeAdStarRatingView {
                Text(text = "Rated $it", style = MaterialTheme.typography.labelMedium)
              }
            }
          }
        }

        // If available, display the body asset.
        nativeAd.body?.let { NativeAdBodyView { Text(text = it) } }
        // Display the media asset.
        NativeAdMediaView(Modifier.fillMaxWidth().height(500.dp).fillMaxHeight())

        Row(Modifier.align(Alignment.End).padding(5.dp)) {
          // If available, display the price asset.
          nativeAd.price?.let {
            NativeAdPriceView(Modifier.padding(5.dp).align(Alignment.CenterVertically)) {
              Text(text = it)
            }
          }
          // If available, display the store asset.
          nativeAd.store?.let {
            NativeAdStoreView(Modifier.padding(5.dp).align(Alignment.CenterVertically)) {
              Text(text = it)
            }
          }
          // If available, display the call to action asset.
          // Note: The Jetpack Compose button implements a click handler which overrides the native
          // ad click handler, causing issues. Use the NativeAdButton which does not implement a
          // click handler. To handle native ad clicks, use the NativeAd AdListener onAdClicked
          // callback.
          nativeAd.callToAction?.let { callToAction ->
            NativeAdCallToActionView(Modifier.padding(5.dp)) { NativeAdButton(text = callToAction) }
          }
        }
      }
    }
  }
}

Estas são as tarefas individuais:

  1. Inflar o layout

    Java

    LayoutInflater inflater = (LayoutInflater) parent.getContext()
            .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    NativeAdView adView = (NativeAdView) inflater
            .inflate(R.layout.ad_layout_file, parent);
    

    Kotlin

    val inflater = parent.getContext().getSystemService(Context.LAYOUT_INFLATER_SERVICE)
            as LayoutInflater
    val adView = inflater.inflate(R.layout.ad_layout_file, parent) as NativeAdView
    

    Esse código está inflando um layout XML que contém visualizações para mostrar um anúncio nativo e, em seguida, localizando uma referência ao NativeAdView. Também é possível reutilizar um NativeAdView existente se houver um no fragmento ou na atividade, ou criar uma instância dinamicamente sem usar um arquivo de layout.

  2. Preencher e registrar as visualizações de recursos

    Este exemplo de código localiza a visualização usada para mostrar o título, define o texto dela usando o recurso de string fornecido pelo objeto de anúncio e o registra com o objeto NativeAdView:

    Java

    TextView headlineView = adView.findViewById<TextView>(R.id.ad_headline);
    headlineView.setText(ad.getHeadline());
    adView.setHeadlineView(headlineView);
    

    Kotlin

    val headlineView = adView.findViewById<TextView>(R.id.ad_headline)
    headlineView.text = ad.headline
    adView.headlineView = headlineView
    

    Esse processo de localizar a visualização, definir o valor dela e registrar com a classe de visualização de anúncio precisa ser repetido para cada um dos recursos fornecidos pelo objeto de anúncio nativo que o app vai mostrar.

  3. Processar cliques

    Não implemente gerenciadores de cliques personalizados em visualizações sobre ou dentro da visualização de anúncio nativo. Os cliques nos recursos de visualização do anúncio são processados pelo SDK, desde que você preencha e registre corretamente as visualizações de recursos, conforme discutido na seção anterior.

    Para detectar cliques, implemente o callback de clique do SDK dos anúncios para dispositivos móveis do Google:

    Java

    AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/example/native")
        // ...
        .withAdListener(new AdListener() {
            @Override
            public void onAdFailedToLoad(LoadAdError adError) {
                // Handle the failure by logging.
            }
            @Override
            public void onAdClicked() {
                // Log the click event or other custom behavior.
            }
        })
        .build();
    

    Kotlin

    val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
        // ...
        .withAdListener(object : AdListener() {
            override fun onAdFailedToLoad(adError: LoadAdError) {
                // Handle the failure.
            }
            override fun onAdClicked() {
                // Log the click event or other custom behavior.
            }
        })
        .build()
    
  4. Registre o MediaView

    Se você quiser incluir um recurso de imagem principal no layout do seu anúncio nativo, use o recurso MediaView em vez de ImageView.

    O MediaView é um View especial projetado para mostrar o recurso de mídia principal, seja vídeo ou imagem.

    MediaView pode ser definido em um layout XML ou construído dinamicamente. Ela precisa ser colocada na hierarquia de visualização de um NativeAdView, assim como qualquer outra visualização de recurso. Os apps que usam um MediaView precisam registrá-lo com o NativeAdView:

    Java

     // Populate and register the media asset view.
     nativeAdView.setMediaView(nativeAdBinding.adMedia);
    

    Kotlin

     // Populate and register the media asset view.
     nativeAdView.mediaView = nativeAdBinding.adMedia
    

    ImageScaleType

    A classe MediaView tem uma propriedade ImageScaleType ao mostrar imagens. Se você quiser mudar o dimensionamento de uma imagem na MediaView, defina o ImageView.ScaleType correspondente usando o método setImageScaleType() da MediaView:

    Java

    mediaView.setImageScaleType(ImageView.ScaleType.CENTER_CROP);
    

    Kotlin

    mediaView.imageScaleType = ImageView.ScaleType.CENTER_CROP
    

    MediaContent

    A classe MediaContent contém os dados relacionados ao conteúdo de mídia do anúncio nativo, que é mostrado usando a classe MediaView. Quando a propriedade MediaView mediaContent é definida com uma instância MediaContent:

    • Se um recurso de vídeo estiver disponível, ele será armazenado em buffer e começará a ser reproduzido na MediaView. Para saber se um recurso de vídeo está disponível, verifique hasVideoContent().

    • Se o anúncio não tiver um recurso de vídeo, a imagem mainImage será baixada e colocada dentro da MediaView.

    Por padrão, mainImage é o primeiro recurso de imagem baixado. Se setReturnUrlsForImageAssets(true) for usado, mainImage será null e você precisará definir a propriedade mainImage como a imagem baixada manualmente. Essa imagem será usada apenas quando não houver um recurso de vídeo disponível.

  5. Registrar o objeto de anúncio nativo

    Esta etapa final registra o objeto de anúncio nativo com a visualização responsável por mostrá-lo.

    Java

    adView.setNativeAd(ad);
    

    Kotlin

    adView.setNativeAd(ad)
    

Destruir um anúncio

Depois de mostrar um anúncio nativo, destrua-o. O exemplo a seguir destrói um anúncio nativo:

Java

nativeAd.destroy();

Kotlin

nativeAd.destroy()

Testar o código de anúncio nativo

Anúncios de vendas diretas

Se você tiver interesse em testar anúncios nativos de vendas diretas, use este ID de bloco de anúncios do Ad Manager:

/21775744923/example/native

Ele foi configurado para veicular amostras de anúncios de instalação do app e de conteúdo, além de um formato de anúncio nativo personalizado com os seguintes recursos:

  • Título (texto)
  • MainImage (imagem)
  • Legenda (texto)

O ID do modelo para o formato de anúncio nativo personalizado é 10063170.

Anúncios de preenchimento nativo

O backfill da Ad Exchange está disponível apenas para um grupo selecionado de editores. Para testar o comportamento de anúncios de preenchimento nativos, use este bloco de anúncios do Ad Manager:

/21775744923/example/native-backfill

Ele exibe amostras de anúncios de instalação do app e de conteúdo que incluem a sobreposição das Opções de Anúncios.

Atualize seu código para que ele consulte os reais IDs de modelo e do bloco de anúncios antes de ser executado.

Exemplos no GitHub

Exemplo de implementação completa de anúncios nativos:

Java Kotlin JetpackCompose

Próximas etapas

Confira os seguintes tópicos: