IVS Android Player SDK の開始方法 - Amazon IVS
ライブラリのインストールデバッグ情報を含む SDK の使用プレイヤーの作成とイベントリスナーのセットアップ動画の SurfaceView を設定する。ストリームを再生するプレイヤーを解放するアクセス許可スレッドセーフSDK サイズ

IVS Android Player SDK の開始方法

このドキュメントでは、Amazon IVS Android Player SDK の使用を開始するための手順について説明します。

ライブラリのインストール

Amazon IVS Android プレイヤーライブラリを Android 開発環境に追加するには、ライブラリを以下に示すモジュールの build.gradleファイル (最新バージョンの Amazon IVS Player 用) に追加します。

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

または、SDK を手動でインストールするには、次の場所から最新バージョンをダウンロードします。

デバッグ情報を含む SDK の使用

また、デバッグ情報を含む Android Player 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 へのシンボルのアップロード

Gradle ビルドファイルが Firebase Crashlytics 用に設定されていることを確認します。以下の Google の指示に従ってください。

https://firebase.google.com/docs/crashlytics/ndk-reports

com.google.firebase:firebase-crashlytics-ndk を依存関係として必ず含めてください。

リリース用にアプリを構築する場合、Firebase Crashlytics プラグインは情報を自動的にアップロードするはずです。情報を手動でアップロードするには、次のいずれかを実行します。

gradle uploadCrashlyticsSymbolFileRelease
./gradlew uploadCrashlyticsSymbolFileRelease

(情報が自動と手動の両方で 2 回アップロードされても問題ありません)。

Release .apk の肥大化を防ぐ

リリース .apk ファイルをパッケージ化する前に、Android Gradle Plugin は共有ライブラリ (IVS プレーヤー SDK の libplayercore.so ライブラリを含む) からデバッグ情報を自動的に削除しようとします。ただし、これはときに動作しないことがあります。その場合、.apk ファイルが肥大化し、Android Gradle プラグインから、「デバッグ情報を削除できず、そのまま .so ファイルをパッケージ化している」という警告メッセージが表示される可能性があります。このような場合は、以下のことを試してみます。

  • Android NDK をインストールします。すべての最新バージョンが機能します。

  • ndkVersion <your_installed_ndk_version_number> をアプリケーションの build.gradle ファイルに追加します。アプリケーション自体にネイティブコードが含まれていない場合でも、これを行います。

詳細については、「問題レポート」を参照してください。

プレイヤーの作成とイベントリスナーのセットアップ

プレイヤーのインターフェイスは 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 アプリケーションのメインスレッドで、リスナーコールバックメソッドが実行されます。

動画の SurfaceView を設定する。

PlayerView を使用しない場合、SurfaceView を Android UI レイアウトに追加して、動画を表示できます。この Surface は、Video Streams 再生前に利用可能である必要があります。基本サーフェスへは、getHolder() の呼び出しによって取得される SurfaceHolder インターフェイスからアクセスできます。(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() メソッドは、プレイヤーが使用されなくなったときに呼び出され、ライブラリによって使用されるリソースを解放する必要があります。通常、これはプレイヤーを含むアクティビティまたはフラグメントの onDestroy コールバックで行われます。

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

player.release() メソッドの呼び出し後、プレイヤーは使用できなくなります。

アクセス許可

Android Player SDK には、次のアクセス許可が必要です。

<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 Player SDK は、可能な限りサイズが軽量になるように設計されています。SDK サイズに関する最新情報については、リリースノートを参照してください。

重要:サイズへの影響を評価する場合、Android Studio で生成した AAB/APK のサイズは、ユーザーのデバイスにダウンロードしたアプリのサイズとは異なりますのでご注意ください。Google Play ストアでは、アプリのサイズを小さくするための最適化が行われています。を使用することをお勧めします。Android App Bundle を使用して、デバイス設定ごとに最適化されたアプリを提供します。