# IVS Android 回放器 SDK 入门
<a name="android-getting-started"></a>

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

## 安装库
<a name="android-install"></a>

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

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

如要手动安装 SDK，也可从以下位置下载最新版本：
+ [https://search.maven.org/artifact/com.amazonaws/ivs-player](https://search.maven.org/artifact/com.amazonaws/ivs-player)

## 使用带有调试符号的 SDK
<a name="player-android-using-debug-symbols-ll"></a>

我们还发布了包含调试符号的 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
<a name="player-android-debug-symbols-ll-firebase-crashlytics"></a>

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

[https://firebase.google.com/docs/crashlytics/ndk-reports](https://firebase.google.com/docs/crashlytics/ndk-reports)

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

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

```
gradle uploadCrashlyticsSymbolFileRelease
```

```
./gradlew uploadCrashlyticsSymbolFileRelease
```

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

### 防止您的版本 .apk 变得越来越大
<a name="player-android-debug-symbols-ll-sizing-apk"></a>

在打包版本 `.apk` 文件之前，Android Gradle 插件会自动尝试从共享库（包括 IVS 播放器 SDK 的 `libplayercore.so` 库）中剥离调试信息。但是，有时这种情况不会发生。在这种情况下，`.apk` 文件可能会变大，您可能会收到来自 Android Gradle 插件的警告消息，告知无法剥离调试符号并将按原样打包 `.so` 文件。如果发生这种情况，则请执行以下操作：
+ 安装 Android NDK。任何最新版本都可以使用。
+ 将 `ndkVersion <your_installed_ndk_version_number>` 添加到应用程序的 `build.gradle` 文件中。即使您的应用程序本身不包含原生代码，也要这样做。

有关更多信息，请参阅此[问题报告](https://issuetracker.google.com/issues/353554169)。

## 创建播放器并设置事件侦听器
<a name="android-create-player"></a>

播放器接口是 `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
<a name="android-set-surface-view"></a>

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

## 播放视频流
<a name="android-play-stream"></a>

由于视频流是异步加载的，因此播放器必须处于 `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;
     }
}
```

## 释放播放器
<a name="android-release-player"></a>

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

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

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

## 权限
<a name="android-permissions"></a>

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" />
```

## 线程安全
<a name="android-thread-safety"></a>

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

## 开发工具包大小
<a name="android-sdk-size"></a>

Amazon IVS 播放器开发工具包设计为尽可能轻便。有关开发工具包大小的最新信息，请参阅[发布说明](release-notes.md)。

**重要提示：**在评估大小影响时，Android Studio 生成的 AAB/APK 的大小并不代表您下载到用户设备的应用程序的大小。Google Play 商店会执行优化以减小应用程序的大小。建议使用 [Android 应用程序包](https://developer.android.com/guide/app-bundle)为每个设备配置提供优化的应用程序。