Anúncios nativos

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

Os anúncios nativos aprimoram a experiência geral de exibição dos anúncios, permitindo que você mostre mais anúncios sem perder o engajamento dos usuários. A longo prazo, isso lhe permite maximizar as receitas publicitárias.

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. Primeiro, é preciso inicializar o SDK de publicidade.
3. Certifique-se de possuir a última Yandex Mobile Ads SDK versão. Se estiver usando mediação, atualize para a single build mais recente.

Implementação

Principais passos para integrar anúncios nativos:

• Crie e configure um 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 componente MediaView devem ter pelo menos 300 × 160 dp (píxeis independente de densidade).

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

Regras para renderizar anúncios intersticiais nativos

1. A zona de segurança não clicável superior tem altura de 80 dp. Os controles no interior dessa zona podem ser clicáveis.

2. Os elementos visuais (ativos) devem ter tamanho mínimo de 32 × 32 dp. Isso inclui o botão Fechar e os demais ícones.

3. A área clicável em torno dos ativos deve ser de pelo menos 64 × 64 dp. Por exemplo, se um ativo tem dimensões de 32 × 32 dp, o espaçamento em torno dele deve garantir que a área clicável total seja de 64 × 64 dp.

4. Se um controle aparecer com atraso, você deve exibir um timer ou uma barra de progresso até o elemento carregar.

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 AdRequest.Builder. É possível aumentar a relevância dos anúncios informando parâmetros como a ID do bloco de anúncio, o método de carregamento da imagem e outros dados pertinentes nos parâmetros de solicitação. Para saber mais, consulte Segmentação de anúncios.

Para receber notificações sobre os resultados do carregamento de anúncios, crie uma instância de NativeAdLoadListener e informe-a para o método loadAd().

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 = NativeAdLoader(this)
      nativeAdLoader?.loadAd(
          // Métodos da classe AdRequest.Builder podem ser usados aqui para especificar configurações individuais de opções.
          AdRequest.Builder("your-ad-unit-id").build(),
          object : NativeAdLoadListener {
              override fun onAdLoaded(p0: NativeAd) {
                  // O anúncio foi carregado com sucesso. Agora você pode exibir o anúncio carregado.
              }

              override fun onAdFailedToLoad(p0: AdRequestError) {
                  // O anúncio não carregou, com AdRequestError.
                  // Tentar carregar outro anúncio a partir do método onAdFailedToLoad() é fortemente desencorajado.
              }
          })
  }
}

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 = new NativeAdLoader(this);
      // Métodos da classe AdRequest.Builder podem ser usados aqui para especificar configurações individuais de opções.
      mNativeAdLoader.loadAd(
              new AdRequest.Builder("your-ad-unit-id").build(),
              new NativeAdLoadListener() {
                  @Override
                  public void onAdLoaded(@NonNull final NativeAd nativeAd) {
                      // O anúncio foi carregado com sucesso. Agora você pode exibir o anúncio carregado.
                  }

                  @Override
                  public void onAdFailedToLoad(@NonNull final AdRequestError error) {
                      // O anúncio não carregou, com AdRequestError.
                      // Tentar carregar outro anúncio a partir do método onAdFailedToLoad() é fortemente desencorajado.
                  }
              }
      );
  }
}

Caso você veicule anúncios através do Adfox, após a resposta do anúncio em banner, os dados campaignId, bannerId e placeId poderão ser acessados a partir dos objetos NativeAd ou BannerAdView usando a propriedade adAttributes do tipo AdAttributes.

Renderizaçã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.

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

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()
    }

    when (val result = nativeAd.bindNativeAd(nativeAdViewBinder))
    {
        is AdBindingResult.Failure -> {
            Logger.error(result.exception.message.orEmpty())
        }
        AdBindingResult.Success -> {
            nativeAd.setNativeAdEventListener(NativeAdEventLogger())
        }
    }
}

private inner class NativeAdEventLogger : NativeAdEventListener {

    override fun onAdClicked() {
        // Convocado quando há o registro de clique em um anúncio.
    }

    override fun onImpression(data: ImpressionData?) {
        // Convocado quando há o registro de impressão de um anúncio.
    }
}

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();
    AdBindingResult result = nativeAd.bindNativeAd(nativeAdViewBinder);
    if (result instanceof AdBindingResult.Failure) {
        Log.e("TAG", ((AdBindingResult.Failure) result).getException().getMessage());
    } else {
        nativeAd.setNativeAdEventListener(new CustomNativeAdActivity.NativeAdEventLogger());
    }
}

private class NativeAdEventLogger implements NativeAdEventListener {
    @Override
    public void onAdClicked() {
        // Convocado quando há o registro de clique em um anúncio.
    }

    @Override
    public void onImpression(@Nullable ImpressionData data) {
        // Convocado quando há o registro de impressão de um anúncio.
    }
}

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 = NativeBulkAdLoader(this)
        // Métodos da classe AdRequest.Builder podem ser usados aqui para especificar configurações individuais de opções.
        nativeAdsLoader?.loadAds(
            AdRequest.Builder("your-ad-unit-id").build(),
            3,
            object : NativeBulkAdLoadListener {
                override fun onAdsLoaded(p0: MutableList<NativeAd>) {
                    // O anúncio foi carregado com sucesso. Agora você pode exibir o anúncio carregado.
                    for (nativeAd in p0) {
                        showAd(nativeAd)
                    }
                }

                override fun onAdsFailedToLoad(p0: AdRequestError) {
                    // O anúncio não carregou, com AdRequestError.
                    // Tentar carregar outro anúncio a partir do método onAdFailedToLoad() é fortemente desencorajado.
                }
            })
    }
}

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 = new NativeBulkAdLoader(this);
        // Métodos da classe AdRequest.Builder podem ser usados aqui para especificar configurações individuais de opções.
        mNativeAdsLoader.loadAds(
                new AdRequest.Builder("your-ad-unit-id").build(),
                3,
                new NativeBulkAdLoadListener() {
                    @Override
                    public void onAdsLoaded(@NonNull final List<NativeAd> list) {
                        // O anúncio foi carregado com sucesso. Agora você pode exibir o anúncio carregado.
                    }

                    @Override
                    public void onAdsFailedToLoad(@NonNull final AdRequestError error) {
                        // O anúncio não carregou, com AdRequestError.
                        // Tentar carregar outro anúncio a partir do método onAdFailedToLoad() é fortemente desencorajado.
                    }
                }
        );
    }
}

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 de adUnitId para anúncios combinatórios: 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:

YandexAds.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:

YandexAds.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>