Conceitos básicos do SDK do reprodutor para Android do IVS

Este documento descreve as etapas envolvidas ao começar a usar o SDK do reprodutor para Android do Amazon IVS.

Instalar a biblioteca

Para adicionar a biblioteca do player para Android do Amazon IVS ao seu ambiente de desenvolvimento do Android, adicione a biblioteca ao seu arquivo build.gradle do módulo, conforme mostrado aqui (para a versão mais recente do player do Amazon IVS).

repositories {
    mavenCentral()
}
 
dependencies {
     implementation 'com.amazonaws:ivs-player:1.42.0'
}

Como alternativa, para instalar o SDK manualmente, baixe a versão mais recente neste local:

Usar o SDK com símbolos de depuração

Também publicamos uma versão do SDK do reprodutor para Android que inclui símbolos de depuração. Você pode usar essa versão para melhorar a qualidade dos relatórios de depuração (rastreamentos de pilha) no Firebase Crashlytics, caso encontre falhas no SDK do reprodutor do IVS, ou seja, libplayercore.so. Quando você relata essas falhas à equipe do SDK do IVS, os rastreamentos de pilha de maior qualidade facilitam a correção dos problemas.

Para usar esta versão do SDK, em seus arquivos de compilação do Gradle, substitua esta linha:

implementation "com.amazonaws:ivs-player:$version@aar"

por esta:

implementation "com.amazonaws:ivs-player:$version:unstripped@aar"

Upload de símbolos para o Firebase Crashlytics

Certifique-se de que os arquivos de compilação do Gradle estejam configurados para o Firebase Crashlytics. Siga as instruções do Google aqui:

https://firebase.google.com/docs/crashlytics/ndk-reports

Certifique-se de incluir com.google.firebase:firebase-crashlytics-ndk como dependência.

Ao criar a aplicação para lançamento, o plug-in do Firebase Crashlytics deve fazer o upload dos símbolos automaticamente. Para fazer o upload dos símbolos manualmente, execute um dos seguintes comandos:

gradle uploadCrashlyticsSymbolFileRelease

./gradlew uploadCrashlyticsSymbolFileRelease

(Não haverá problema algum se os símbolos forem carregados duas vezes, tanto automática quanto manualmente.)

Impedir que o arquivo .apk de lançamento fique maior

Antes de empacotar o arquivo .apk de lançamento, o plug-in do Gradle para Android tenta automaticamente remover as informações de depuração das bibliotecas compartilhadas (incluindo a biblioteca libplayercore.so do SDK do reprodutor do IVS). No entanto, às vezes isso não acontece. Neste caso, o arquivo .apk pode ficar maior e é possível que você receba uma mensagem de aviso do plug-in do Gradle para Android informando que ele não consegue remover os símbolos de depuração e que está empacotando os arquivos .so da forma como estão. Se isso acontecer, faça o seguinte:

Para obter mais informações, consulte este relatório de problemas.

Crie o player e configure o listener de eventos

A interface do player é com.amazonaws.ivs.player.Player. Inicialize-a como mostrado abaixo:

// Create a player instance
// <this> refers to the current Android Activity
player = Player.Factory.create(this);

// Set up to receive playback events and errors 
player.addListener(this);

Se preferir, inicialize usando PlayerView:

// Create a player instance
// <this> refers to the current Android Activity
PlayerView playerView = new PlayerView(this);
Player player = playerView.getPlayer();
// Set up to receive playback events and errors 
player.addListener(this);

Observação: os métodos de retorno de chamada de listener são executados no thread principal de sua aplicação Android.

Definir a Exibição da superfície para vídeo

Se não estiver usando PlayerView, adicione um SurfaceView ao layout da interface do usuário do Android para exibir um vídeo. Esse Surface deve estar disponível antes de você conseguir reproduzir quaisquer fluxos de vídeo. Você pode acessar a superfície subjacente por meio da interface SurfaceHolder, que é recuperada chamando getHolder(). (Consulte Exibição da superfície na referência do desenvolvedor do Android). Usar a SurfaceHolder.Callback para receber eventos sobre alterações de superfície (consulte SurfaceHolder.Callback).

surfaceView = (SurfaceView) findViewById(R.id.surfaceView);
surfaceView.getHolder().addCallback(this);

@Override
public void surfaceCreated(SurfaceHolder holder) {
   this.surface = holder.getSurface();
   if (player != null) {
       player.setSurface(this.surface);
   }
}

@Override
public void surfaceDestroyed(SurfaceHolder holder) {
   this.surface = null;
   if (player != null) {
       player.setSurface(null);
   }
}

Reproduzir um stream

Como o fluxo é carregado de forma assíncrona, o player deve estar em um estado READY antes que sua aplicação possa chamar o método play para iniciar a reprodução. Usar a interface Player.Listener para determinar quando o player está no estado correto.

Consulte o seguinte código de exemplo:

player.load(Uri.parse(url));

@Override
public void onStateChanged(Player.State state) {
    switch (state) {
        case BUFFERING:
            // player is buffering
            break;
        case READY:
            player.play();
            break;
        case IDLE:
            break;
        case PLAYING:
            // playback started
            break;
     }
}

Liberar o player

O método player.release() deverá ser chamado quando o player não estiver mais sendo usado para liberar os recursos usados pela biblioteca. Normalmente, isso é feito no retorno de chamada onDestroy da atividade ou fragmento que contém o player.

@Override
protected void onDestroy() {
    super.onDestroy();
    player.removeListener(this);
    player.release();
}

Após o método player.release() ser chamado, o player não pode mais ser usado.

Permissões

O SDK do player do Android necessita da seguinte permissão:

<uses-permission android:name="android.permission.INTERNET" />

Além disso, essas permissões opcionais podem melhorar a experiência de reprodução:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Segurança de thread

A API do player não é um thread seguro. Todas as chamadas feitas para uma instância do reprodutor devem ser da mesma thread.

Tamanho do SDK

Os SDKs do Amazon IVS Player foram projetados para serem o mais leve possível. Para obter informações atuais sobre o tamanho do SDK, consulte as Notas de release.

Importante: ao avaliar o impacto do tamanho, o tamanho do AAB/APK produzido pelo Android Studio não representa o tamanho da aplicação baixada no dispositivo do usuário. A Google Play Store realiza otimizações para reduzir o tamanho de sua aplicação. Recomendamos usar Android App Bundles para servir aplicações otimizadas para cada configuração de dispositivo.