Google Play Asset Delivery のリファレンス

Google PAD API の API リファレンスと実装ガイドライン

Windows
MacOS
Linux

Google Play Asset Delivery (Google PAD) は、デバイスにアプリケーションをインストールした後でアセット パックを配信する Google Play ストアのソリューションです。このソリューションは Android App Bundle 配布形式と一緒に使用することを前提にしています。App Bundle がカスタマイズ済みの .apk をエンド ユーザーに配布して、初期インストールでコードやバイナリの処理するのに対して、Play Asset Delivery システムは、モデル、テクスチャ、サウンド、シェーダ、その他の大きなアセット ファイルを .apk とは別に提供します。この機能により Google Play で配布されるアプリは、必要に応じてコンテンツを配信することでコンテンツが占めるスペースを管理できます。

Google Play Asset Delivery の一般情報については、Android 公式ドキュメント (https://android-developers.googleblog.com/2020/06/introducing-google-play-asset-delivery.html) を参照してください。

Unreal Engine 4.25 以降はプラグインで Google PAD 統合を提供しており、このシステムを作成したプロジェクトに簡単に実装することが可能です。このプラグインが提供する関数ライブラリにより、ダウンロードを管理して Play Asset Delivery システムから情報をリクエストする、呼び出しを利用できます。また、UGooglePADFunctionLibrary は C++ と Blueprint の両方で使用できます。

Android App Bundle の内容に関する詳細は「Android プロジェクトのパッケージ化 」を参照してください。

Google PAD プラグインを有効化する

Google PAD プラグインは Unreal Editor の [Plugins (プラグイン)] ウィンドウの [Android] セクションから利用できます。これは Unreal Engine 4.25.0 以降ではデフォルトで有効です。Google PAD を使用するには、パッケージ化の形式として Android App Bundles を使用する必要があります。

Google PAD Plugin

このプラグインを完全に有効化するには [Project Settings (プロジェクト設定)] を開いて [Plugins (プラグイン)] > [GooglePAD] > [Packaging] の順に移動します。[Enable Plugin] チェックボックスをクリックすると、Android プロジェクトの起動時にこのモジュールが使用可能になります。

Google PAD Plugin Options

インストール時 アセットに Google PAD を使用する場合は、[Platforms (プラットフォーム)] > [Android] > [APK Packaging] の順に移動して、[Package Data inside APK (APK 内のゲーム データをパッケージ化)] を無効にする必要もあります。メインの .obb ファイルはその後インストール時アセット パックとして自動的に供給されます。

クリックして画像を拡大します

アセット パックを作成する

Google PAD の Asset packs は Android App Bundle ビルド内にパッケージ化され、アップロード時に Google Play Store によって管理されます。このセクションではご使用の App Bundle に含むアセット パックのパッケージ化および整理方法について説明します。

アセットパックの配信モード

チャンク とは外部アセットを管理するための Unreal Engine の形式です。チャンク 0 はゲームの基本インストールを表し、その他すべてのチャンクはゲームのメイン インストール外のアセットを含む .pak ファイルです。

Google PAD を使用するには、ゲームのアセットをチャンクにグループ化し、これらのチャンクをアセット パックにグループかしなければなりません。使用する配信モードに基づいてGoogle Play Asset Delivery は以下のアセットパックの配信モードをサポートします。

配信モード

ファイル サイズの制限 (アセットパックごと)

説明

Install-Time

1 GB

インストール時に配信されるアセットパック。プロジェクトのメイン .obb はこのアセットパックに自動的にバンドルされます。

Fast-Follow

512 MB

アプリケーションのインストール後に自動的にダウンロードされるアセットパック。これをダウンロードするためにアプリケーションを開く必要はありません。Fast-Follow アセットパックは 1 プロジェクトにつき 1 つです。

On-Demand

512 MB

アプリケーションが実行するとダウンロードされるアセットパックです。

アプリケーションにつき最大 50 までアセットパックを作ることができます。1 プロジェクトにつき Install-Time アセットパックと Fast-Follow アセットパックはそれぞれ 1 つしか作成できませんが、On-Demand アセットパックは 50 までであれば好きなだけ作成することができます。

チャンクを作成する

Project Settings (プロジェクト設定)] をから [Project] > [Packaging] を開いて [Generate Chunks (チャンクを作成する)] が有効であることを確認します。

Activate Generate Chunks in the Project > Packaging section

アセット マネージャ または プライマリ アセット ラベル を使ってチャンク内でアセットを整理することができます。

コンテンツ ブラウザで右クリックして [Miscellaneous (その他)] > [Data Asset (データ アセット)] をクリックしてプライマリ アセットを作成します。

クリックして画像を拡大

データ アセット クラス を選択するプロンプトが表示されます。[PrimaryAssetLabel] を選択して [Select (選択)] をクリックします。

クリックして画像を拡大

新しいプライマリ アセット ラベルに名前を付けます。情報を編集するためにダブルクリックします。

クリックして画像を拡大

同じフォルダ内のすべてのアセットをこのアセット ラベルに属すると指定するために [Label Assets in my Directory] を有効にします。このラベルに属するアセットが属するチャンクを指定するために、Chunk ID に 0 より大きい値を設定します。Explicit Assets リストを使ってアセット ラベルにアセットを直接追加することもできます。

アセット マネージャは [Project Settings (プロジェクト設定)][Game] > [Asset Manager] にあります。

クリックして画像を拡大

ここで、プロジェクトがアセットをプロシージャルにチャンクにブループ化するために使用するルールを指定することができます。詳しくは「クックとチャンキング 」を参照してください。

特定のチャンクに属するアセットを指定すると、プロジェクトを パッケージ化 することでチャンクが .pak ファイルで出力されます。このファイルは「Saved\StagedBuilds[PlatformName][ProjectName]\Content\Paks」にあります。

クリックして画像を拡大

App Bundle Build にチャンクをインクルードする

Play Asset Delivery の各配信モードでは、App Bundles にチャンクを取り込むための要求事項が異なります。

Install-Time アセットの場合、何も変更する必要はありません。

Fast-Follow アセット、または On-Demand アセットの場合、インクルードする .pak ファイルを選択して、それをプロジェクトの「Build/Android/gradle/assetpacks」に移動します。配信モードはそれぞれ異なるサブフォルダを持ちます。

  • Fast-Follow アセットパックの場所は「Build/Android/gradle/assetpacks/fast-follow/[assetpackname]/src/main/assets」です。

  • On-Demand アセットパックの場所は「Build/Android/gradle/assetpacks/on-demand/[assetpackname]/src/main/assets」です。

をチャンクがバンドルされるアセットパック名に [assetpackname] を置き換えます。異なる .pak ファイルのセットで複数の異なる名前のついたアセットパックを作成することができます。ただし、アセットパックの名前は一意でなければなりません。また、fast-follow と on-demand 間での再利用はできません。この名前は API でアセットパックをクエリする際に使用する名前になります。

最後に、以下のコードを含むアセットパック フォルダに build.gradle ファイルを追加する必要があります。

apply plugin: 'com.android.asset-pack'

def fileparts = projectDir.absolutePath.replaceAll('\\\\', '/').tokenize('/')
def assetPackName = fileparts[fileparts.size()-1]
def assetPackType = fileparts[fileparts.size()-2]

assetPack {
    packName = assetPackName
    dynamicDelivery {
        deliveryType = assetPackType
        instantDeliveryType = assetPackType
    }
}

これらの要求事項を満たした後に、プロジェクトを app buncle として再度パッケージ化すると、ビルド内にこれらのアセットパックがそれぞれインクルードされます。App Bundle を Google Play Store にアップロードする際に、Google PAD API を使ってアセットパックをダウンロードすることができます。

このワークフローは Unreal Engine 4.26 で効率的に再編されます。

API リファレンス

次のセクションでは、Google PAD 関数ライブラリで利用できる関数と、その使用方法を詳しく説明します。

リクエストとエラー ハンドリング

Google PAD 関数ライブラリのリクエストはすべて EGooglePADErrorCode を返し、これは操作が成功したかどうかを表します。そして失敗した場合は、リクエストを完了できなかった特定のエラーを示します。発生する可能性があるエラー コードを以下に示します。

EGooglePADErrorCode

説明

AssetPack_NO_ERROR

このリクエストにエラーはありません。通常どおりリクエストの情報で続行します。

AssetPack_APP_UNAVAILABLE

リクエストしたアプリは利用できません。

AssetPack_UNAVAILABLE

このアプリの現在のバージョンではリクエストしたアセット パックを利用できません。

AssetPack_INVALID_REQUEST

このリクエストは無効です。

AssetPack_DOWNLOAD_NOT_FOUND

リクエストされたダウンロードが見つかりません。

AssetPack_API_NOT_AVAILABLE

この Asset Pack API は使用できません。

AssetPack_NETWORK_ERROR

タイムアウトやその他のネットワーク エラーにより、アセット パックの詳細を取得できません。

AssetPack_ACCESS_DENIED

現在のデバイスの状態ではダウンロードが許可されていません。ユーザーが Google アカウントにサインインして可能性があります。

AssetPack_INSUFFICIENT_STORAGE

ストレージ容量が足りないためアセット パックをダウンロードできません。

AssetPack_PLAY_STORE_NOT_FOUND

このデバイスに Play ストア アプリがインストールされていないか、公式のバージョンではありません。

AssetPack_NETWORK_UNRESTRICTED

Wi-Fi を必要とするアセット パックがない場合に ShowCellularDataConfirmation を呼び出すと返されます。この場合はユーザーの確認を待たずにダウンロードを続行できます。

AssetPack_INTERNAL_ERROR

アセット パックのダウンロード中に不明なエラーが発生しました。

AssetPack_INITIALIZATION_NEEDED

まだ AssetPackManager_init を呼び出していないため、API もまだ有効化されていません。

AssetPack_INITIALIZATION_FAILED

Asset Pack API の初期化でエラーが発生しました。

この戻り値以外にも、リクエスト関数には必要な情報を提供する出力変数があります。結果が AssetPack_NO_ERROR の場合は、通常どおり提供された情報で続行できます。それ以外の場合は、フロー制御を使用して提供されたエラー コードに適切に対処する必要があります。

ダウンロードしたファイルの場所を取得する

関数 GetAssetPackLocation は、ダウンロードしたアセット パックの場所を取得して、関連する情報とともにローカルにキャッシュします。そのアセットが利用可能なときは、キャッシュした情報へのアクセスに必要に応じて使用する整数のハンドルを出力します。

GetAssetsPath を呼び出して場所ハンドルを提供すると、必要なアセット パックのアセット パスを含む文字列を出力します。また、GetStorageMethodEGooglePADStorageMethod を出力し、これはアセット パックをユーザーのデバイスにストアした方法を示します。アセットのパスとストア方法を把握したら、適切な呼び出しを使用してそのアセットを利用できます。

可能なストア方法を以下に示します。

EGooglePADStorageMethod

説明

AssetPack_STORAGE_FILES

アセットパックは個々のアセット ファイルを含むフォルダにアンパックされます。標準のファイル API でこうしたアセットにアクセスできます。

AssetPack_STORAGE_APK

アセットパックは、アセット ファイルがパックされた APK としてインストールされます。

AssetPack_STORAGE_UNKNOWN

アセット パックに関する情報を利用できません。エラーが発生した可能性があります。

AssetPack_STORAGE_NOT_INSTALLED

アセット パックがインストールされていないため使用できません。

上記の情報が必要なくなったら、場所ハンドルを ReleaseAssetPackLocation に渡してキャッシュした場所の情報を解放する必要があります。

アセット パックに関する情報をリクエストする

RequestInfo はダウンロードを開始する上で必須ではありませんが、リモートのアセット パックが有効かどうかの判断に利用できます。

ダウンロードをリクエストまたはキャンセルする

関数 RequestDownload は、ダウンロードするアセット パック名を表す文字列 TArray を受け取り、リモート サービスにリクエストを送信して対象のアセット パックのダウンロードを開始します。RequestDownload がエラーを示しない場合は、アセット パックをダウンロードして非同期にバックグラウンドでアプリに転送します。

これは非同期の機能なので、RequestDownload 関数は、リクエストが成功したかどうかを表すエラー コードを除いて、ダウンロードするアセット パックについて情報を返しません。ダウンロードの現在のステータスを確認するには、以下の「ダウンロードのステータスを監視する 」セクションに詳述している機能を使用する必要があります。その後ダウンロードが完了したら、GetAssetPackLocation を使用してアセット パック自体を利用します。

また、関数 CancelDownload はアセット パック名のリストを使用して、指定したアセット パックのダウンロードをキャンセルします。

携帯電話データ通信のステータスを取得する

関数 ShowCellularDataConfirmation は、携帯電話ネットワークを使用してデータをダウンロードするかどうかをユーザーに確認します。この確認を既に行っている場合は、GetShowCellularDataConfirmationStatus を使用してユーザーがダウンロードを承認しているかどうかを示す EGooglePADCellularDataConfirmStatus を取得できます。

この結果が AssetPack_CONFIRM_UNKNOWNAssetPack_CONFIRM_PENDING の場合はまだユーザーが承認していないことを表し、アプリケーションは承認されるまで待つ必要があります。

この結果が AssetPack_CONFIRM_USER_CANCELLED の場合はユーザーが携帯電話データ通信の使用を許可していないことを表し、この時点でダウンロードしてはいけません。

この結果が AssetPack_CONFIRM_USER_APPROVED の場合は、ユーザーが携帯電話データ通信の使用を明示的に承認しているのでダウンロードを続行できます。さらに、この関数が AssetPack_NETWORK_UNRESTRICTED の結果で EGooglePADErrorCode を返す場合は、ユーザーが Wi-Fi ネットワークを利用できるため携帯電話データ通信を使用する必要がなく、さらにこの機能を確認せずにダウンロードできます。

ダウンロードのステータスを監視する

GetDownloadState はアセット パックのダウンロード ステータスをローカルにキャッシュして、このキャッシュ済み情報にアクセスするためのダウンロード ハンドルを返します。この関数は、ダウンロードするアセット パック名を受け取り、そのハンドルを整数として出力します。このダウンロード ハンドルをキャッシュしておくことでダウンロードを引き続き監視できます。そうしない場合はダウンロード ハンドルの再取得が必要です。

有効なダウンロード ハンドルを使用して GetDownloadStatus を呼び出すことで、必要なアセット パックのステータスを EGooglePADDownloadStatus として取得できます。この列挙型はダウンロードのステータスであり、以下に示す可能な状態のいずれかを表します。

EGooglePADDownloadStatus

説明

AssetPack_UNKNOWN

このアセット パックに関する情報を現在取得できません。

AssetPack_DOWNLOAD_PENDING

アセット パックをダウンロードする非同期リクエストは送信済ですが、現在保留中です。

AssetPack_DOWNLOADING

現在アセット パックのダウンロード中です。

AssetPack_TRANSFERRING

アセット パックをアプリに転送中です。

AssetPack_DOWNLOAD_COMPLETED

ダウンロードと転送が両方完了したので、アセットをアプリから利用できます。

AssetPack_DOWNLOAD_FAILED

アセット パックのダウンロード リクエストに失敗しました。

AssetPack_DOWNLOAD_CANCELED

アセット パックをダウンロードするリクエストがキャンセルされました。

AssetPack_WAITING_FOR_WIFI

アセット パックのダウンロードは Wi-Fi 転送を待機しています。

AssetPack_NOT_INSTALLED

このアセット パックは現在インストールされていません。

AssetPack_INFO_FAILED

このアセット パックに関する情報のリクエストに失敗しました。

AssetPack_REMOVAL_PENDING

このアセット パックを削除する非同期リクエストは送信済みですが、現在保留中です。

AssetPack_REMOVAL_FAILED

このアセット パックを削除する非同期リクエストに失敗しました。

ダウンロード ステータスのハンドルとともに GetBytesDownloaded を呼び出すことで、ユーザーのデバイスに現在ダウンロード済みのバイト数を取得できます。一方、GetTotalBytesToDownload はダウンロードする対象の合計サイズを返します。

ダウンロードのステータス情報が必要なくなったら ReleaseDownloadState を呼び出してハンドルを提供し、メモリからキャッシュ済みのダウンロード情報を解放する必要があります。

アセット パックを削除する

関数 RequestRemoval にアセット パック名を渡すことで、この指定したアセット パックをユーザーのデバイスから非同期で削除します。このアセット パックを削除するステータスは上記の GetDownloadStatus で監視できます。

推奨する実装方法

Google PAD API の実装は、ダウンロードの状態によって異なるサイクルとしてモデル化できます。

ステータス

説明

Accessing Asset Pack

  • GetAssetPackLocation を使用してアセット パックがダウンロード済みかどうかを確認します。既存のアセットをダウンロードしないように、これを必ず最初に実行します。

  • GetAssetsPathGetStorageMethod を使用してアセット パックのファイル パスと適切なアクセス方法を指定します。

  • ReleaseAssetPackLocation を呼び出してアセット パックをキャッシュした場所のメモリを解放する必要があります。

Initiating Download

  • 必要なアセット パックをローカルで利用できない場合は、RequestDownload を呼び出してダウンロードを開始します。

  • 接続に問題がある場合は成功するまで RequestDownload を繰り返す必要があります。

Checking for Cellular Data Confirmation

  • ShowCelllarDataConfirmation を使用してアプリケーションにダウンロードを続ける権限があることを確認します。

  • 最初の携帯電話データ通信について確認するプロンプトの後で GetShowCellularDataConfirmationStatus を使用して、このプロンプトの現在のステータスを出力します。これはプロンプトがキャンセルまたは確認されるまで Tick 関数で継続的に実行されます。

Monitoring Download Status

  • RequestDownload が正常に完了した後で GetDownloadState を使用し、ダウンロードのステータスをキャッシュしてアクセスに必要なハンドルを取得します。この呼び出しは必ず 1 回だけ実行して、使用する期間はハンドルをキャッシュしておきます。

  • GetBytesDownloadedGetTotalBytesToDownload を使用してダウンロードの進捗状況を確認します。この進捗状況の監視を止めるまで、GetBytesDownloaded をティックで継続的に実行する必要があります。

  • GetDownloadStatus を使用してダウンロードの正確なステータスを判断します。これもティックで継続的に監視する必要があります。ステータスが AssetPack_DOWNLOAD_COMPLETED になったら、ダウンロード ステータスの監視を止めてアセット パックを利用できます。

  • 完了したら RelaseDownloadState を呼び出して、必ずキャッシュしたダウンロード ステータスのメモリを解放します。

カスタムの GameState クラスでソリューションを実装すると、シーンやゲーム モードを変更してもダウンロードを引き続き追跡できます。他にも、起動時にロードするフロントエンド ゲーム モードにソリューションを実装して、ゲームの開始前に必要なパッチや更新を実行することが可能です。なお、ソリューションの正確な詳細はアセットを更新するプロジェクト固有のニーズにより異なります。

Select Skin
Light
Dark

新しい Unreal Engine 4 ドキュメントサイトへようこそ!

あなたの声を私たちに伝えるフィードバックシステムを含め、様々な新機能について開発をおこなっています。まだ広く使える状態にはなっていないので、準備ができるまでは、ドキュメントフィードバックフォーラムで、このページについて、もしくは遭遇した問題について教えていただけると助かります。

新しいシステムが稼働した際にお知らせします。

フィードバックを送信