Banner

Os anúncios de banner são anúncios retangulares de imagem ou texto que ocupam um espaço dentro do layout do aplicativo. Eles permanecem na tela enquanto os usuários interagem com o app e podem ser atualizados automaticamente após um determinado período de tempo. Se você está começando na publicidade mobile, eles são uma excelente opção para começar.

Integração

Existem três formas de integrar um banner: adicionando a view do banner a um layout XML, criando-a por código ou incorporando-a ao Jetpack Compose. Abaixo mostramos exemplos de cada método:

Layout XML

<com.wortise.ads.banner.BannerAd
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  app:adSize="HEIGHT_50"
  app:adUnitId="Ad Unit ID da Wortise"
/>

O widget oferece suporte aos seguintes parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
app:adUnitId	String	Sim	O ID do ad unit a ser atribuído ao banner
app:adSize	AdSize	Não	Tamanho máximo (altura) do banner. Os valores possíveis para este parâmetro estão declarados na classe AdSize
app:autoRefreshTime	Integer	Não	Valor em segundos que representa o tempo que deve transcorrer para carregar um novo anúncio de banner

Código

Kotlin

class MainActivity : Activity() {

    private var bannerAd: BannerAd? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        bannerAd = BannerAd(this).also {
            it.adSize = AdSize.HEIGHT_50
            it.adUnitId = "<Ad Unit ID da Wortise>"

            // Por exemplo, adicionamos o BannerAd em um FrameLayout
            val frameLayout = findViewById<FrameLayout>(R.id.frame)
            frameLayout.addView(it)

            it.loadAd()
        }
    }

    override fun onDestroy() {
        ...
        bannerAd?.destroy()
    }

    override fun onPause() {
        ...
        bannerAd?.pause()
    }

    override fun onResume() {
        ...
        bannerAd?.resume()
    }

}

Java

public class MainActivity extends Activity {

    private BannerAd mBannerAd;

    @Override
    public void onCreate(Bundle savedInstanceState) {
        ...
        mBannerAd = new BannerAd(this);
        mBannerAd.setAdSize(AdSize.HEIGHT_50);
        mBannerAd.setAdUnitId("<Ad Unit ID da Wortise>");

        // Por exemplo, adicionamos o BannerAd em um FrameLayout
        FrameLayout frameLayout = findViewById(R.id.frame);
        frameLayout.addView(mAdView);

        mBannerAd.loadAd();
    }

    @Override
    public void onDestroy() {
        ...
        mBannerAd.destroy();
    }

    @Override
    public void onPause() {
        ...
        mBannerAd.pause();
    }

    @Override
    public void onResume() {
        ...
        mBannerAd.resume();
    }
}

A classe BannerAd oferece os seguintes métodos para configurar a instância:

Método	Obrigatório	Descrição
setAdUnitId(String)	Sim	Atribui um ad unit ao banner
setAdSize(AdSize)	Não	Tamanho máximo (altura) do banner. Os valores possíveis para este parâmetro estão declarados na classe AdSize
setAutoRefreshTime(long)	Não	Valor em milissegundos que representa o tempo que deve transcorrer para carregar um novo anúncio de banner
setAutoRefreshTime(long, TimeUnit)	Não	Igual ao método anterior, mas permite especificar a unidade de tempo do valor informado

Jetpack Compose

Os anúncios banner da Wortise podem ser integrados ao Jetpack Compose usando a API de interoperabilidade AndroidView do Compose.

@Composable
fun WortiseBanner() {
    val context = LocalContext.current
    val banner = remember { BannerAd(context) }

    AndroidView(
        factory = {
            banner.apply {
                adSize = AdSize.HEIGHT_50
                adUnitId = "<Ad Unit ID da Wortise>"

                loadAd()
            }
        },
        modifier = Modifier
            .fillMaxWidth()
            .wrapContentHeight()
    )

    DisposableEffect(Unit) {
        onDispose {
            banner.destroy()
        }
    }
}

A classe BannerAd é uma View padrão do Android, portanto pode ser incorporada a uma interface Compose usando AndroidView.

A instância do banner é criada com remember para ser preservada entre recomposições e é destruída quando o composable sai da composição.

Exemplo

@Composable
fun MyScreen() {
    Column {
        // Conteúdo da sua tela

        WortiseBanner()
    }
}

Banners adaptativos

Os banners adaptativos são um novo formato de banner em que o tamanho dos anúncios se adapta ao dispositivo e à interface do app, com o objetivo de maximizar o desempenho.

Atualmente há suporte para dois tipos de banners adaptativos:

Ancorados

Esse tipo de banner foi projetado para substituir os banners tradicionais de 320x50 e ser posicionado na parte superior ou inferior da tela.

Para usar esse formato, o seguinte código deve ser utilizado para configurar um tamanho adaptativo:

Kotlin

// Você precisa especificar a largura do banner
val adSize = AdSize.getAnchoredAdaptiveBannerAdSize(context, width)
bannerAd.adSize = adSize

Java

// Você precisa especificar a largura do banner
AdSize adSize = AdSize.getAnchoredAdaptiveBannerAdSize(context, width);
mBannerAd.setAdSize(adSize);

Como alternativa, esta outra opção pode ser implementada para que o SDK calcule a largura do banner, passando a própria instância do BannerAd ou a View que irá contê-lo:

Cuidado

Nesta opção, é altamente recomendável que a View passada ao método já esteja adicionada ao layout do app, para que o SDK possa calcular corretamente todas as dimensões.

Kotlin

val adSize = AdSize.getAnchoredAdaptiveBannerAdSize(view)
bannerAd.adSize = adSize

Java

AdSize adSize = AdSize.getAnchoredAdaptiveBannerAdSize(view);
mBannerAd.setAdSize(adSize);

Inline

Esse outro tipo de banner, em comparação com o ancorado, foi projetado para ter altura variável e ser posicionado dentro de um conteúdo com rolagem.

Neste caso, o seguinte código deve ser utilizado para configurar um tamanho adaptativo apropriado:

Kotlin

val maxHeight = 200

// Você precisa especificar a largura do banner. A altura máxima é um
// parâmetro opcional
val adSize = AdSize.getInlineAdaptiveBannerAdSize(context, width, maxHeight)
bannerAd.adSize = adSize

Java

int maxHeight = 200;

// Você precisa especificar a largura do banner. A altura máxima é um
// parâmetro opcional
AdSize adSize = AdSize.getInlineAdaptiveBannerAdSize(
    context, width, maxHeight
);
mBannerAd.setAdSize(adSize);

Como alternativa, esta outra opção pode ser implementada para que o SDK calcule a largura do banner, passando a própria instância do BannerAd ou a View que irá contê-lo:

Cuidado

Nesta opção, é altamente recomendável que a View passada ao método já esteja adicionada ao layout do app, para que o SDK possa calcular corretamente todas as dimensões.

Kotlin

val maxHeight = 200

val adSize = AdSize.getInlineAdaptiveBannerAdSize(view, maxHeight)
bannerAd.adSize = adSize

Java

int maxHeight = 200;

AdSize adSize = AdSize.getInlineAdaptiveBannerAdSize(view, maxHeight);
mBannerAd.setAdSize(adSize);

Banners recolhíveis

Os banners recolhíveis são banners ancorados que inicialmente são exibidos como uma sobreposição maior, com um botão que os recolhe até o tamanho declarado. Eles têm como objetivo melhorar o desempenho dos banners ancorados sem ocupar mais espaço de forma permanente.

Para solicitar um, passe uma instância de RequestParameters com a posição desejada ao método loadAd:

Kotlin

val parameters = RequestParameters(
    collapsible = CollapsiblePosition.BOTTOM
)

bannerAd.loadAd(parameters)

Java

RequestParameters parameters = new RequestParameters();
parameters.setCollapsible(CollapsiblePosition.BOTTOM);

mBannerAd.loadAd(parameters);

A posição determina onde o anúncio expandido é ancorado, e deve corresponder à posição do banner dentro do layout do app:

Valor	Descrição
CollapsiblePosition.BOTTOM	O banner está posicionado na parte inferior da tela
CollapsiblePosition.TOP	O banner está posicionado na parte superior da tela

Nota

Os banners recolhíveis exigem um tamanho adaptativo ancorado, então certifique-se de que o banner foi configurado conforme explicado na seção Ancorados.

Cuidado

O formato recolhível só é solicitado para o primeiro anúncio de uma instância de BannerAd. Quando o banner é atualizado, os anúncios seguintes são solicitados como banners ancorados comuns.

Configuração do listener

Um listener pode ser definido em qualquer instância de BannerAd para receber os eventos que ocorrem durante seu ciclo de vida. Para isso, você precisa implementar a interface BannerAd.Listener como mostrado no exemplo abaixo:

Kotlin

bannerAd.listener = object : BannerAd.Listener {

    override fun onBannerClicked(ad: BannerAd) {
        // Invocado quando o anúncio foi clicado
    }

    override fun onBannerFailedToLoad(ad: BannerAd, error: AdError) {
        // Invocado quando não foi possível carregar o anúncio
        // (por causa de um erro ou sem preenchimento (no fill))
    }

    override fun onBannerImpression(ad: BannerAd) {
        // Invocado quando o anúncio gerou uma impressão
    }

    override fun onBannerLoaded(ad: BannerAd) {
        // Invocado quando o anúncio foi carregado
    }

    override fun onBannerRevenuePaid(ad: BannerAd,
                                     data: RevenueData) {
        // Invocado quando o anúncio gerou receita
    }

}

Java

mBannerAd.setListener(new BannerAd.Listener() {
    @Override
    public void onBannerClicked(@NonNull BannerAd ad) {
        // Invocado quando o anúncio foi clicado
    }

    @Override
    public void onBannerFailedToLoad(@NonNull BannerAd ad,
                                     @NonNull AdError error) {
        // Invocado quando não foi possível carregar o anúncio
        // (por causa de um erro ou sem preenchimento (no fill))
    }

    @Override
    public void onBannerImpression(@NonNull BannerAd ad) {
        // Invocado quando o anúncio gerou uma impressão
    }

    @Override
    public void onBannerLoaded(@NonNull BannerAd ad) {
        // Invocado quando o anúncio foi carregado
    }

    @Override
    public void onBannerRevenuePaid(@NonNull BannerAd ad,
                                     @NonNull RevenueData data) {
        // Invocado quando o anúncio gerou receita
    }
});