アセット配信を統合する（ネイティブ）

このガイドの手順に沿って、C / C++ コードでアプリのアセットパックにアクセスします。

統合コードのサンプルは GitHub で入手できます。

ネイティブ向けのビルド

プロジェクトの Android App Bundle に Play Asset Delivery を組み込む手順は次のとおりです。この手順で Android Studio を使用する必要はありません。

プロジェクトの build.gradle ファイル内の Android Gradle プラグインのバージョンを 4.0.0 以降に更新します。
プロジェクトの最上位ディレクトリに、Asset Pack のディレクトリを作成します。このディレクトリ名は Asset Pack 名として使用されます。Asset Pack 名の先頭は英字にしてください。その後には、英字、数字、アンダースコアのみ使用できます。

Asset Pack のディレクトリに build.gradle ファイルを作成し、下記のコードを入力します。Asset Pack の名前と配信タイプを 1 つだけ指定します。

// In the asset pack’s build.gradle file:
plugins {
    id 'com.android.asset-pack'
}

assetPack {
    packName = "asset-pack-name" // Directory name for the asset pack
    dynamicDelivery {
        deliveryType = "[ install-time | fast-follow | on-demand ]"
    }
}

プロジェクトのアプリの build.gradle ファイルで、下記のように、プロジェクト内の各 Asset Pack の名前を追加します。
```
// In the app build.gradle file:
android {
    ...
    assetPacks = [":asset-pack-name", ":asset-pack2-name"]
}
```
プロジェクトの settings.gradle ファイルに、下記のように、プロジェクト内のすべての Asset Pack をインクルードします。
```
// In the settings.gradle file:
include ':app'
include ':asset-pack-name'
include ':asset-pack2-name'
```
Asset Pack のディレクトリにサブディレクトリ src/main/assets を作成します。
アセットを src/main/assets ディレクトリに配置します。ここでもサブディレクトリを作成できます。アプリのディレクトリ構造は次のようになります。
- build.gradle
- settings.gradle
- app/
- asset-pack-name/build.gradle
- asset-pack-name/src/main/assets/your-asset-directories
Gradle を使用して Android App Bundle をビルドします。生成された App Bundle のルートレベルのディレクトリには、以下が含まれるようになりました。
- asset-pack-name/manifest/AndroidManifest.xml: Asset Pack の識別子と配信モードを設定します
- asset-pack-name/assets/your-asset-directories: Asset Pack の一部として配信されるすべてのアセットを含むディレクトリです
Gradle は各 Asset Pack のマニフェストを生成し、assets/ ディレクトリを出力してくれます。
（省略可）さまざまなテクスチャ圧縮形式をサポートするように App Bundle を構成します。

Play Asset Delivery Library と統合する

アクセスするアセットパックの配信タイプに応じて、この API を実装します。Asset Pack にアクセスする手順を次のフローチャートに示します。

Asset Pack のネイティブコードのフロー図

図 1:アセットパックへのアクセスのフロー図

Play Core Native SDK には、アセットパックのリクエスト、ダウンロードの管理、アセットへのアクセスのための C ヘッダーファイル play/asset_pack.h が用意されています。

Play Core Native SDK 用に開発環境をセットアップする

Play Core Native SDKのダウンロード

ダウンロードする前に、次の利用規約に同意する必要があります。

利用規約

最終更新日: 2020 年 9 月 24 日

Play Core ソフトウェア開発キットを使用することにより、Google API 利用規約（「API 利用規約」）に加えて、本規約に同意したことになります。各規約の間に矛盾がある場合は、本規約が API 利用規約よりも優先されます。本規約と API 利用規約をよくお読みください。
本規約において、「API」とは Google の API、その他のデベロッパー向けサービス、および関連するソフトウェア（あらゆる再配布可能コードを含む）を意味します。
「再配布可能コード」とは、API を呼び出す Google 提供のオブジェクトコードまたはヘッダーファイルを指します。
本規約および API 利用規約の規定に従い、API クライアントの一部として含める形でのみ、再配布可能コードをコピーして配布することができます。Google とそのライセンサーは、再配布可能コードとそれに含まれる一切の権利、権原、および利益（すべての知的財産権とその他の所有権を含む）を保有します。デベロッパーは、再配布可能コードの修正、翻訳、派生物の作成をしてはなりません。
Google は、通知を行い、Play Core ソフトウェア開発キットの使用を拒否する機会を提供したうえで、いつでも本規約を変更することができます。Google は、本規約の変更の通知を https://developer.android.com/guide/playcore/license に掲載します。変更が遡って適用されることはありません。

上記の利用規約を読んだうえで利用規約に同意します。

ダウンロードする: Play Core Native SDK

play-core-native-sdk-1.11.1.zip

次のいずれかの操作を行います。
- Android Studio バージョン 4.0 以降をインストールし、SDK Manager UI を使用して、Android SDK Platform バージョン 10.0（API レベル 29）をインストールします。
- Android SDK コマンドラインツールをインストールし、sdkmanager を使用して Android SDK Platform バージョン 10.0（API レベル 29）をインストールする。
Android Studio をネイティブ開発で使用できるようにするため、SDK Manager を使用して最新の CMake と Android Native Development Kit（NDK）をインストールします。ネイティブプロジェクトの作成やインポートの詳細については、NDK のスタートガイドをご覧ください。

zip ファイルをダウンロードして、プロジェクトと同じ場所に展開します。

ダウンロードリンク	サイズ	SHA-256 チェックサム
	52.4 MB	35b25bd1d410a0e251983d8d186afb48bba62aa71c44b4c8698677f5622393e7

アプリの build.gradle ファイルを以下のように更新します。

Groovy

    // App build.gradle

    plugins {
      id 'com.android.application'
    }

    // Define a path to the extracted Play Core SDK files.
    // If using a relative path, wrap it with file() since CMake requires absolute paths.
    def playcoreDir = file('../path/to/playcore-native-sdk')

    android {
        defaultConfig {
            ...
            externalNativeBuild {
                cmake {
                    // Define the PLAYCORE_LOCATION directive.
                    arguments "-DANDROID_STL=c++_static",
                              "-DPLAYCORE_LOCATION=$playcoreDir"
                }
            }
            ndk {
                // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
                abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
            }
        }
        buildTypes {
            release {
                // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
                proguardFile '$playcoreDir/proguard/common.pgcfg'
                proguardFile '$playcoreDir/proguard/gms_task.pgcfg'
                proguardFile '$playcoreDir/proguard/per-feature-proguard-files'
                ...
            }
            debug {
                ...
            }
        }
        externalNativeBuild {
            cmake {
                path 'src/main/CMakeLists.txt'
            }
        }
    }

    dependencies {
        // Import these feature-specific AARs for each Google Play Core library.
        implementation 'com.google.android.play:app-update:2.0.0'
        implementation 'com.google.android.play:asset-delivery:2.0.0'
        implementation 'com.google.android.play:integrity:1.0.1'
        implementation 'com.google.android.play:review:2.0.0'

        // Import these common dependencies.
        implementation 'com.google.android.gms:play-services-tasks:18.0.2'
        implementation files("$playcoreDir/playcore-native-metadata.jar")
        ...
    }

Kotlin

// App build.gradle

plugins {
    id("com.android.application")
}

// Define a path to the extracted Play Core SDK files.
// If using a relative path, wrap it with file() since CMake requires absolute paths.
val playcoreDir = file("../path/to/playcore-native-sdk")

android {
    defaultConfig {
        ...
        externalNativeBuild {
            cmake {
                // Define the PLAYCORE_LOCATION directive.
                arguments += listOf("-DANDROID_STL=c++_static", "-DPLAYCORE_LOCATION=$playcoreDir")
            }
        }
        ndk {
            // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
            abiFilters.clear()
            abiFilters += listOf("armeabi-v7a", "arm64-v8a", "x86", "x86_64")
        }
    }
    buildTypes {
        release {
            // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
            proguardFile("$playcoreDir/proguard/common.pgcfg")
            proguardFile("$playcoreDir/proguard/gms_task.pgcfg")
            proguardFile("$playcoreDir/proguard/per-feature-proguard-files")
            ...
        }
        debug {
            ...
        }
    }
    externalNativeBuild {
        cmake {
            path = "src/main/CMakeLists.txt"
        }
    }
}

dependencies {
    // Import these feature-specific AARs for each Google Play Core library.
    implementation("com.google.android.play:app-update:2.0.0")
    implementation("com.google.android.play:asset-delivery:2.0.0")
    implementation("com.google.android.play:integrity:1.0.1")
    implementation("com.google.android.play:review:2.0.0")

    // Import these common dependencies.
    implementation("com.google.android.gms:play-services-tasks:18.0.2")
    implementation(files("$playcoreDir/playcore-native-metadata.jar"))
    ...
}

アプリの CMakeLists.txt ファイルを以下のように更新します。

cmake_minimum_required(VERSION 3.6)

...

# Add a static library called “playcore” built with the c++_static STL.
include(${PLAYCORE_LOCATION}/playcore.cmake)
add_playcore_static_library()

// In this example “main” is your native code library, i.e. libmain.so.
add_library(main SHARED
        ...)

target_include_directories(main PRIVATE
        ${PLAYCORE_LOCATION}/include
        ...)

target_link_libraries(main
        android
        playcore
        ...)

データの収集

Play Core Native SDK は、Google がサービスを改善する目的で、次のようなバージョンに関連するデータを収集することがあります。

アプリのパッケージ名
アプリのパッケージバージョン
Play Core Native SDK のバージョン

このデータは、アプリパッケージを Google Play Console にアップロードする際に収集されます。データ収集のプロセスを無効にするには、build.gradle ファイル内の $playcoreDir/playcore-native-metadata.jar インポートを削除します。

Play Core Native SDK の使用と Google による収集データの使用に関連するこのデータ収集は、Google Play Console にアプリパッケージをアップロードする際に Gradle で宣言されるライブラリ依存関係の Google のデータ収集とは別のものであり、相互の関係はありません。

インストール時の配信

install-time として設定された Asset Pack は、アプリの起動時にすぐに利用できます。このモードで配信されるアセットにアクセスするには、NDK AAssetManager API を使用します。

#include <android/asset_manager.h>
#include <android_native_app_glue.h>
...
AAssetManager* assetManager = app->activity->assetManager;
AAsset* asset = AAssetManager_open(assetManager, "asset-name", AASSET_MODE_BUFFER);
size_t assetLength = AAsset_getLength(asset);
char* buffer = (char*) malloc(assetLength + 1);
AAsset_read(asset, buffer, assetLength);

fast-follow 配信と on-demand 配信

以下のセクションでは、API を初期化する方法、Asset Pack に関する情報をダウンロード前に取得する方法、API を呼び出してダウンロードを開始する方法、ダウンロードしたパックにアクセスする方法について説明します。このセクションは、fast-follow と on-demand の Asset Pack を対象としています。

アプリを起動

他の関数を呼び出す前に、必ず AssetPackManager_init() を呼び出して Asset Pack API を初期化します。Asset Pack のエラーコードがないか確認します。

#include "play/asset_pack.h"
...
AssetPackErrorCode AssetPackManager_init(JavaVM* jvm, jobject android_context);

また、次の関数は必ず ANativeActivityCallbacks の onPause() と onResume() で呼び出してください。

Asset Pack のダウンロード情報を取得

アプリは、Asset Pack を取得する前に、ダウンロードサイズを開示する必要があります。ダウンロードのサイズを確認し、パックがすでにダウンロード中かどうかを判別するための非同期リクエストを開始するには、AssetPackManager_requestInfo() 関数を使用します。次に、AssetPackManager_getDownloadState() を使用してダウンロード状態をポーリングします（たとえば、ゲームループ内のフレームごとにこの関数を 1 回呼び出します）。リクエストが失敗した場合、Asset Pack のエラーコードを確認します。

AssetPackErrorCode AssetPackManager_requestInfo();      // Call once
AssetPackErrorCode AssetPackManager_getDownloadState(); // Call once per frame in your game loop

AssetPackManager_getDownloadState() 関数は、不透明型の AssetPackDownloadState を出力ポインタとして返します。このポインタを使用して、次の関数を呼び出します。

AssetPackDownloadState* state;
AssetPackErrorCode error_code = AssetPackManager_getDownloadState(asset-pack-name, &state);
AssetPackDownloadStatus status = AssetPackDownloadState_getStatus(state);
uint64_t downloadedBytes = AssetPackDownloadState_getBytesDownloaded(state);
uint64_t totalBytes = AssetPackDownloadState_getTotalBytesToDownload(state));
AssetPackDownloadState_destroy(state);

インストール

Asset Pack の最初のダウンロードや、Asset Pack を更新して完了するためのリクエストを行うには、AssetPackManager_requestDownload() を使用します。

AssetPackErrorCode AssetPackManager_requestDownload();  // Call once
AssetPackErrorCode AssetPackManager_getDownloadState(); // Call once per frame in your game loop

AssetPackManager_getDownloadState() 関数は、不透明型の AssetPackDownloadState を返します。この型の使用方法については、ダウンロード情報を取得をご覧ください。

大規模なダウンロード

ダウンロードのサイズが 150 MB を超えていて、ユーザーが Wi-Fi に接続していない場合、モバイルデータ通信を介してダウンロードを続行することにユーザーが明示的に同意するまで、ダウンロードは開始されません。同様に、ダウンロードのサイズが大きく、ユーザーの Wi-Fi 接続が切断された場合は、ダウンロードが一時停止され、モバイルデータ接続を使用してダウンロードを続行するにはユーザーの明示的な同意が必要になります。一時停止されたパックは WAITING_FOR_WIFI の状態になります。ユーザーに同意を求める UI フローをトリガーするには、次の関数を使用します。

Asset Pack にアクセス

ダウンロードリクエストが COMPLETED 状態になった後、ファイルシステム呼び出しを使用して Asset Pack にアクセスできます。各 Asset Pack は、アプリの内部ストレージ内の個別のディレクトリに保存されます。AssetPackManager_getAssetPackLocation() を使用して、指定した Asset Pack の AssetPackLocation を取得します。その場所で AssetPackLocation_getStorageMethod() を使用して格納方法を確認します。

ASSET_PACK_STORAGE_APK: Asset Pack は APK としてインストールされます。これらのアセットにアクセスするには、install-time 配信をご覧ください。
ASSET_PACK_STORAGE_FILES: AssetPackLocation_getAssetsPath() を使用して、アセットが格納されているディレクトリへのファイルパスを取得します。アセットがダウンロードされていない場合は null が返されます。このファイルパスでは、ダウンロードしたファイルを変更しないでください。

AssetPackLocation* location;

AssetPackErrorCode error_code = AssetPackManager_getAssetPackLocation(asset-pack-name, &location);

if (error_code == ASSET_PACK_NO_ERROR) {
    AssetPackStorageMethod storage_method = AssetPackLocation_getStorageMethod(location);
    const char* assets_path = AssetPackLocation_getAssetsPath(location);
    AssetPackLocation_destroy(location);
}

アセットが見つかったら、fopen や ifstream などの関数を使用してファイルにアクセスします。

その他の Play Core API メソッド

アプリで使用できるその他の API メソッドを次にいくつか示します。

リクエストをキャンセルする

アクティブなアセットパックリクエストをキャンセルするには、AssetPackManager_cancelDownload() を使用します。このリクエストはベストエフォート型のオペレーションです。

削除をリクエスト

Asset Pack の削除をスケジュールするには、AssetPackManager_requestRemoval() を使用します。

次のステップ

ローカルおよび Google Play で Play Asset Delivery をテストします。