IVS Android 回放器 SDK 入门

本文档将引导您完成 Amazon IVS Android 回放器 SDK 入门所涉及的步骤。

安装库

要将 Amazon IVS Android 播放器库添加到您的 Android 开发环境中，请将该库添加到您模块的 build.gradle 文件（如此处所示，适用于最新版本的 Amazon IVS 播放器）。

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

如要手动安装 SDK，也可从以下位置下载最新版本：

使用带有调试符号的 SDK

我们还发布了包含调试符号的 Android 播放器 SDK 版本。如果在 IVS 播放器 SDK 中遇到崩溃，则可以使用此版本来提高 Firebase Crashlytics 中调试报告（堆栈跟踪）的质量；即 libplayercore.so。当您向 IVS SDK 团队报告这些崩溃时，堆栈跟踪质量越高，修复问题越轻松。

要使用此版本的 SDK，请在 Gradle 构建文件中替换此行：

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

替换为：

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

将符号上传到 Firebase Crashlytics

确保已为 Firebase Crashlytics 设置 Gradle 构建文件。请按照此处的 Google 说明进行操作：

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

请务必将 com.google.firebase:firebase-crashlytics-ndk 作为依赖项包括在内。

在构建要发布的应用程序时，Firebase Crashlytics 插件应自动上传符号。要手动上传符号，请运行以下命令之一：

gradle uploadCrashlyticsSymbolFileRelease

./gradlew uploadCrashlyticsSymbolFileRelease

[如果符号上传两次（自动和手动上传）也无妨。]

防止您的版本 .apk 变得越来越大

在打包版本 .apk 文件之前，Android Gradle 插件会自动尝试从共享库（包括 IVS 播放器 SDK 的 libplayercore.so 库）中剥离调试信息。但是，有时这种情况不会发生。在这种情况下，.apk 文件可能会变大，您可能会收到来自 Android Gradle 插件的警告消息，告知无法剥离调试符号并将按原样打包 .so 文件。如果发生这种情况，则请执行以下操作：

有关更多信息，请参阅此问题报告。

创建播放器并设置事件侦听器

播放器接口是 com.amazonaws.ivs.player.Player。将其初始化，如下所示：

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

或者，通过使用 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);

注意：在 Android 应用程序的主线程中执行侦听器回调方法。

设置视频的 Surface View

如果未使用 PlayerView，请将 SurfaceView 添加到您的 Android UI 布局以显示视频。此 Surface 必须可用，然后才能播放任何视频流。您可以通过 SurfaceHolder 接口访问基础 Surface，该接口可通过调用 getHolder() 进行检索。（请参阅 Android 开发人员参考中的 SurfaceView）。使用 SurfaceHolder.Callback 接收有关 Surface 变化的事件（请参阅 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);
   }
}

播放视频流

由于视频流是异步加载的，因此播放器必须处于 READY 状态，然后您的应用程序才可以调用 play 方法开始播放。使用 Player.Listener 接口来确定播放器何时处于就绪状态。

请看下面的示例代码：

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

释放播放器

当不再使用播放器时，必须调用 player.release() 方法，以释放库使用的资源。通常，这是在播放器的 Activity 或 Fragment 的 onDestroy 回调中完成的。

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

调用 player.release() 方法后，将无法再使用播放器。

权限

Android 播放器开发工具包需要以下权限：

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

此外，这些可选权限还可以改善播放体验：

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

线程安全

播放器 API 不是线程安全的。对播放器实例发起的所有调用都应来自同一个线程。

开发工具包大小

Amazon IVS 播放器开发工具包设计为尽可能轻便。有关开发工具包大小的最新信息，请参阅发布说明。

重要提示：在评估大小影响时，Android Studio 生成的 AAB/APK 的大小并不代表您下载到用户设备的应用程序的大小。Google Play 商店会执行优化以减小应用程序的大小。建议使用 Android 应用程序包为每个设备配置提供优化的应用程序。