Pré-carregando mídia

O SDK do IMA oferece suporte ao carregamento antecipado de recursos de anúncios em vídeo. É possível ativar esse recurso na integração do SDK para oferecer uma transição mais suave entre anúncios e conteúdo. Este guia aborda os detalhes técnicos da implementação do carregamento prévio de mídia com o SDK do IMA.

Pré-requisito

O pré-carregamento requer a versão 3.17.0 ou mais recente do SDK do IMA para Android.

Ativar o pré-carregamento

Para ativar o pré-carregamento, use AdsRenderingSettings.setEnablePreloading() para definir o pré-carregamento como verdadeiro. Isso precisa ser feito no callback onAdsManagerLoaded():

@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent adsManagerLoadedEvent) {
  ...
  AdsRenderingSettings adsRenderingSettings =
      ImaSdkFactory.getInstance().createAdsRenderingSettings();
  adsRenderingSettings.setEnablePreloading(true);
  mAdsManager.init(adsRenderingSettings);
}

Suporte ao pré-carregamento com um VideoAdPlayer personalizado

Recomendamos a extensão ExoPlayer-IMA usada no app de exemplo do ExoPlayer do Android. Quando integrada, a extensão ExoPlayer-IMA tem o carregamento prévio ativado por padrão e inclui suporte integrado a ele.

Se você estiver implementando o pré-carregamento sem a extensão ExoPlayer-IMA, outras mudanças serão necessárias quando setEnablePreloading() for chamado. Para que um player de vídeo ofereça suporte ao pré-carregamento de anúncios, ele precisa acompanhar os objetos AdMediaInfo que são transmitidos em chamadas de loadAd() e playAd() e incluir o AdMediaInfo correto nas chamadas de AdPlayerCallback. Isso pode requerer uma estrutura de dados para gerenciar objetos AdMediaInfo, já que loadAd() para uma AdMediaInfo subsequente pode ocorrer enquanto uma AdMediaInfo anterior está sendo reproduzida. O exemplo a seguir demonstra algumas das mudanças que você pode precisar fazer para que o app ofereça suporte ao pré-carregamento:

// enum for cases of PlayerState.
static enum PlayerState {
  IDLE,
  LOADED,
  PLAYING,
  PAUSED,
}

...

private final List<VideoAdPlayer.VideoAdPlayerCallback> callbacks;
private final ArrayList<AdMediaInfo> mediaInfos = new ArrayList<>();
private PlayerState playerState;
private boolean adCurrentlyLoaded;

...

@Override
public void playAd(AdMediaInfo adMediaInfo) {
  switch (playerState) {
    case LOADED:
      for (VideoAdPlayerCallback callback : callbacks) {
        callback.onPlay(adMediaInfo);
      }
      break;
    case PAUSED:
      for (VideoAdPlayerCallback callback : callbacks) {
        callback.onResume(adMediaInfo);
      }
      break;
    case PLAYING:
      // Intentionally and silently ignore since it is already playing from a prior media item,
      // note that onPlay is triggered by positionDiscontinuity.
      return;
    case IDLE:
      throw new IllegalStateException("Call to playAd when player state is not LOADED.");
  }
  playerState = PlayerState.PLAYING;
  player.setPlayWhenReady(true);
}

@Override
public void loadAd(AdMediaInfo adMediaInfo, AdPodInfo adPodInfo) {
  if (adCurrentlyLoaded == true) {
    mediaInfos.add(adMediaInfo);
    return;
  }
  player.stop();
  player.seekTo(0);
  mediaInfos.clear();
  mediaInfos.add(adMediaInfo);
  player.setPlayWhenReady(false);
  player.loadMedia(adMediaInfo.getUrl());
  playerState = PlayerState.LOADED;
  adCurrentlyLoaded = true;
}

@Override
public void stopAd(AdMediaInfo adMediaInfo) {
  if (allAdsInBreakHavePlayed()) {
    if (isFinalAd(adMediaInfo)) {
      // handle clean up after all ads have played.
    } else {
      seekToNextItem(player);
    }
  } else {
    mediaInfos.remove(adMediaInfo);
  }
}

private boolean allAdsInBreakHavePlayed() {
  // Code to determine if all the ads in the current ad break have completed.
}

private boolean isFinalAd(AdMediaInfo adMediaInfo) {
  // Code to determine if this adMediaInfo is the final ad.
}

private void seekToNextItem(YourPlayerClass player) {
  // Code to seek your player to the next media item.
}

Como testar implementações de pré-carregamento personalizadas

Para implementações de pré-carregamento personalizadas, é recomendado testar os seguintes casos extremos para verificar uma configuração de pré-carregamento correta:

• Anúncio precedente único
• 3 anúncios precedentes
• 3 anúncios intermediários no conjunto
• Procurar um segundo anúncio intermediário depois que o primeiro começou a ser carregado, mas antes de ser reproduzido
• Reprodução de anúncio final

Tempo

A tabela a seguir resume as mudanças no tempo de carregamento de anúncios quando o carregamento antecipado está ativado:

Evento	Com pré-carregamento	Sem pré-carregamento
VAST do anúncio solicitado	AdsLoader.requestAds()	AdsLoader.requestAds()
Anúncio precedente carregado (um anúncio)	AdsManager.init()	AdsManager.start()
Pre-roll carregado (VMAP/regras de anúncio)	AdsManager.init()	AdsManager.init()
Anúncios intermediários ou finais carregados	Para o primeiro anúncio em um intervalo comercial, 8 segundos antes do início do anúncio. Para anúncios consecutivos, quando o anúncio anterior começa a ser reproduzido.	No horário de início do anúncio.

Perguntas frequentes

O pré-carregamento de mídia carrega o criativo completo?

Não, o criativo geralmente não é carregado totalmente quando a reprodução do anúncio começa. O objetivo do pré-carregamento é melhorar a experiência do usuário minimizando o tempo necessário para carregar o anúncio. Ele não é compatível com a veiculação de anúncios off-line.

O carregamento prévio de mídia precisa ser ativado para o VAST e a mídia do anúncio?

Não, o SDK sempre carrega o VAST do anúncio, independentemente dessa configuração de pré-carregamento.