# 開始使用 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 廣播 SDK 的最新版本)：

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

我們也發布了包含偵錯符號的廣播 SDK Android 版本。如果在 IVS 廣播 SDK 中遇到當機 (即 `libbroadcastcore.so`)，您可以使用此版本來改善 Firebase Crashlytics 中偵錯報告 (堆疊追蹤) 的品質。向 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 廣播 SDK for Android 呼叫都*必須*在 SDK 執行個體化的執行緒上進行。*來自不同執行緒的呼叫將導致 SDK 擲回嚴重錯誤並停止廣播*。

```
// 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();
}
```