# 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.50.0' } ``` In alternativa, per installare manualmente l'SDK, scaricare la versione più recente da questo percorso: + [https://search.maven.org/artifact/com.amazonaws/ivs-player](https://search.maven.org/artifact/com.amazonaws/ivs-player) ## 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](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: + Installa un NDK per Android. Va bene qualsiasi versione recente. + Aggiungi `ndkVersion ` al file `build.gradle` dell'applicazione. Fallo anche se l'applicazione non contiene codice nativo. Per ulteriori informazioni, consulta questo [report sul problema](https://issuetracker.google.com/issues/353554169). ## 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 // 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 // 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](https://developer.android.com/reference/android/view/SurfaceView.html) nella documentazione di riferimento per sviluppatori Android). Utilizzare `SurfaceHolder.Callback` per ricevere eventi sulle modifiche di superficie (consultare [SurfaceHolder.callback](https://developer.android.com/reference/android/view/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: ``` ``` Inoltre, queste autorizzazioni facoltative possono migliorare l'esperienza di riproduzione: ``` ``` ## 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](release-notes.md). **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](https://developer.android.com/guide/app-bundle) per distribuire app ottimizzate per ogni configurazione del dispositivo.