O ExoPlayer é um player de mídia no nível de aplicativo para Android. Este guia mostra como você pode usar a extensão ExoPlayer do IMA, que une o SDK de DAI do IMA para Android, para solicitar e reproduzir um stream de mídia com anúncios e conteúdo.
Veja alguns dos benefícios da extensão:
- Simplifica o código necessário para integrar o IMA aos recursos.
- Reduz o tempo de desenvolvimento necessário para atualizar para novas versões do IMA.
A extensão de IMA do ExoPlayer oferece suporte aos protocolos de streaming HLS e DASH. Aqui está um resumo:
Suporte ao stream de extensão do ExoPlayer-IMA | ||
---|---|---|
Transmissões ao vivo | Streams de VOD | |
HLS | ||
DASH |
As transmissões ao vivo do DASH são compatíveis com o ExoPlayer-IMA versão 1.1.0+.
Este guia é baseado no guia
do ExoPlayer e mostra
como criar um app completo e integrar a extensão. Consulte a
ExoPlayerExample
do
GitHub para conferir um exemplo com
um app de exemplo completo.
Pré-requisitos
- Android Studio
- AndroidX Media3 ExoPlayer versão 1.0.0 ou mais recente para compatibilidade com a DAI.
Criar um novo projeto do Android Studio
Para criar seu projeto do Android Studio, siga estas etapas:
- Inicie o Android Studio.
- Selecione Iniciar um novo projeto do Android Studio.
- Na página Choose your project, selecione o modelo No Activity.
- Clique em Próxima.
Na página Configurar seu projeto, dê um nome ao projeto e selecione Java para a linguagem.
Selecione Concluir.
Adicionar a extensão de IMA do ExoPlayer ao seu projeto
Adicione importações da extensão para o arquivo build.gradle do aplicativo na seção dependencies
.
Configure seu app e ative o
multidex. Isso é necessário devido
ao tamanho da extensão e necessário para apps com minSdkVersion
definido
como Android 4.4W (nível
20 da API) ou anterior.
Veja um exemplo:
app/build.gradle
android { ... defaultConfig { applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp" minSdkVersion 19 targetSdkVersion 34 multiDexEnabled true versionCode 1 versionName "1.0" } ... } dependencies { implementation 'androidx.multidex:multidex:2.0.1' implementation 'androidx.media3:media3-ui:1.1.1' implementation 'androidx.media3:media3-exoplayer:1.1.1' implementation 'androidx.media3:media3-exoplayer-hls:1.1.1' implementation 'androidx.media3:media3-exoplayer-dash:1.1.1' // Adding the ExoPlayer IMA extension for ads will also include the IMA // SDK as a dependency. implementation 'androidx.media3:media3-exoplayer-ima:1.1.1' }
Adicione as permissões de usuário exigidas pelo SDK do IMA para solicitar anúncios:
app/src/main/AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?> <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.project name"> <!-- Required permissions for the IMA SDK --> <uses-permission android:name="android.permission.INTERNET"/> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/> ... </manifest>
Adicionar declarações de intent
Caso seu app seja direcionado ao Android 11 (nível 30 da API) ou versões mais recentes, as versões atuais e recentes do SDK do IMA exigem uma declaração explícita de intenção para abrir links da Web. Adicione o snippet a seguir ao arquivo de manifesto do seu app para ativar os cliques nos anúncios (os usuários clicam no botão Saiba mais).
<?xml version="1.0" encoding="utf-8"?> <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.project name"> ... </application> <queries> <intent> <action android:name="android.intent.action.VIEW" /> <data android:scheme="https" /> </intent> <intent> <action android:name="android.intent.action.VIEW" /> <data android:scheme="http" /> </intent> </queries> </manifest>
Configurar a interface do ExoPlayer
Crie o objeto PlayerView
que será usado pelo ExoPlayer.
Altere androidx.constraintlayout.widget.ConstraintLayout
para uma
LinearLayout
, que é recomendada para a extensão de IMA do ExoPlayer.
Veja um exemplo:
app/src/main/res/layout/activity_my.xml
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools" android:background="@android:color/black" android:id="@+id/container" android:layout_width="match_parent" android:layout_height="match_parent" android:orientation="vertical" tools:context=".MyActivity" tools:ignore="MergeRootFrame"> <androidx.media3.ui.PlayerView android:id="@+id/player_view" android:layout_width="match_parent" android:layout_height="match_parent" /> </LinearLayout>
Adicionar os parâmetros de stream
Acesse a página de amostra de stream do IMA (em inglês) para conferir exemplos de recursos de stream para testar seu projeto. Consulte também a seção do Ad Manager sobre DAI para ver informações sobre como configurar seus próprios streams.
Esta etapa demonstra a configuração de uma transmissão ao vivo, mas a extensão de IMA do ExoPlayer também oferece suporte a streams de VOD da DAI. Consulte a etapa para streams de vídeo on demand (VOD) e veja quais mudanças seu app precisa para lidar com streams de VOD.
Importar a extensão de IMA do ExoPlayer
Adicione as instruções de importação para a extensão do ExoPlayer.
Adicione as variáveis particulares abaixo a MyActivity.java
:
PlayerView
ExoPlayer
ImaServerSideAdInsertionMediaSource.AdsLoader
ImaServerSideAdInsertionMediaSource.AdsLoader.State
Adicione a chave do recurso HLS da transmissão HLS de Big Buck Bunny (ao vivo) para testar com essa transmissão. Mais transmissões estão disponíveis para teste na página de stream de amostra do IMA.
Crie uma constante KEY_ADS_LOADER_STATE
para salvar e recuperar o estado
AdsLoader
.
Veja um exemplo:
app/src/main/java/com/example/project name/MyActivity.java
import static androidx.media3.common.C.CONTENT_TYPE_HLS; import android.app.Activity; import android.net.Uri; import android.os.Bundle; import androidx.annotation.Nullable; import androidx.annotation.OptIn; import androidx.media3.common.MediaItem; import androidx.media3.common.util.Util; import androidx.media3.datasource.DataSource; import androidx.media3.datasource.DefaultDataSource; import androidx.media3.exoplayer.ExoPlayer; import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionMediaSource; import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionUriBuilder; import androidx.media3.exoplayer.source.DefaultMediaSourceFactory; import androidx.media3.exoplayer.util.EventLogger; import androidx.media3.ui.PlayerView; import androidx.multidex.MultiDex; ... public class MyActivity extends Activity { private static final String KEY_ADS_LOADER_STATE = "ads_loader_state"; private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ"; private PlayerView playerView; private ExoPlayer player; private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader; private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState; }
Criar uma instância adsLoader
Substitua o método onCreate
para encontrar o PlayerView
e procurar um
AdsLoader.State
salvo,
que pode ser usado ao iniciar o objeto adsLoader
.
Além disso, ative o multidex, se necessário para a contagem de métodos do app e minSdkVersion
,
conforme explicado na
etapa 2.
Veja um exemplo:
app/src/main/java/com/example/project name/MyActivity.java
... public class MyActivity extends Activity { private static final String KEY_ADS_LOADER_STATE = "ads_loader_state"; private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ"; private PlayerView playerView; private ExoPlayer player; private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader; private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState; @Override protected void onCreate(@Nullable Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_my); MultiDex.install(this); playerView = findViewById(R.id.player_view); // Checks if there is a saved AdsLoader state to be used later when // initiating the AdsLoader. if (savedInstanceState != null) { Bundle adsLoaderStateBundle = savedInstanceState.getBundle(KEY_ADS_LOADER_STATE); if (adsLoaderStateBundle != null) { adsLoaderState = ImaServerSideAdInsertionMediaSource.AdsLoader.State.CREATOR.fromBundle( adsLoaderStateBundle); } } } }
Adicionar métodos para inicializar o player
Adicione um método para inicializar o player e faça o seguinte:
- Crie uma instância
AdsLoader
. - Crie o
ExoPlayer
. - Crie um
MediaItem
com a chave de recurso da transmissão ao vivo. - Defina o
MediaItem
como o player.
Veja um exemplo:
app/src/main/java/com/example/project name/MyActivity.java
public class MyActivity extends Activity { ... // Create a server side ad insertion (SSAI) AdsLoader. private ImaServerSideAdInsertionMediaSource.AdsLoader createAdsLoader() { ImaServerSideAdInsertionMediaSource.AdsLoader.Builder adsLoaderBuilder = new ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(this, playerView); // Attempt to set the AdsLoader state if available from a previous session. if (adsLoaderState != null) { adsLoaderBuilder.setAdsLoaderState(adsLoaderState); } return adsLoaderBuilder.build(); } private void initializePlayer() { adsLoader = createAdsLoader(); // Set up the factory for media sources, passing the ads loader. DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this); DefaultMediaSourceFactory mediaSourceFactory = new DefaultMediaSourceFactory(dataSourceFactory); // MediaSource.Factory to create the ad sources for the current player. ImaServerSideAdInsertionMediaSource.Factory adsMediaSourceFactory = new ImaServerSideAdInsertionMediaSource.Factory(adsLoader, mediaSourceFactory); // 'mediaSourceFactory' is an ExoPlayer component for the DefaultMediaSourceFactory. // 'adsMediaSourceFactory' is an ExoPlayer component for a MediaSource factory for IMA server // side inserted ad streams. mediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory); // Create an ExoPlayer and set it as the player for content and ads. player = new ExoPlayer.Builder(this).setMediaSourceFactory(mediaSourceFactory).build(); playerView.setPlayer(player); adsLoader.setPlayer(player); // Build an IMA SSAI media item to prepare the player with. Uri ssaiLiveUri = new ImaServerSideAdInsertionUriBuilder() .setAssetKey(SAMPLE_ASSET_KEY) .setFormat(CONTENT_TYPE_HLS) // Use CONTENT_TYPE_DASH for dash streams. .build(); // Create the MediaItem to play, specifying the stream URI. MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiLiveUri); // Prepare the content and ad to be played with the ExoPlayer. player.setMediaItem(ssaiMediaItem); player.prepare(); // Set PlayWhenReady. If true, content and ads will autoplay. player.setPlayWhenReady(false); } }
Adicionar um método para liberar o player
Adicione um método para liberar o player nesta sequência:
- Defina as referências do player como nulas e libere os recursos dele.
- Libere o estado da
adsLoader
.
app/src/main/java/com/example/project name/MyActivity.java
public class MyActivity extends Activity { ... private void releasePlayer() { // Set the player references to null and release the player's resources. playerView.setPlayer(null); player.release(); player = null; // Release the adsLoader state so that it can be initiated again. adsLoaderState = adsLoader.release(); }
Processar eventos do jogador
Por fim, crie callbacks para os eventos de ciclo de vida da atividade para processar a reprodução do fluxo.
Para oferecer suporte ao SDK do Android versão 24 ou mais recente:
Para oferecer suporte a versões do SDK do Android anteriores à 24:
- onResume()
- onPause()
onStart()
e onResume()
são mapeados para playerView.onResume()
, e onStop()
e onPause()
são mapeados para playerView.onPause()
.
Esta etapa também usa o evento
onSaveInstanceState()
para tentar salvar o adsLoaderState
.
app/src/main/java/com/example/project name/MyActivity.java
public class MyActivity extends Activity { ... @Override public void onStart() { super.onStart(); if (Util.SDK_INT > 23) { initializePlayer(); if (playerView != null) { playerView.onResume(); } } } @Override public void onResume() { super.onResume(); if (Util.SDK_INT <= 23 || player == null) { initializePlayer(); if (playerView != null) { playerView.onResume(); } } } @Override public void onPause() { super.onPause(); if (Util.SDK_INT <= 23) { if (playerView != null) { playerView.onPause(); } releasePlayer(); } } @Override public void onStop() { super.onStop(); if (Util.SDK_INT > 23) { if (playerView != null) { playerView.onPause(); } releasePlayer(); } } @Override public void onSaveInstanceState(Bundle outState) { // Attempts to save the AdsLoader state to handle app backgrounding. if (adsLoaderState != null) { outState.putBundle(KEY_ADS_LOADER_STATE, adsLoaderState.toBundle()); } } ... }
Configuração da transmissão de VOD (opcional)
Se o seu app precisar reproduzir conteúdo VOD com anúncios, faça o seguinte:
- Adicione
CMS ID
eVideo ID
a uma transmissão de teste de VOD. - Crie um URI SSAI VOD usando
ImaServerSideAdInsertionUriBuilder()
. - Use esse novo URI como o item de mídia do player.
app/src/main/java/com/example/project name/MyActivity.java
public class MyActivity extends Activity { private static final String KEY_ADS_LOADER_STATE = "ads_loader_state"; private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ"; private static final String SAMPLE_CMS_ID = "2528370"; private static final String SAMPLE_VIDEO_ID = "tears-of-steel"; ... private void initializePlayer() { ... Uri ssaiVodUri = new ImaServerSideAdInsertionUriBuilder() .setContentSourceId(SAMPLE_CMS_ID) .setVideoId(SAMPLE_VIDEO_ID) .setFormat(CONTENT_TYPE_HLS) .build(); // Create the MediaItem to play, specifying the stream URI. MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiVodUri); // Prepare the content and ad to be played with the ExoPlayer. player.setMediaItem(ssaiMediaItem); player.prepare(); // Set PlayWhenReady. If true, content and ads will autoplay. player.setPlayWhenReady(false); }
Pronto! Agora você está solicitando e reproduzindo um stream de mídia com a extensão do ExoPlayer do IMA. Confira os exemplos de DAI do Android no GitHub (link em inglês) para ver o código completo.