# IVS Android 广播 SDK 入门 \$1 低延迟直播功能
<a name="broadcast-android-getting-started"></a>

本文档将引导您完成 Amazon IVS 低延迟直播功能 Android 广播 SDK 入门所涉及的步骤。

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

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

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

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

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

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

要使用此版本的 SDK，请将以下内容放入您的 Gradle 构建文件中：

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

使用上面一行代替以下一行：

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

### 将符号上传到 Firebase Crashlytics
<a name="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="android-debug-symbols-ll-sizing-apk"></a>

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

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

## 创建事件侦听器
<a name="broadcast-android-create-event-listener"></a>

设置事件侦听器可接收状态更新、设备更改通知、错误和会话音频信息。

```
BroadcastSession.Listener broadcastListener = 
          new BroadcastSession.Listener() {
    @Override
    public void onStateChanged(@NonNull BroadcastSession.State state) {
        Log.d(TAG, "State=" + state);
    }

    @Override
    public void onError(@NonNull BroadcastException exception) {
        Log.e(TAG, "Exception: " + exception);
    }
};
```

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

您的应用必须请求权限才能访问用户摄像头和麦克风。（这并非特定于 Amazon IVS；需要访问摄像头和麦克风的任何应用程序都需要这样做。）

我们在此处检查用户是否已授予权限，如果没有，对他们提出要求：

```
final String[] requiredPermissions =
         { Manifest.permission.CAMERA, Manifest.permission.RECORD_AUDIO };

for (String permission : requiredPermissions) {
    if (ContextCompat.checkSelfPermission(this, permission) 
                != PackageManager.PERMISSION_GRANTED) {
        // If any permissions are missing we want to just request them all.
        ActivityCompat.requestPermissions(this, requiredPermissions, 0x100);
        break;
    }
}
```

在这里，我们得到用户的响应：

```
@Override
public void onRequestPermissionsResult(int requestCode, 
                                      @NonNull String[] permissions,
                                      @NonNull int[] grantResults) {
    super.onRequestPermissionsResult(requestCode,
               permissions, grantResults);
    if (requestCode == 0x100) {
        for (int result : grantResults) {
            if (result == PackageManager.PERMISSION_DENIED) {
                return;
            }
        }
        setupBroadcastSession();
    }
}
```

## 创建广播会话
<a name="broadcast-android-create-session"></a>

广播接口为 `com.amazonaws.ivs.broadcast.BroadcastSession`。使用预设值对它进行初始化，如下所示。如果在初始化过程中出现任何错误（例如配置编解码器失败），则 `BroadcastListener` 将得到错误消息，并且 `broadcastSession.isReady` 将变为 `false`。

**重要提示：**对 Amazon IVS Broadcast SDK for Android 的所有调用*必须*在实例化该开发工具包的线程上进行。*来自不同线程的调用将导致开发工具包抛出致命错误并停止广播*。

```
// Create a broadcast-session instance and sign up to receive broadcast
// events and errors.
Context ctx = getApplicationContext();
broadcastSession = new BroadcastSession(ctx,
                       broadcastListener,
                       Presets.Configuration.STANDARD_PORTRAIT,
                       Presets.Devices.FRONT_CAMERA(ctx));
```

另请参阅[创建广播会话（高级版）](broadcast-android-use-cases.md#broadcast-android-create-session-advanced)。

## 设置 ImagePreviewView 进行预览
<a name="broadcast-android-set-imagepreviewview"></a>

如果要显示活动摄像机设备的预览，请将设备的预览 `ImagePreviewView` 添加到您的视图层次结构。

```
// awaitDeviceChanges will fire on the main thread after all pending devices 
// attachments have been completed
broadcastSession.awaitDeviceChanges(() -> {
    for(Device device: session.listAttachedDevices()) {
        // Find the camera we attached earlier
        if(device.getDescriptor().type == Device.Descriptor.DeviceType.CAMERA) {
            LinearLayout previewHolder = findViewById(R.id.previewHolder);
            ImagePreviewView preview = ((ImageDevice)device).getPreviewView();
            preview.setLayoutParams(new LinearLayout.LayoutParams(
                    LinearLayout.LayoutParams.MATCH_PARENT,
                    LinearLayout.LayoutParams.MATCH_PARENT));
            previewHolder.addView(preview);
        }
    }
});
```

## 开启广播
<a name="broadcast-android-start"></a>

您在 `GetChannel` 操作的 `ingestEndpoint` 响应字段中接收的主机名的前面应为 `rtmps://`，后面为 `/app`。完整 URL 应采用以下格式：`rtmps://{{ ingestEndpoint }}/app`

```
broadcastSession.start(IVS_RTMPS_URL, IVS_STREAMKEY);
```

Android 广播 SDK 仅支持 RTMPS 采集（不支持不安全的 RTMP 采集）。

## 停止广播
<a name="broadcast-android-stop"></a>

```
broadcastSession.stop();
```

## 发布广播会话
<a name="broadcast-android-release-session"></a>

当不再使用广播会话时，*必须调用* `broadcastSession.release()` 方法，以释放库使用的资源。

```
@Override
protected void onDestroy() {
    super.onDestroy();
    previewHolder.removeAllViews();
    broadcastSession.release();
}
```