Migração do SDK

Esta página aborda migrações para versões atuais e anteriores.

Migrar da v23 para a v24

As subseções a seguir descrevem mudanças significativas e diferenças de comportamento entre as versões principais 23 e 24 do SDK dos anúncios para dispositivos móveis do Google.

O nível mínimo da API Android é 23.

A partir da versão 24.0.0, o SDK dos anúncios para dispositivos móveis do Google exige que todos os apps sejam executados em um nível mínimo da API do Android 23. Para ajustar o nível da API, mude o valor de minSdk no arquivo build.gradle no nível do app para 23 ou mais recente.

Mudanças na inicialização e no carregamento otimizados

Por padrão, as flags OPTIMIZE_INITIALIZATION e OPTIMIZE_AD_LOADING são definidas como true. Para mais informações sobre essas flags, consulte Otimizar inicialização e carregamento.

Dependências firebase-ads e firebase-ads-lite removidas

A partir da versão 24.0.0, os lançamentos do SDK não distribuem mais as dependências firebase-ads e firebase-ads-lite. Em vez disso, use a dependência play-services-ads.

Definir parâmetros de segmentação personalizada

Para definir uma segmentação personalizada em uma solicitação de anúncio, use addCustomTargeting().

Remoção de APIs de orientação descontinuadas para anúncios de abertura do app

  • Remoção dos métodos AppOpenAd.load() que aceitam um parâmetro de entrada de orientação. Em vez disso, use métodos AppOpenAd.load() que não exigem uma orientação.
  • A enumeração AppOpenAdOrientation foi removida.

Callback de recompensa simplificado para adaptadores de mediação

A versão 24.0.0 adiciona o callback onUserEarnedReward() em MediationRewardedAdCallback e descontinua onUserEarnedReward(RewardItem). Os adaptadores de mediação precisam começar a chamar onUserEarnedReward() quando o usuário ganha uma recompensa.

Ao encaminhar callbacks de adaptadores de mediação, todas as versões do SDK dos anúncios para dispositivos móveis do Google retornam a recompensa definida na interface do Ad Manager em OnUserEarnedRewardListener.

Turmas removidas

As seguintes classes foram removidas sem substituição:

  • DynamicHeightSearchAdRequest
  • SearchAdRequest
  • SearchAdView

Métodos removidos

Os seguintes métodos foram removidos sem substituição:

Turma Método
RewardedInterstitialAdLoadCallback onRewardedInterstitialAdLoaded()
onRewardedInterstitialAdFailedToLoad(int)
onRewardedInterstitialAdFailedToLoad(LoadAdError)

Métodos descontinuados

Os seguintes métodos foram descontinuados sem substituição:

Turma Método
Adaptador loadInterscrollerAd()
RtbAdapter loadRtbInterscrollerAd()

Migrar da v22 para a v23

As subseções a seguir descrevem mudanças significativas e diferenças de comportamento entre as versões principais 22 e 23 do SDK dos anúncios para dispositivos móveis do Google.

O nível mínimo da API Android é 21.

A partir da versão 23.0.0, o SDK dos anúncios para dispositivos móveis do Google exige que todos os apps estejam em um nível mínimo da API Android 21 para serem executados. Para ajustar o nível da API, mude o valor de minSdkVersion no arquivo build.gradle no nível do app para 21 ou mais recente.

É possível encadear métodos AdManagerAdRequest.Builder herdados da superclasse

Na versão 23.0.0, os métodos AdManagerAdRequest.Builder herdados do elemento pai podem ser encadeados para criar um AdManagerAdRequest usando uma única chamada:

Java

AdManagerAdRequest request = new AdManagerAdRequest.Builder()
    .addCustomTargeting("age", "25") // AdManagerAdRequest.Builder method.
    .setContentUrl("https://www.example.com") // Method inherited from parent.
    .build(); // Builds an AdManagerAdRequest.

Kotlin

var request = AdManagerAdRequest.Builder()
  .addCustomTargeting("age", "25") // AdManagerAdRequest.Builder method.
  .setContentUrl("https://www.example.com") // Method inherited from parent.
  .build() // Builds an AdManagerAdRequest.

Métodos obsoletos removidos/substituídos

API v22.0.0 API v23.0.0
AdRequest.Builder.addTestDevice() RequestConfiguration.Builder.setTestDeviceIds()
AdRequest.Builder.tagForChildDirectedTreatment() RequestConfiguration.Builder.setTagForChildDirectedTreatment()
AdRequest.Builder.setIsDesignedForFamilies() RequestConfiguration.Builder.setMaxAdContentRating()
AdFormat.UNKNOWN Sem substituição
AdLoader.Builder.forUnifiedNativeAd() AdLoader.Builder.forNativeAd()
AdLoader.Builder.forCustomTemplateAd() AdLoader.Builder.forCustomFormatAd()
AdLoader.Builder.withNativeAdOptions(com.google.android.gms.ads.formats.NativeAdOptions) AdLoader.Builder.withNativeAdOptions(com.google.android.gms.ads.nativead.NativeAdOptions)
void MobileAds.setSameAppKeyEnabled() boolean MobileAds.putPublisherFirstPartyIdEnabled()

Migrar da v21 para a v22

As subseções a seguir descrevem mudanças significativas e diferenças de comportamento entre as versões principais 21 e 22 do SDK dos anúncios para dispositivos móveis do Google.

Use MobileAds.getVersion() para receber a versão do SDK dos anúncios para dispositivos móveis do Google.

O método MobileAds.getVersionString() foi removido na versão 22.0.0 e substituído por MobileAds.getVersion().

O novo método retorna o número da versão externa esperada, por exemplo, 22.0.0. Para mais informações sobre essa mudança, consulte Usar o novo método getVersion() do SDK dos anúncios para dispositivos móveis do Google.

Remoção de NativeCustomFormatAd.getVideoMediaView() descontinuado

Na versão 21, o SDK dos anúncios para dispositivos móveis do Google forneceu o método NativeCustomFormatAd.getVideoMediaView() para receber o recurso de mídia de um formato de anúncio nativo personalizado.

A partir da versão 22, você cria seu próprio MediaView, define o conteúdo de mídia dele e usa MediaContent.getVideoController() para acessar os controles de vídeo.

v22

// Called when a custom native ad loads.
@Override
public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
    // Assumes you have a FrameLayout in your view hierarchy with the ID media_placeholder.
    FrameLayout mediaPlaceholder = (FrameLayout) findViewById(R.id.media_placeholder);

    MediaContent mediaContent = ad.getMediaContent();
    if (mediaContent != null && mediaContent.hasVideoContent()) {
        // Create a MediaView and set its media content.
        MediaView mediaView = new MediaView(mediaPlaceholder.getContext());
        mediaView.setMediaContent(mediaContent);
        mediaPlaceholder.addView(mediaView);
    }
}

v21

// Called when a custom native ad loads.
@Override
public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
    // Assumes you have a FrameLayout in your view hierarchy with the ID media_placeholder.
    FrameLayout mediaPlaceholder = (FrameLayout) findViewById(R.id.media_placeholder);

    VideoController videoController = ad.getVideoController();
    if (videoController.hasVideoContent()) {
        // Add the media view provided by the native ad.
        mediaPlaceholder.addView(ad.getVideoMediaView());
    }
}

Consulte o guia de anúncios nativos personalizados para mais informações.

Métodos removidos ou substituídos

A tabela a seguir lista as mudanças específicas na versão 22.0.0:

v21.0.0 v22.0.0
MobileAds.getVersionString() MobileAds.getVersion()
NativeCustomFormatAd.getVideoMediaView() NativeCustomFormatAd.getMediaContent()
NativeCustomFormatAd.getVideoController() NativeCustomFormatAd.getMediaContent().getVideoController()
AdRequest.Builder.setAdInfo() AdRequest.Builder.setAdString()
MediationRewardedVideoAdAdapter Adaptador
MediationRewardedVideoAdListener
com.google.android.gms.ads.mediation.VersionInfo com.google.android.gms.ads.VersionInfo
com.google.android.gms.ads.doubleclick.AppEventListener com.google.android.gms.ads.admanager.AppEventListener

Migrar da v20 para a v21

As subseções a seguir descrevem mudanças interruptivas e diferenças de comportamento entre as versões principais 20 e 21 do SDK dos anúncios para dispositivos móveis do Google:

Atualize minSdkVersion para 19 ou mais recente

A partir da versão 21.0.0, o SDK dos anúncios para dispositivos móveis do Google exige que todos os apps estejam em um nível mínimo da API Android 19 para serem executados. Para ajustar o nível da API, mude o valor de minSdkVersion no arquivo de build do app para 19 ou mais.

Aplicar nulidade estrita

Em preparação para a aplicação da nulidade estrita, as anotações @NonNull são adicionadas a todas as APIs que não definiram explicitamente a nulidade.

Essa mudança pode interromper os apps Kotlin e os apps que usam frameworks de verificação de nulos do Java se houver violações de proteção contra valores nulos e se os valores null não forem processados de maneira segura (consulte a documentação do Kotlin sobre proteção contra valores nulos).

Remoção do método addNetworkExtras()

O método addNetworkExtras(), que transmite parâmetros extras como uma instância NetworkExtras para um adaptador de rede de publicidade específico, foi descontinuado na versão 20.3.0 do SDK e será removido na versão 21.0.0. Em vez disso, use o método addNetworkExtrasBundle() da mesma classe AdRequest.Builder.

Remoção de métodos de localização

Os seguintes métodos de localização serão removidos na versão 21.0.0:

  • O método setLocation(Location location) na classe AdRequest.Builder que define a localização do usuário para fins de segmentação por mediação.
  • O método getLocation() na classe AdRequest que retorna as informações de segmentação por local do usuário transmitidas anteriormente ao método setLocation(Location location).
  • O método getLocation() na classe MediationAdConfiguration que retorna o local do usuário, se definido pelo AdRequest.

Os dados de local não são usados pelo Google para segmentar anúncios. Use APIs de terceiros para fornecer as informações às redes de publicidade de terceiros, se necessário.

Descontinuação das interfaces de eventos personalizados

Com os eventos personalizados, os editores que usam a mediação podem configurar uma origem de anúncios em hierarquia que não seja uma das origens de anúncios compatíveis do Ad Manager.

Todas as interfaces de evento personalizado foram descontinuadas em favor da classe Adapter e da interface MediationAdLoadCallback.

A tabela a seguir lista a classe ou interface correspondente que você precisa usar para cada interface de evento personalizado a partir da versão 21.0.0:

Interfaces da v20.0.0 Classe/ interface v21.0.0
CustomEvent Adaptador
CustomEventBanner
CustomEventInterstitial
CustomEventNative
CustomEventBannerListener Adapter, MediationAdLoadCallback
CustomEventInterstitialListener
CustomEventListener
CustomEventNativeListener

Migrar da v19 para a v20

Há muitas mudanças interruptivas na versão 20.0.0. A versão 19.7.0 introduziu muitas APIs novas e descontinuou ou renomeou muitas classes em preparação para a versão 20.0.0. Este guia destaca as principais mudanças na versão 20.0.0.

Atualizações da API de formato de tela cheia

A partir da versão 20.0.0, os formatos de anúncio intersticial, premiado, intersticial premiado e de abertura do app são padronizados para seguir um design de API consistente.

Todas as APIs de formato de tela cheia usam os seguintes princípios:

  • Um método de carregamento estático
  • Um mecanismo de retorno de chamada ou manipulador de carga semelhante
  • Confiança na classe FullScreenContentCallback para callbacks de apresentação

Remoção da API Legacy RewardedVideoAd

A API RewardedAd mais recente foi lançada em março de 2019 e é a API de recompensa preferida há mais de 18 meses. Ela teve mais melhorias em comparação com a API RewardedVideoAd legada, incluindo a capacidade de carregar mais de um anúncio premiado por vez.

A API legada RewardedVideoAd foi removida na versão 20.0.0 do SDK.

Descontinuação do banner inteligente em favor do banner adaptativo

Os anúncios de banner inteligente foram descontinuados em favor dos anúncios de banner adaptativo. Os banners adaptativos oferecem performance superior e mais flexibilidade na definição da largura do anúncio. Se você preferir continuar usando banners de largura total, isso ainda poderá ser feito com o banner adaptativo, conforme mostrado no snippet de código a seguir:

Java

public class MyActivity extends AppCompatActivity {
  ...
  private AdSize getFullWidthAdaptiveSize() {
    Display display = getWindowManager().getDefaultDisplay();
    DisplayMetrics outMetrics = new DisplayMetrics();
    display.getMetrics(outMetrics);

    float widthPixels = outMetrics.widthPixels;
    float density = outMetrics.density;

    int adWidth = (int) (widthPixels / density);
    return AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, adWidth);
  }
}

Kotlin

class MyActivity : AppCompatActivity() {
  ...
  private val adaptiveAdSize: AdSize
    get() {
      val display = windowManager.defaultDisplay
      val outMetrics = DisplayMetrics()
      display.getMetrics(outMetrics)

      val density = outMetrics.density

      var adWidthPixels = ad_view_container.width.toFloat()
      if (adWidthPixels == 0f) {
        adWidthPixels = outMetrics.widthPixels.toFloat()
      }

      val adWidth = (adWidthPixels / density).toInt()
      return AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, adWidth)
    }
}

Remoção de callback de saída do aplicativo

O callback onAdLeftApplication para todos os formatos de anúncio foi removido em favor de ProcessLifecycleOwner. Usar uma API no nível do SO notifica você sempre que os usuários saem do app, independente de ser devido a uma interação com um anúncio ou não.

O callback onAdLeftApplication nunca foi criado para ser um gerenciador de cliques de anúncios, e confiar nele para informar cliques não produzia uma métrica precisa. Por exemplo, um clique no ícone "Opções de anúncios" que iniciou um navegador externo invocou o callback, mas não foi contabilizado como um clique.

Renomeação de classes

A tabela a seguir lista nomes de classes específicos que foram alterados ou removidos:

  • A maioria das classes relacionadas a UnifiedNativeAd foi renomeada como NativeAd.
  • As classes e visualizações MobileAds.Settings, NativeExpressAdView, NativeAppInstallAd, NativeContentAd e InstreamAd foram removidas.
  • Todas as classes com o prefixo Publisher foram substituídas por um prefixo AdManager.
  • O nome do pacote InterstitialAd mudou.
Classe 19.5.0 Classe 20.0.0
com.google.android.gms.ads. com.google.android.gms.ads.
reward.RewardedVideoAd rewarded.RewardedAd
reward.RewardedVideoAdListener rewarded.RewardedAdLoadCallback e FullScreenContentCallback
reward.RewardItem rewarded.RewardItem
rewarded.RewardedAdCallback OnUserEarnedRewardListener
formats.UnifiedNativeAdView nativead.NativeAdView
formats.UnifiedNativeAd nativead.NativeAd
formats.UnifiedNativeAdAssetNames nativead.NativeAdAssetNames
formats.UnifiedNativeAd.OnUnifiedNativeAdLoadedListener nativead.NativeAd.OnNativeAdLoadedListener
formats.AdChoicesView nativead.AdChoicesView
formats.NativeAd.AdChoicesInfo nativead.NativeAd.AdChoicesInfo
formats.MediaView nativead.MediaView
formats.NativeAdViewHolder nativead.NativeAdViewHolder
formats.NativeAdOptions nativead.NativeAdOptions
formats.NativeCustomTemplateAd nativead.NativeCustomFormatAd
formats.NativeCustomTemplateAd.OnCustomTemplateAdLoadedListener nativead.NativeCustomFormatAd.OnCustomFormatAdLoadedListener
MobileAds.Settings Removido
doubleclick.PublisherAdRequest admanager.AdManagerAdRequest
doubleclick.PublisherAdView admanager.AdManagerAdView
formats.PublisherAdViewOptions formats.AdManagerAdViewOptions
doubleclick.PublisherInterstitialAd admanager.AdManagerInterstitialAd
InterstitialAd interstitial.InterstitialAd
NativeExpressAdView Removido
instream.InstreamAd Removido
mediation.admob.AdMobExtras Removido
Correlator Removido
search.SearchAdRequest Removido
Interface AdRequest.TagForUnderAgeOfConsent Removido
Interface AdRequest.MaxAdContentRating Removido
formats.NativeAppInstallAd native.NativeAd
formats.NativeAppInstallAdView native.NativeAdView
mediation.NativeAppInstallAdMapper mediation.UnifiedNativeAdMapper
formats.NativeContentAd native.NativeAd
formats.NativeContentAdView native.NativeAdView
mediation.NativeContentAdMapper mediation.UnifiedNativeAdMapper

Métodos removidos/substituídos

A tabela a seguir lista as mudanças específicas na versão 20.0.0:

  • Métodos de inicialização desatualizados foram removidos da classe MobileAds.
  • Alguns métodos da classe AdRequest.Builder() foram removidos ou movidos para a classe RequestConfiguration.
  • As APIs RewardedAd e InterstitialAd foram atualizadas para se alinhar a todos os formatos de tela cheia.
  • Os recursos de correlacionador foram removidos.
Turma API v19.5.0 API v20.0.0 Observações
AdSize getPortraitBannerAdSizeWithWidth() getPortraitAnchoredAdaptiveBannerAdSize()
getLandscapeBannerAdSizeWithWidth() getLandscapeAnchoredAdaptiveBannerAdSize()
getCurrentOrientationBannerAdSizeWithWidth() getCurrentOrientationAnchoredAdaptiveBannerAdSize()
MobileAds initialize(Context, String) MobileAds.initialize(Context, OnInitializationCompleteListener) O ID do app agora está definido no AndroidManifest.xml.
initialize(Context, String, MobileAds.Settings) initialize(Context, OnInitializationCompleteListener) A classe "Settings" foi descontinuada.
getRewardedVideoAdInstance() Removido Use a API RewardedAd.
AdListener onAdFailedToLoad(int) onAdFailedToLoad(LoadAdError)
onAdLeftApplication() Removido Os formatos de anúncio em tela cheia usam FullscreenContentCallback em vez de AdListener, e não há um método equivalente em FullscreenContentCallback. O método foi removido de AdListener.
VideoController getAspectRatio() MediaContent.getAspectRatio()
PublisherAdRequest getGender() Removido
getBirthday() Removido
getNetworkExtras() Removido
setManualImpressionsEnabled() Removido
updateCorrelator() Removido Consulte Filtragem de conteúdo do anúncio.
PublisherAdRequest.Builder setBirthday() Removido
setGender() Removido
setIsDesignedForFamilies() Removido Consulte o guia.
addTestDevice() RequestConfiguration.Builder.setTestDeviceIds() Consulte Ativar anúncios de teste.
tagForChildDirectedTreatment() RequestConfiguration.Builder.setTagForChildDirectedTreatment() Consulte Filtragem de conteúdo do anúncio.
setTagForUnderAgeOfConsent() RequestConfiguration.Builder.setTagForUnderAgeOfConsent()
setMaxAdContentRating() RequestConfiguration.Builder.setMaxAdContentRating()
AdView getMediationAdapterClassName() ResponseInfo.getMediationAdapterClassName() Um objeto ResponseInfo está disponível usando o método AdView, getResponseInfo().
NativeAdOptions setImageOrientation() setMediaAspectRatio()
getImageOrientation getMediaAspectRatio()
RewardedAd loadAd(AdRequest, RewardedAdLoadCallback) RewardedAd.load(Context, String, AdRequest, RewardedAdLoadCallback) O RewardedAd agora usa a mesma abordagem de carregamento estático que outros formatos de tela cheia.
loadAd(PublisherAdRequest, RewardedAdLoadCallback) RewardedAd.load(Context, String, AdManagerAdRequest, RewardedAdLoadCallback)
isLoaded() Removido O callback do método de carregamento estático fornece um anúncio já carregado.
show(Activity, RewardedAdCallback) show(Activity, OnUserEarnedRewardListener) Esse método de exibição segue a abordagem mais ampla do formato de tela cheia.
RewardedAdLoadCallback onRewardedAdFailedToLoad(int) onAdFailedToLoad(LoadAdError)
onRewardedAdFailedToLoad(LoadAdError) onAdFailedToLoad(LoadAdError)
onRewardedAdLoaded() onAdLoaded(RewardedAd)
AppOpenAdLoadCallback onAppOpenAdFailedToLoad(int) onAdFailedToLoad(LoadAdError)
onAppOpenAdFailedToLoad(LoadAdError) onAdFailedToLoad(LoadAdError)
onAppOpenAdLoaded(AppOpenAd) onAdLoaded(AppOpenAd)
RewardedInterstitialAdLoadCallback onRewardedInterstitialAdFailedToLoad(int) onAdFailedToLoad(LoadAdError)
onRewardedInterstitialAdFailedToLoad(LoadAdError) onAdFailedToLoad(LoadAdError)
onRewardedInterstitialAdLoaded(RewardedInterstitialAd) onAdLoaded(RewardedInterstitialAd)
PublisherInterstitialAd new PublisherInterstitialAd() InterstitialAd.load(Context, String, AdRequest, InterstitialAdLoadCallback) O InterstitialAd agora usa a mesma abordagem de carregamento estático que outros formatos de tela cheia.
setAdListener()
DynamicHeightSearchAdRequest getNetworkExtras() Removido A classe NetworkExtras foi descontinuada.
AdLoader forContentAd() Removido
forAppInstallAd() Removido
withCorrelator() Removido
getMediationAdapterClassName() Removido