Pré-carregando mídia

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

Pré-requisitos

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

Ativar 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 Android BasicExample. Quando integrada, a extensão ExoPlayer-IMA tem o pré-carregamento ativado por padrão e inclui suporte ao pré-carregamento integrado.

Se você estiver implementando o pré-carregamento sem a extensão do ExoPlayer-IMA, será necessário fazer outras mudanças depois que setEnablePreloading() for chamado. Para que um player de vídeo ofereça suporte a anúncios de pré-carregamento, ele precisa rastrear os objetos AdMediaInfo transmitidos em chamadas de loadAd() e playAd() e incluir o AdMediaInfo correto nas chamadas de AdPlayerCallback. Isso pode exigir uma estrutura de dados para gerenciar objetos AdMediaInfo, já que loadAd() para uma AdMediaInfo subsequente pode ocorrer enquanto um AdMediaInfo anterior está sendo reproduzido no momento. 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, recomendamos testar os seguintes casos extremos para verificar uma configuração de pré-carregamento correta:

• Anúncio precedente único
• 3 anúncios precedentes do conjunto de anúncios
• 3 anúncios intermediários em conjuntos de anúncios
• Buscar um segundo anúncio intermediário após o início do pré-carregamento, mas antes da reprodução
• Reprodução final

Prazo

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

Evento	Com pré-carregamento	Sem pré-carregamento
Anúncio VAST solicitado	AdsLoader.requestAds()	AdsLoader.requestAds()
Anúncio precedente carregado (anúncio único)	AdsManager.init()	AdsManager.start()
Anúncio precedente carregado (regras de anúncio/VMAP)	AdsManager.init()	AdsManager.init()
Anúncio intermediário ou final carregado	Para o primeiro anúncio em um intervalo, oito segundos antes do horário de 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 está totalmente carregado quando a reprodução do anúncio começa. O pré-carregamento visa melhorar a experiência do usuário, minimizando o tempo necessário para o carregamento do anúncio. Seu objetivo não é oferecer suporte à veiculação de anúncios off-line.

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

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