Guida introduttiva all'SDK IVS Player per Android

Questo documento illustra i passaggi necessari per iniziare a utilizzare l'SDK Amazon IVS Player su Android.

Installare la libreria

Per aggiungere la libreria del lettore Amazon IVS per Android al proprio ambiente di sviluppo Android, aggiungere la libreria al file build.gradle del modulo come mostrato di seguito (per l'ultima versione dell'Amazon IVS Player).

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

In alternativa, per installare manualmente l'SDK, scaricare la versione più recente da questo percorso:

Utilizzo dell'SDK con i simboli di debug

Pubblichiamo anche una versione dell'SDK del lettore Android che include i simboli di debug. È possibile utilizzare questa versione per migliorare la qualità dei report di debug (tracce dello stack) in Firebase Crashlytics se si verificano arresti anomali nell'SDK del lettore IVS, ad esempio libplayercore.so. Quando segnali questi arresti anomali al team dell'SDK di IVS, le tracce dello stack di qualità superiore facilitano la risoluzione dei problemi.

Per utilizzare questa versione dell'SDK, nei tuoi file di build di Gradle, sostituisci questa riga:

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

con questa:

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

Caricamento dei simboli in Firebase Crashlytics

Assicurati che i tuoi file di build Gradle siano configurati per Firebase Crashlytics. Segui le istruzioni di Google qui:

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

Assicurati di includere com.google.firebase:firebase-crashlytics-ndk come dipendenza.

Quando crei l'app per il rilascio, il plug-in Firebase Crashlytics dovrebbe caricare i simboli automaticamente. Per caricare i simboli manualmente, esegui uno dei comandi seguenti:

gradle uploadCrashlyticsSymbolFileRelease

./gradlew uploadCrashlyticsSymbolFileRelease

Non è un problema se i simboli vengono caricati due volte, automaticamente e manualmente.

Impedire che .apk Release diventi più grande

Prima di impacchettare il file .apk di rilascio, il plug-in Android Gradle tenta automaticamente di rimuovere le informazioni di debug dalle librerie condivise (inclusa la libreria libplayercore.so dell'SDK del lettore IVS). Tuttavia, a volte ciò non accade. In questo caso, il file .apk potrebbe diventare più grande e si potrebbe ricevere un messaggio di avviso dal plug-in Android Gradle che indica che non è in grado di rimuovere i simboli di debug e sta impacchettando i file .so così come sono. In tal caso, segui questa procedura:

Per ulteriori informazioni, consulta questo report sul problema.

Configurare il lettore e impostare il listener di eventi

L'interfaccia del lettore è com.amazonaws.ivs.player.Player. Inizializzare come illustrato di seguito:

// 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);

In alternativa, inizializzare utilizzando 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);

Nota: i metodi di callback del listener vengono eseguiti nel thread principale dell'applicazione Android.

Impostare la visualizzazione della superficie per il video

Se non si utilizza una PlayerView aggiungere una SurfaceView al layout dell'interfaccia utente Android per la visualizzazione di un video. Questa Surface deve essere disponibile prima di poter riprodurre qualsiasi flusso video. Esiste la possibilità di accedere alla superficie sottostante tramite l'interfaccia SurfaceHolder, che viene recuperata attraverso la chiamata getHolder(). (Consultare SurfaceView nella documentazione di riferimento per sviluppatori Android). Utilizzare SurfaceHolder.Callback per ricevere eventi sulle modifiche di superficie (consultare 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);
   }
}

Riprodurre un flusso

Poiché il flusso viene caricato in modo asincrono, il lettore deve trovarsi in uno stato READY prima che l'applicazione possa richiamare il metodo play per avviare la riproduzione. Utilizzare l'interfaccia Player.Listener per determinare quando il lettore è nello stato corretto.

Consultare il seguente codice di esempio:

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;
     }
}

Rilascio del lettore

Il metodo player.release() deve essere invocato quando il lettore non è più in uso, per liberare le risorse utilizzate dalla biblioteca. In genere ciò può essere fatto nel callback onDestroy dell'attività o frammento contenente il lettore.

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

Dopo il richiamo del metodo player.release(), il lettore non può più essere utilizzato.

Autorizzazioni

L'SDK del lettore per Android richiede la seguente autorizzazione:

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

Inoltre, queste autorizzazioni facoltative possono migliorare l'esperienza di riproduzione:

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

Sicurezza del thread

L'API del lettore non è thread-safe. Tutte le chiamate effettuate a un'istanza del lettore devono provenire dallo stesso thread.

Dimensione dell'SDK

Gli SDK Amazon IVS Player sono progettati per essere il più leggeri possibile. Per informazioni aggiornate sulle dimensioni dell'SDK, consultare Note di rilascio.

Importante: quando si valuta l'impatto delle dimensioni, la dimensione dell'AAB/APK prodotto da Android Studio non è rappresentativa della dimensione dell'app scaricata sul dispositivo di un utente. Google Play Store esegue ottimizzazioni per ridurre le dimensioni della propria app. Consigliamo di utilizzare Bundle di app Android per distribuire app ottimizzate per ogni configurazione del dispositivo.