Mise en route avec le kit SDK du lecteur Android d’IVS

Ce document vous présente les étapes à suivre pour commencer à utiliser le kit SDK du lecteur Android d’Amazon IVS.

Installer la bibliothèque

Pour ajouter la bibliothèque de lecteur Android Amazon IVS à votre environnement de développement Android, ajoutez la bibliothèque au fichier build.gradle de votre module, comme indiqué ici (pour la dernière version du lecteur Amazon IVS).

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

Vous pouvez également installer le kit SDK manuellement, en téléchargeant la dernière version à partir du lien suivant :

Utilisation du kit SDK avec des symboles de débogage

Nous publions également une version du kit SDK du lecteur Android incluant des symboles de débogage. Vous pouvez utiliser cette version pour améliorer la qualité des rapports de débogage (traces de pile) dans Firebase Crashlytics, en cas de plantages dans le kit SDK du lecteur IVS, par exemple libplayercore.so. Lorsque vous signalez ces plantages à l’équipe SDK IVS, des traces de pile de meilleure qualité facilitent la résolution des problèmes.

Pour utiliser cette version du kit SDK, dans vos fichiers de configuration Gradle, remplacez cette ligne :

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

par ceci :

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

Téléchargement des symboles vers Firebase Crashlytics

Assurez-vous que vos fichiers de configuration Gradle sont bien configurés pour Firebase Crashlytics. Suivez les instructions de Google ici :

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

Veillez à ajouter com.google.firebase:firebase-crashlytics-ndk en tant que dépendance.

Lorsque vous créez votre application en vue de sa publication, le plug-in Firebase Crashlytics devrait automatiquement télécharger les symboles. Pour ce faire, exécutez l’une des commandes suivantes :

gradle uploadCrashlyticsSymbolFileRelease

./gradlew uploadCrashlyticsSymbolFileRelease

(Il n’y a aucun risque si les symboles sont téléchargés deux fois, automatiquement et manuellement.)

Prévention de l’augmentation de la taille du fichier .apk en version finale

Avant de générer le fichier .apk en version finale, le plug-in Android Gradle tente automatiquement de supprimer les informations de débogage des bibliothèques partagées (y compris la bibliothèque libplayercore.so du kit SDK du lecteur IVS). Cependant, cela ne fonctionne pas toujours. Dans ce cas, votre fichier .apk pourrait devenir plus volumineux et vous pourriez recevoir un message d’avertissement du plugin Android Gradle indiquant qu’il est impossible de supprimer les symboles de débogage et qu’il inclut les fichiers .so tels quels. Si cela se produit, procédez comme suit :

Pour plus d’informations, consultez ce problème connu.

Créer le lecteur et configurer l’écouteur d’événement

L’interface du lecteur est com.amazonaws.ivs.player.Player. Initialisez-le comme indiqué ci-dessous :

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

Vous pouvez également l’initialiser en utilisant 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);

Remarque : les méthodes de rappel d’écouteur sont exécutées dans le thread principal de votre application Android.

Définir la vue Surface pour la vidéo

Si vous n’utilisez pas PlayerView, ajoutez SurfaceView à votre interface utilisateur Android pour afficher une vidéo. Cette Surface doit être disponible avant de pouvoir lire des flux vidéo. Vous pouvez accéder à la surface sous-jacente via l’interface SurfaceHolder, qui est récupérée en appelant getHolder(). (Consultez la section SurfaceView dans les références du développeur Android). Utilisez SurfaceHolder.Callback pour recevoir des événements sur les modifications de surface (cf. 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);
   }
}

Lire un flux

Étant donné que le flux est chargé de manière asynchrone, le lecteur doit afficher l’état READY pour que votre application puisse appeler play pour commencer la lecture. Utilisez Player.Listener pour déterminer quand le lecteur est dans le bon état.

Voir l’exemple de code suivant :

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

Libérer le lecteur

La méthode player.release() doit être appelée lorsque le lecteur n’est plus utilisé, pour libérer les ressources utilisées par la bibliothèque. Généralement, cette opération est exécutée dans le rappel onDestroy de l’activité ou du fragment contenant le lecteur.

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

Une fois la méthode player.release() appelée, le lecteur ne peut plus être utilisé.

Autorisations

Le kit SDK du lecteur Android nécessite l’autorisation suivante :

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

En outre, ces autorisations facultatives peuvent améliorer l’expérience de lecture :

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

Sécurité des threads

L’API du lecteur n’est pas thread-safe. Tous les appels effectués vers une instance de lecteur doivent provenir du même fil de discussion.

Taille du kit SDK

Les kits SDK du lecteur Amazon IVS sont conçus pour être aussi légers que possible. Pour plus d’informations sur la taille du kit SDK, consultez les notes de mise à jour.

Important : lors de l’évaluation de l’impact de la taille, la taille de l’AAB/APK produite par Android Studio n’est pas représentative de la taille de votre appli téléchargée sur l’appareil d’un utilisateur. L’App Store effectue des optimisations pour réduire la taille de votre appli. Nous vous recommandons d’utiliser Android App Bundles pour servir des applis optimisées pour chaque configuration d’appareil.