# 開始使用 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 (即 `libplayercore.so`) 中遇到當機，您可以使用此版本來改進 Firebase Crashlytics 中偵錯報告 (堆疊追蹤) 的品質。向 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 應用程式的主要執行緒中執行接聽程式回呼方法。

## 設定影片的表面檢視
<a name="android-set-surface-view"></a>

如果不使用 `PlayerView`，請將 `SurfaceView` 新增到您的 Android 版面配置以顯示影片。在播放任何影片串流之前，此 `Surface` 必須可用。您可以透過 `SurfaceHolder` 界面存取基礎資料表面，透過呼叫 `getHolder()` 來擷取。(請參閱 Android 開發人員參考中的 [SurfaceView](https://developer.android.com/reference/android/view/SurfaceView.html))。使用 `SurfaceHolder.Callback` 以接收有關表面變更的事件 (請參閱 [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>

因為串流是非同步方式載入，所以在您的應用程式呼叫 `play` 方法開始播放之前，播放器必須處於 `READY` 狀態。使用 `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 不是安全執行緒。對播放器執行個體進行的所有呼叫都應來自同一執行緒。

## SDK 大小
<a name="android-sdk-size"></a>

Amazon IVS 播放器 SDK的設計盡可能輕量化。如需 SDK 大小的最新資訊，請參閱[版本備註](release-notes.md)。

**重要：**在評估大小影響時，Android Studio 產生的 AAB/APK 大小不代表下載到使用者裝置的應用程式大小。Google Play 商店會執行最佳化，以減少應用程式的大小。我們建議您使用 [Android App Bundle](https://developer.android.com/guide/app-bundle)，為各裝置組態提供最佳化的應用程式。