Anúncios nativos

Publicidade nativa é um tipo de anúncio em que o layout pode ser definido no lado do aplicativo. Esta funcionalidade permite alterar o estilo visual dos anúncios e seu posicionamento, considerando as especificidades do design do aplicativo.

Anúncios nativos melhoram a experiência com anúncios. Como resultado, você pode exibir mais anúncios sem que o usuário perca o interesse. Isso garante a máxima receita de publicidade a longo prazo.

A renderização de anúncios é realizada com ferramentas nativas da plataforma, o que melhora o desempenho e a qualidade dos anúncios.

Aparência

Este guia abrange o processo de integração de anúncios nativos em aplicativos Android. Além de exemplos de código e instruções, contém recomendações específicas aos formatos e links para recursos adicionais.

Pré-requisito

1. Siga os passos de integração do SDK descritos em Início rápido.
2. Inicialize seu SDK de anúncios com antecedência.
3. Confirme se você está utilizando a última versão do Yandex Mobile Ads SDK. Se você estiver usando mediação, confirme se também está utilizando a última versão da compilação unificada.

Implementação

Principais passos para integrar anúncios nativos:

• Criar e configurar um carregador de anúncios chamado NativeAdLoader.
• Registrar um listener de eventos de carregamento de anúncios.
• Carregar o anúncio.
• Renderizar o anúncio carregado.

Especificidades da integração de anúncios nativos

1. Todas as chamadas para métodos do Yandex Mobile Ads SDK devem ser feitas a partir do thread principal.

2. Se o onAdFailedToLoad() callback retornar um erro, não tente carregar um novo anúncio novamente. Se não houver outra opção, limite o número de tentativas de carregamento de anúncios. Isso ajudará a evitar solicitações constantes malsucedidas e problemas de conexão se houver limitações.

3. Recomendamos manter uma referência forte ao anúncio e seu carregador durante todo o ciclo de vida da tela na qual ocorre a interação com o anúncio.

4. O tamanho do contêiner do anúncio deve ser baseado no conteúdo do anúncio. Após o anúncio terminar de carregar, você precisa renderizar todos os seus ativos. Você pode obter a lista de ativos de anúncios disponíveis a partir do objeto de publicidade NativeAd.

5. Geralmente, anúncios em vídeo produzem os melhores resultados. Para exibir anúncios em vídeo, o tamanho do contêiner do anúncio e o ativo MediaView devem ter pelo menos 300 × 160 dp (pixels de densidade independente).

6. Recomendamos usar um layout que inclua todos os ativos possíveis. Na prática, esses layouts resultam em taxas de conversão mais altas.

Carregamento de anúncios

Para carregar seus anúncios nativos, crie um objeto NativeAdLoader.

Os parâmetros de solicitação de anúncios são configurados através do objeto da classe NativeAdRequestConfiguration.Builder. Nos parâmetros de solicitação, você pode passar o ID do bloco de anúncios, o método de carregamento de imagem, idade, atributos de gênero e outros dados que podem deixar as impressões mais relevantes. Saiba mais na seção Segmentação de anúncios.

Para receber notificações sobre os resultados do carregamento de anúncios, crie uma instância de NativeAdLoadListener e defina-a como um listener de eventos do carregador de anúncios.

Para carregar o anúncio, chame o método loadAd().

O exemplo abaixo mostra como carregar anúncios nativos a partir de Activity:

class CustomNativeAdActivity : AppCompatActivity(R.layout.activity_custom_native_ad) {

  private val nativeAdView get() = binding.nativeAd.root

  private var nativeAdLoader: NativeAdLoader? = null

  private lateinit var binding: ActivityCustomNativeAdBinding

  override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      binding = ActivityCustomNativeAdBinding.inflate(layoutInflater)
      setContentView(binding.root)

      nativeAdLoader = createNativeAdLoader()
      nativeAdLoader?.loadAd(
          // Methods in the NativeAdRequestConfiguration.Builder class can be used here to specify individual options settings.
          NativeAdRequestConfiguration.Builder("your-ad-unit-id").build())
  }

  private fun createNativeAdLoader(): NativeAdLoader {
      return nativeAdLoader ?: NativeAdLoader(this).apply {
          setNativeAdLoadListener(object : NativeAdLoadListener {
              override fun onAdLoaded(p0: NativeAd) {
                  // The ad was loaded successfully. Now you can show the loaded ad.
              }

              override fun onAdFailedToLoad(p0: AdRequestError) {
                  // Ad failed to load with AdRequestError.
                  // Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged.
              }
          })
      }
  }
}

class CustomNativeAdActivity extends AppCompatActivity {
  private NativeAdView mNativeAdView = mBinding.nativeAd.getRoot();

  @Nullable private NativeAdLoader mNativeAdLoader = null;

  private ActivityCustomNativeAdBinding mBinding;

  @Override
  public void onCreate(@Nullable Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      mBinding = ActivityCustomNativeAdBinding.inflate(getLayoutInflater());
      setContentView(mBinding.getRoot());

      mNativeAdLoader = createNativeAdLoader();
      if (mNativeAdLoader != null) {
          // Methods in the NativeAdRequestConfiguration.Builder class can be used here to specify individual options settings.
          mNativeAdLoader.loadAd(
                  new NativeAdRequestConfiguration.Builder("your-ad-unit-id").build()
          );
      }
  }

  private NativeAdLoader createNativeAdLoader() {
      if (mNativeAdLoader != null) {
          return mNativeAdLoader;
      }

      final NativeAdLoader newNativeAdLoader = new NativeAdLoader(this);
      newNativeAdLoader.setNativeAdLoadListener(new NativeAdLoadListener() {
          @Override
          public void onAdLoaded(@NonNull final NativeAd nativeAd) {
              // The ad was loaded successfully. Now you can show the loaded ad.
          }

          @Override
          public void onAdFailedToLoad(@NonNull final AdRequestError error) {
              // Ad failed to load with AdRequestError.
              // Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged.
          }
      });
      return newNativeAdLoader;
  }
}

Exibição de anúncios

Após o anúncio terminar de carregar, você precisa renderizar todos os seus ativos. Você pode obter a lista de ativos de anúncios disponíveis a partir do objeto de publicidade NativeAd.

Existem duas maneiras de configurar o layout de um anúncio:

• Layout baseado em modelo.
• Configuração manual do layout de anúncios nativos.

Layout baseado em modelo

O layout de modelo padrão é a maneira mais simples de trabalhar com anúncios nativos, e você precisará de apenas algumas linhas de código para configurar a variante básica.

O modelo já inclui um conjunto completo de ativos de anúncios necessários e define o posicionamento relativo deles. O modelo é compatível com qualquer tipo de anúncio nativo permitido.

private fun showAd(nativeAd: NativeAd) {
   nativeAd.setNativeAdEventListener(NativeAdEventLogger())
   binding.nativeBanner.setAd(nativeAd)
}

private inner class NativeAdEventLogger : NativeAdEventListener {
    override fun onAdClicked() {
       // Called when a click is recorded for an ad.
    }

    override fun onLeftApplication() {
        // Called when the user is about to leave the application (e.g., to go to the browser), as a result of clicking on the ad.
    }

    override fun onReturnedToApplication() {
        // Called when the user returns to the application after a click.
    }

    override fun onImpression(data: ImpressionData?) {
        // Called when an impression is recorded for an ad.
    }
}

private void showAd(@NonNull final NativeAd nativeAd) {
    nativeAd.setNativeAdEventListener(new NativeAdEventLogger());
    mBinding.nativeBanner.setAd(nativeAd);
}

private static class NativeAdEventLogger implements NativeAdEventListener {
    @Override
    public void onAdClicked() {
        //  Called when a click is recorded for an ad.
    }

    @Override
    public void onLeftApplication() {
        // Called when the user is about to leave the application (e.g., to go to the browser), as a result of clicking on the ad.
    }

    @Override
    public void onReturnedToApplication() {
        // Called when the user returns to the application after a click.
    }

    @Override
    public void onImpression(@Nullable ImpressionData impressionData) {
        // Called when an impression is recorded for an ad.
    }
}

O modelo de anúncio nativo pode ser personalizado. Para saber mais, veja Configuração do layout usando um modelo.

Configuração manual do layout de anúncios nativos

Se o modelo não atender às suas necessidades, você pode configurar o layout dos seus anúncios nativos manualmente.

Este método permite criar um layout personalizado para seus anúncios nativos e definir o posicionamento relativo entre eles. O anúncio pode incluir ativos obrigatórios e opcionais para exibição. Veja a lista completa em Ativos de anúncios nativos.

Para cada ativo de anúncio, forneça uma View através de uma instância da classe NativeAdViewBinder.Builder. A classe recebe o contêiner NativeAdView como argumento. Você deve definir todos os ativos de anúncio como subview desse contêiner.

Vincule o layout de anúncio pronto parar uso ao objeto NativeAd.

private fun showAd(nativeAd: NativeAd) {
    val nativeAdViewBinder = binding.nativeAd.run {
        NativeAdViewBinder.Builder(nativeAdView)
            .setAgeView(age)
            .setBodyView(body)
            .setCallToActionView(callToAction)
            .setDomainView(domain)
            .setFaviconView(favicon)
            .setFeedbackView(feedback)
            .setIconView(icon)
            .setMediaView(media)
            .setPriceView(price)
            .setRatingView(rating)
            .setReviewCountView(reviewCount)
            .setSponsoredView(sponsored)
            .setTitleView(title)
            .setWarningView(warning)
            .build()
    }

    try {
        nativeAd.bindNativeAd(nativeAdViewBinder)
        nativeAd.setNativeAdEventListener(NativeAdEventLogger())
    } catch (exception: NativeAdException) {
        Logger.error(exception.message.orEmpty())
    }
}

private inner class NativeAdEventLogger : NativeAdEventListener {

    override fun onAdClicked() {
        // Called when a click is recorded for an ad.
    }

    override fun onLeftApplication() {
        // Called when the user is about to leave the application (e.g., to go to the browser), as a result of clicking on the ad.
    }

    override fun onReturnedToApplication() {
        // Called when the user returns to the application after a click.
    }

    override fun onImpression(data: ImpressionData?) {
        // Called when an impression is recorded for an ad.
    }
}

private void showAd(@NonNull final NativeAd nativeAd) {
    final NativeAdViewBinder nativeAdViewBinder = new NativeAdViewBinder.Builder(mNativeAdView)
            .setAgeView(age)
            .setBodyView(body)
            .setCallToActionView(callToAction)
            .setDomainView(domain)
            .setFaviconView(favicon)
            .setFeedbackView(feedback)
            .setIconView(icon)
            .setMediaView(media)
            .setPriceView(price)
            .setRatingView(rating)
            .setReviewCountView(reviewCount)
            .setSponsoredView(sponsored)
            .setTitleView(title)
            .setWarningView(warning)
            .build();
    try {
        nativeAd.bindNativeAd(nativeAdViewBinder);
        nativeAd.setNativeAdEventListener(new CustomNativeAdActivity.NativeAdEventLogger());
    } catch (final NativeAdException exception) {
        Log.e("TAG", exception.getMessage());
    }
}

private class NativeAdEventLogger implements NativeAdEventListener {
    @Override
    public void onAdClicked() {
        // Called when a click is recorded for an ad.
    }

    @Override
    public void onLeftApplication() {
        // Called when the user is about to leave the application (e.g., to go to the browser), as a result of clicking on the ad.
    }

    @Override
    public void onReturnedToApplication() {
        // Called when the user returns to the application after a click.
    }

    @Override
    public void onImpression(@Nullable ImpressionData data) {
        // Called when an impression is recorded for an ad.
    }
}

Carregamento de vários anúncios

O Yandex Mobile Ads SDK oferece a opção de carregar vários anúncios em uma única solicitação (até nove anúncios).

Para fazer uma solicitação de anúncios em massa, use uma instância da classe NativeBulkAdLoader. Ela recebe o argumento count no método loadAds, que identifica o número desejado de anúncios por solicitação.

class NativeBulkAdLoaderActivity : AppCompatActivity(R.layout.activity_custom_native_ad) {

    private val nativeAdView get() = binding.nativeAd.root

    private var nativeAdsLoader: NativeBulkAdLoader? = null

    private lateinit var binding: ActivityCustomNativeAdBinding

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = ActivityCustomNativeAdBinding.inflate(layoutInflater)
        setContentView(binding.root)

        nativeAdsLoader = createNativeBulkAdLoader()
        // Methods in the NativeAdRequestConfiguration.Builder class can be used here to specify individual options settings.
        val adRequestConfiguration = NativeAdRequestConfiguration.Builder("your-ad-unit-id").build()
        nativeAdsLoader?.loadAds(adRequestConfiguration, 3)
    }

    private fun createNativeBulkAdLoader(): NativeBulkAdLoader {
        return nativeAdsLoader ?: NativeBulkAdLoader(this).apply {
            setNativeBulkAdLoadListener(object : NativeBulkAdLoadListener {
                override fun onAdsLoaded(p0: MutableList<NativeAd>) {
                    // The ads were loaded successfully. Now you can show the loaded ads.
                    for (nativeAd in p0) {
                        showAd(nativeAd)
                    }
                }

                override fun onAdsFailedToLoad(p0: AdRequestError) {
                    // Ad failed to load with AdRequestError.
                    // Attempting to load new ads from the onAdFailedToLoad() method is strongly discouraged.
                }
            })
        }
    }
}

class CustomBulkNativeAdActivity extends AppCompatActivity {
    private NativeAdView mNativeAdView = mBinding.nativeAd.getRoot();

    @Nullable private NativeBulkAdLoader mNativeAdsLoader = null;

    private ActivityCustomNativeAdBinding mBinding;

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        mBinding = ActivityCustomNativeAdBinding.inflate(getLayoutInflater());
        setContentView(mBinding.getRoot());

        mNativeAdsLoader = createNativeBulkAdLoader();
        if (mNativeAdsLoader != null) {
            // Methods in the NativeAdRequestConfiguration.Builder class can be used here to specify individual options settings.
            mNativeAdsLoader.loadAds(
                    new NativeAdRequestConfiguration.Builder("your-ad-unit-id").build();
            );
        }
    }

    private NativeBulkAdLoader createNativeBulkAdLoader() {
        if (mNativeAdsLoader != null) {
            return mNativeAdsLoader;
        }

        final NativeBulkAdLoader newNativeBulkAdLoader = new NativeBulkAdLoader(this);

        newNativeBulkAdLoader.setNativeBulkAdLoadListener(new NativeBulkAdLoadListener() {
            @Override
            public void onAdsLoaded(@NonNull final List<NativeAd> list) {
                // The ad was loaded successfully. Now you can show the loaded ad.
            }

            @Override
            public void onAdsFailedToLoad(@NonNull final AdRequestError error) {
                // Ad failed to load with AdRequestError.
                // Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged.
            }
        });
        return newNativeBulkAdLoader;
    }
}

Teste da integração de anúncios nativos

Uso de blocos de anúncios de demonstração para teste de anúncios

Use anúncios de teste para verificar sua integração de anúncios nativos e o próprio aplicativo.

Para garantir que anúncios de teste sejam retornados para cada solicitação de anúncio, criamos um ID especial de posicionamento de anúncios de demonstração para ajudar você a testar sua integração de anúncios.

Demonstração adUnitId para anúncios de texto e imagem: demo-native-content-yandex.

Demonstração adUnitId para anúncios de aplicativos móveis: demo-native-app-yandex.

Teste da integração de anúncios

Você pode verificar se seus anúncios nativos estão integrados corretamente usando o analisador integrado do SDK.

Essa ferramenta verifica se os anúncios nativos estão ativados corretamente e gera um relatório detalhado em um arquivo de log. Para visualizar o relatório, faça uma busca pela palavra-chave "YandexAds" no Logcat, uma ferramenta para depuração de aplicativos Android.

adb logcat -v brief '*:S YandexAds'

Se a integração for bem-sucedida, a seguinte mensagem será retornada:

adb logcat -v brief '*:S YandexAds'
mobileads$ adb logcat -v brief '*:S YandexAds'
I/YandexAds(13719): [Integration] Ad type native was integrated successfully

Se houver algum problema na integração de anúncios nativos, você receberá um relatório detalhado do problema e recomendações de diagnóstico e solução.

Indicador de integração correta de anúncios nativos

Usando este indicador, você pode descobrir se a integração de anúncios nativos foi bem-sucedida. Case não tenha sido, você pode obter informações de depuração que descrevem a causa do problema.

Para ativar a exibição do indicador no modo de depuração, chame o método enableDebugErrorIndicator configurado para true:

MobileAds.enableDebugErrorIndicator(true)

Integração bem-sucedida

Integração com erros

Se a integração foi bem-sucedida, uma borda verde-clara será exibida sobre o anúncio no modo de depuração.

Se houver um erro na integração de anúncios nativos, o indicador será exibido sobre o anúncio no modo de depuração. Clique no indicador para ver a mensagem de depuração, que deve indicar a causa raiz do problema. Ao clicar novamente no indicador, a mensagem é ocultada.

Para desativar a exibição do indicador no modo de depuração, chame o método enableDebugErrorIndicator configurado para false:

MobileAds.enableDebugErrorIndicator(false)

Aceleração de hardware para anúncios em vídeo

Para garantir que os anúncios em vídeo sejam reproduzidos corretamente na tela do seu aplicativo, a aceleração de hardware deve estar ativada (saiba mais na documentação).

Por padrão, a aceleração de hardware está ativada. Se você desativou a aceleração de hardware no seu aplicativo, precisa ativá-la na tela do aplicativo na qual os anúncios são exibidos.

<application android:hardwareAccelerated="true">
    <!-- For activities that use ads, hardwareAcceleration should be true. -->
    <activity android:hardwareAccelerated="true" />
</application>