開始使用 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 (即 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

確保已針對 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 應用程式的主要執行緒中執行接聽程式回呼方法。

設定影片的表面檢視

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

播放串流

因為串流是非同步方式載入，所以在您的應用程式呼叫 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;
     }
}

釋放播放器

當不再使用播放器時，必須呼叫 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 不是安全執行緒。對播放器執行個體進行的所有呼叫都應來自同一執行緒。

SDK 大小

Amazon IVS 播放器 SDK的設計盡可能輕量化。如需 SDK 大小的最新資訊，請參閱版本備註。

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