# 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.50.0'
}
```
または、SDK を手動でインストールするには、次の場所から最新バージョンをダウンロードします。
+ [https://search.maven.org/artifact/com.amazonaws/ivs-player](https://search.maven.org/artifact/com.amazonaws/ivs-player)
## デバッグ情報を含む 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](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 ` をアプリケーションの `build.gradle` ファイルに追加します。アプリケーション自体にネイティブコードが含まれていない場合でも、これを行います。
詳細については、「[問題レポート](https://issuetracker.google.com/issues/353554169)」を参照してください。
## プレイヤーの作成とイベントリスナーのセットアップ
プレイヤーのインターフェイスは `com.amazonaws.ivs.player.Player` です。以下に示すように、インターフェイスを初期化します。
```
// Create a player instance
// 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
// 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](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);
}
}
```
## ストリームを再生する
ストリームは非同期で読み込まれるため、アプリケーションが `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 には、次のアクセス許可が必要です。
```
```
さらに、これらのオプションのアクセス許可により、再生体験を向上させることができます。
```
```
## スレッドセーフ
プレイヤー API はスレッドセーフではありません。プレイヤーインスタンスへのすべての呼び出しは、同じスレッドからのものである必要があります。
## SDK サイズ
Amazon IVS Player SDK は、可能な限りサイズが軽量になるように設計されています。SDK サイズに関する最新情報については、[リリースノート](release-notes.md)を参照してください。
**重要:**サイズへの影響を評価する場合、Android Studio で生成した AAB/APK のサイズは、ユーザーのデバイスにダウンロードしたアプリのサイズとは異なりますのでご注意ください。Google Play ストアでは、アプリのサイズを小さくするための最適化が行われています。を使用することをお勧めします。[Android App Bundle](https://developer.android.com/guide/app-bundle) を使用して、デバイス設定ごとに最適化されたアプリを提供します。