Banner adaptativo inline

Um banner adaptativo inline é um formato flexível de anúncio em banner que otimiza o tamanho do anúncio em cada dispositivo, garantindo máxima eficiência.

Com esse tipo de anúncio, os desenvolvedores podem definir a largura e a altura máximas permitidas para o anúncio, deixando o sistema determinar o tamanho ideal automaticamente. Para escolher o melhor tamanho de anúncio, os banners adaptativos inline utilizam uma altura máxima, e não uma altura fixa. Isso ajuda a melhorar o desempenho.

Normalmente, esse formato é usado em aplicativos baseados em feed ou contextos em que é aceitável focar principalmente no anúncio.

Aparência

Este guia aborda o processo para integrar banners adaptativos inline 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 banners adaptativos inline:

  • Criar e configurar uma visualização para exibir anúncios em banner.
  • Registrar um listener de método de callback.
  • Carregar o anúncio.
  • Passar configurações adicionais se você estiver usando Adfox.

Especificidades da integração de banner adaptativo inline

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

  2. Para que os anúncios em vídeo sejam exibidos com sucesso na tela do seu aplicativo, a aceleração de hardware deve estar habilitada. Por padrão, a aceleração de hardware estará habilitada, mas alguns aplicativos podem acabar a desabilitando. Se isso se aplicar ao seu aplicativo, recomendamos ativar a aceleração de hardware para as classes de atividade que usam anúncios.

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

  4. Para que os banners adaptativos inline funcionem corretamente, torne os layouts do seu app adaptativos. Caso contrário, seus anúncios podem ser renderizados incorretamente.

  5. Os banners adaptativos inline funcionam melhor quando utilizam toda a largura disponível da tela. Na maioria dos casos, será a largura total da tela do dispositivo. Você precisa considerar os parâmetros de margem definidos no seu aplicativo e a área segura de exibição.

  6. Os banners adaptativos inline foram projetados para uso em conteúdo rolável. Ele pode ter a mesma altura que a tela do dispositivo ou ser limitado à altura máxima, dependendo da API.

  7. Para obter o tamanho do anúncio, use o método BannerAdSize.inline(context, adWidth, maxAdHeight), que aceita como argumentos o contexto, a largura disponível do contêiner do anúncio e a altura máxima aceitável do anúncio.

  8. O objeto BannerAdSize, calculado usando o método BannerAdSize.inline(context, adWidth, maxAdHeight), contém dados técnicos para selecionar os tamanhos de anúncio mais eficazes no backend. A altura do anúncio pode mudar toda vez que é carregado. A largura e altura reais do anúncio ficam disponíveis após o recebimento de uma mensagem de carregamento de anúncio bem-sucedido.

  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.

Por exemplo

Adição de uma visualização de anúncio ao layout do aplicativo

Para exibir anúncios em banner, você precisa adicionar BannerAdView ao layout do aplicativo. Você pode fazer isso programaticamente ou usando um arquivo XML.

Exemplo de adição de BannerAdView ao layout da tela do aplicativo:

# activity.xml
...
<com.yandex.mobile.ads.banner.BannerAdView
        android:id="@+id/ad_container_view"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />
...

Também é possível criar uma instância de BannerAdView programaticamente:

val bannerAd = BannerAdView(this)

final BannerAdView bannerAd = new BannerAdView(this);

Carregamento e renderização de anúncios

Após criar e adicionar BannerAdView à tela do aplicativo, é necessário carregar os anúncios. Antes de carregar um banner adaptativo inline, calcule o tamanho do anúncio em cada dispositivo.

Isso é feito automaticamente por meio do método da API do SDK: BannerAdSize.inline(context, adWidth, maxAdHeight). Passe o contexto, a largura disponível do contêiner do anúncio e a altura máxima aceitável do anúncio como argumentos. Os banners adaptativos inline funcionam melhor quando utilizam toda a largura disponível da tela. Na maioria dos casos, será a largura total da tela do dispositivo. Você precisa considerar os parâmetros de margem definidos no seu aplicativo e a área segura de exibição:

private val adSize: BannerAdSize
    get() {
        val screenHeight = resources.displayMetrics.run { heightPixels / density }.roundToInt()
        // Calcule a largura do anúncio, levando em conta o padding do contêiner do anúncio.
        var adWidthPixels = binding.adContainerView.width
        if (adWidthPixels == 0) {
            // Se o anúncio não tiver sido posicionado, use como padrão a largura de tela cheia
            adWidthPixels = resources.displayMetrics.widthPixels
        }
        val adWidth = (adWidthPixels / resources.displayMetrics.density).roundToInt()
        val maxAdHeight = screenHeight / 2

        return BannerAdSize.inline(context, adWidth, maxAdHeight)
    }

@NonNull
private BannerAdSize getAdSize() {
    final DisplayMetrics displayMetrics = getResources().getDisplayMetrics();
    final int screenHeight = Math.round(displayMetrics.heightPixels / displayMetrics.density);
    // Calcule a largura do anúncio, levando em conta o padding do contêiner do anúncio.
    int adWidthPixels = mBinding.adContainerView.getWidth();
    if (adWidthPixels == 0) {
        // Se o anúncio não tiver sido posicionado, use como padrão a largura de tela cheia
        adWidthPixels = displayMetrics.widthPixels;
    }
    final int adWidth = Math.round(adWidthPixels / displayMetrics.density);
    // Determine a altura máxima permitida para o anúncio. O valor atual é dado como exemplo.
    final int maxAdHeight = screenHeight / 2;

    return BannerAdSize.inline(this, adWidth, maxAdHeight);
}

Para carregar anúncios, você também precisa do contexto de Atividade e da ID do bloco de anúncio (adUnitId) obtido na interface Yandex Advertising Network.

Para ativar notificações quando anúncios são carregados ou deixam de ser carregados e rastrear os eventos do ciclo de vida de um banner adaptativo inline, defina o ouvinte de callback BannerAdEventListener para a instância da classe BannerAdView.

É possível ampliar os parâmetros de solicitação de anúncios com a classe AdRequest.Builder() para incluir na solicitação de anúncio informações sobre interesses do usuário, contexto da página, localização e outros dados adicionais. O acréscimo de mais contexto às solicitações de anúncios pode melhorar a qualidade dos anúncios consideravelmente. Para saber mais, consulte Segmentação de anúncios.

O exemplo a seguir mostra como carregar um banner adaptativo inline. Após o carregamento bem-sucedido, o banner será exibido automaticamente:

class AdaptiveInlineBannerAdActivity : AppCompatActivity(R.layout.activity_inline_banner_ad) {
    private var bannerAd: BannerAdView? = null
    private lateinit var binding: ActivityInlineBannerAdBinding

    private val adSize: BannerAdSize
        get() {
            val screenHeight = resources.displayMetrics.run { heightPixels / density }.roundToInt()
            // Calcule a largura do anúncio, levando em conta o padding do contêiner do anúncio.
            var adWidthPixels = binding.adContainerView.width
            if (adWidthPixels == 0) {
                // Se o anúncio não tiver sido posicionado, use como padrão a largura de tela cheia
                adWidthPixels = resources.displayMetrics.widthPixels
            }
            val adWidth = (adWidthPixels / resources.displayMetrics.density).roundToInt()
            // Determine a altura máxima permitida para o anúncio. O valor atual é dado como exemplo.
            val maxAdHeight = screenHeight / 2

            return BannerAdSize.inline(context, adWidth, maxAdHeight)
        }

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

        // Como estamos carregando o banner com base no tamanho do adContainerView,
        // precisamos esperar até que esta exibição seja renderizada antes de obtermos a largura
        binding.adContainerView.viewTreeObserver.addOnGlobalLayoutListener(object :
            ViewTreeObserver.OnGlobalLayoutListener {
            override fun onGlobalLayout() {
                binding.adContainerView.viewTreeObserver.removeOnGlobalLayoutListener(this);
                bannerAd = loadBannerAd(adSize)
            }
        })
    }

    private fun loadBannerAd(adSize: BannerAdSize): BannerAdView {
        return binding.banner.apply {
            setAdSize(adSize)
            setBannerAdEventListener(object : BannerAdEventListener {
                override fun onAdLoaded() {
                    // Se esse callback ocorrer após a atividade ser destruída, você
                    // deve convocar destroy e retornar, para não arriscar um vazamento de memória.
                    // Observe que isDestroyed é um método de Activity.
                    if (isDestroyed) {
                        bannerAd?.destroy()
                        return
                    }
                }

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

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

                override fun onImpression(impressionData: ImpressionData?) {
                    // Convocado quando há o registro de impressão de um anúncio.
                }
            })
            loadAd(
                AdRequest.Builder("your-ad-unit-id")
                    // Métodos da classe AdRequest.Builder podem ser usados aqui para especificar configurações individuais de opções.
                    .build()
            )
        }
    }
}

public class AdaptiveInlineBannerAdActivity extends AppCompatActivity {
    @Nullable
    private BannerAdView mBannerAd = null;
    private ActivityInlineBannerAdBinding mBinding;

    public AdaptiveInlineBannerAdActivity() {
        super(R.layout.activity_inline_banner_ad);
    }

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

        // Como estamos carregando o banner com base no tamanho do adContainerView,
        // precisamos esperar até que esta exibição seja renderizada antes de obtermos a largura
        mBinding.adContainerView.getViewTreeObserver().addOnGlobalLayoutListener(
                new ViewTreeObserver.OnGlobalLayoutListener() {
                    @Override
                    public void onGlobalLayout() {
                        mBinding.adContainerView.getViewTreeObserver().removeOnGlobalLayoutListener(this);
                        mBannerAd = loadBannerAd(getAdSize());
                    }
                }
        );
    }

    @NonNull
    private BannerAdSize getAdSize() {
        final DisplayMetrics displayMetrics = getResources().getDisplayMetrics();
        final int screenHeight = Math.round(displayMetrics.heightPixels / displayMetrics.density);
        // Calcule a largura do anúncio, levando em conta o padding do contêiner do anúncio.
        int adWidthPixels = mBinding.adContainerView.getWidth();
        if (adWidthPixels == 0) {
            // Se o anúncio não tiver sido posicionado, use como padrão a largura de tela cheia
            adWidthPixels = displayMetrics.widthPixels;
        }
        final int adWidth = Math.round(adWidthPixels / displayMetrics.density);
        // Determine a altura máxima permitida para o anúncio. O valor atual é dado como exemplo.
        final int maxAdHeight = screenHeight / 2;

        return BannerAdSize.inline(this, adWidth, maxAdHeight);
    }

    @NonNull
    private BannerAdView loadBannerAd(@NonNull final BannerAdSize adSize) {
        final BannerAdView bannerAd = mBinding.banner;
        bannerAd.setAdSize(adSize);
        bannerAd.setBannerAdEventListener(new BannerAdEventListener(){
            @Override
            public void onAdLoaded() {
                // Se esse callback ocorrer após a atividade ser destruída, você
                // deve convocar destroy e retornar, para não arriscar um vazamento de memória.
                // Observe que isDestroyed é um método de Activity.
                if (isDestroyed() && mBannerAd != null) {
                    mBannerAd.destroy();
                }
            }

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

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

            @Override
            public void onImpression(@Nullable ImpressionData impressionData) {
                // Convocado quando há o registro de impressão de um anúncio.
            }
        });
        final AdRequest adRequest = new AdRequest.Builder("your-ad-unit-id")
                // Métodos da classe AdRequest.Builder podem ser usados aqui para especificar configurações individuais de opções.
                .build();
        bannerAd.loadAd(adRequest);
        return bannerAd;
    }
}

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 BannerAdView usando a propriedade adAttributes do tipo AdAttributes.

Liberação de recursos

Se um callback ocorrer após a destruição da atividade, chame a função destroy() para o objeto anúncio utilizado, para liberar os recursos:

private fun loadBannerAd(adSize: BannerAdSize): BannerAdView {
    return binding.banner.apply {
        setBannerAdEventListener(object : BannerAdEventListener {
            override fun onAdLoaded() {
                // Se esse callback ocorrer após a atividade ser destruída, você
                // deve convocar destroy e retornar, para não arriscar um vazamento de memória.
                // Observe que isDestroyed é um método de Activity.
                if (isDestroyed) {
                    bannerAd?.destroy()
                    return
                }
            }
            ...
        })
        ...
    }
}

@NonNull
private BannerAdView loadBannerAd(@NonNull final BannerAdSize adSize) {
    final BannerAdView bannerAd = mBinding.banner;
    bannerAd.setBannerAdEventListener(new BannerAdEventListener() {
        @Override
        public void onAdLoaded() {
            // Se esse callback ocorrer após a atividade ser destruída, você
            // deve convocar destroy e retornar, para não arriscar um vazamento de memória.
            // Observe que isDestroyed é um método de Activity.
            if (isDestroyed() && mBannerAd != null) {
                mBannerAd.destroy();
            }
        }
        ...
    });
    ...
    return bannerAd;
}

Teste da integração do banner adaptativo inline

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

Use anúncios-teste para verificar a integração dos banners adaptativos inline e o aplicativo em si. Para garantir que os anúncios-teste sejam retornados para cada solicitação de anúncio, é possível usar uma ID especial de posicionamento de anúncios demonstrativa.

adUnitId de demonstração: demo-banner-yandex.

Importante

Antes de publicar seu app na loja, certifique-se de substituir a ID de posicionamento demonstrativa pela ID real obtida na interface Yandex Advertising Network.

Para a lista de todas as IDs de posicionamento de anúncio demonstrativas disponíveis, consulte Blocos de anúncio demonstrativos para testes.

Teste da integração de anúncios

É possível verificar se seus banners adaptativos inline estão integrados corretamente usando o analisador embutido do SDK. Aparecerá no log um relatório detalhado com os resultados do teste.

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 banner was integrated successfully

Se houver algum problema na integração dos banners, você receberá um relatório detalhado do problema com soluções recomendadas.

Recursos adicionais

Seguinte
Anúncios intersticiais