Mengintegrasikan pengiriman aset (native)

Gunakan langkah-langkah dalam panduan ini untuk mengakses paket aset aplikasi Anda dari kode C dan C++.

Contoh kode integrasi tersedia di GitHub.

Build untuk native

Gunakan langkah-langkah berikut untuk membuat Play Asset Delivery ke dalam Android App Bundle project Anda. Anda tidak perlu menggunakan Android Studio untuk melakukan langkah-langkah ini.

  1. Update versi plugin Android Gradle di file build.gradle project Anda ke 4.0.0 atau yang lebih baru.

  2. Di direktori level teratas project Anda, buat direktori untuk paket aset. Nama direktori ini digunakan sebagai nama paket aset. Nama paket aset harus diawali dengan huruf dan hanya boleh berisi huruf, angka, dan garis bawah.

  3. Dalam direktori paket aset, buat file build.gradle dan tambahkan kode berikut. Pastikan untuk menentukan nama paket aset dan satu jenis pengiriman saja:

    // 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 ]"
        }
    }
    
  4. Pada file build.gradle aplikasi di project, tambahkan nama setiap paket aset dalam project Anda seperti yang ditunjukkan di bawah ini:

    // In the app build.gradle file:
    android {
        ...
        assetPacks = [":asset-pack-name", ":asset-pack2-name"]
    }
    
  5. Dalam file settings.gradle project, sertakan semua paket aset dalam project Anda seperti yang ditunjukkan di bawah ini:

    // In the settings.gradle file:
    include ':app'
    include ':asset-pack-name'
    include ':asset-pack2-name'
    
  6. Dalam direktori paket aset, buat subdirektori berikut: src/main/assets.

  7. Tempatkan aset di direktori src/main/assets. Anda juga dapat membuat subdirektori di sini. Struktur direktori untuk aplikasi Anda sekarang akan terlihat seperti berikut:

    • build.gradle
    • settings.gradle
    • app/
    • asset-pack-name/build.gradle
    • asset-pack-name/src/main/assets/your-asset-directories
  8. Buat Android App Bundle menggunakan Gradle. Dalam app bundle yang dihasilkan, direktori level root kini menyertakan hal berikut:

    • asset-pack-name/manifest/AndroidManifest.xml: Mengonfigurasi mode pengiriman dan pengenal paket aset
    • asset-pack-name/assets/your-asset-directories: Direktori yang berisi semua aset yang dikirim sebagai bagian dari paket aset

    Gradle menghasilkan manifes untuk setiap paket aset dan menghasilkan direktori assets/ untuk Anda.

  9. (Opsional) Konfigurasikan app bundle Anda untuk mendukung berbagai format kompresi tekstur.

Integrasi dengan Play Core SDK

Play Core Native SDK menyediakan file header C play/asset_pack.h untuk meminta paket aset, mengelola download, dan mengakses aset. Pastikan untuk terlebih dahulu Menambahkan Library Play Core ke dalam project Anda.

Anda harus menerapkan API ini sesuai dengan jenis pengiriman paket aset yang ingin Anda akses. Langkah-langkah ini ditampilkan dalam diagram alir berikut.

Diagram alir asset pack untuk kode native

Gambar 1. Diagram alir untuk mengakses asset pack

Pengiriman waktu penginstalan

Asset pack yang dikonfigurasi sebagai install-time akan segera tersedia saat aplikasi diluncurkan. Gunakan NDK AAssetManager API untuk mengakses aset yang disalurkan dalam mode ini:

#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);

Pengiriman fast-follow dan on-demand

Bagian berikut menunjukkan cara menginisialisasi API, cara mendapatkan informasi tentang asset pack sebelum mendownloadnya, cara memanggil API untuk memulai download, dan cara mengakses paket yang didownload. Bagian ini berlaku untuk asset pack fast-follow dan on-demand.

Peluncuran aplikasi

Selalu panggil AssetPackManager_init() untuk menginisialisasi asset pack API sebelum memanggil fungsi lainnya. Periksa ada tidaknya kode error asset pack.

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

Pastikan juga untuk memanggil fungsi berikut di onPause() dan onResume() pada ANativeActivityCallbacks:

Mendapatkan informasi download tentang asset pack

Aplikasi wajib mengungkapkan ukuran download sebelum mengambil asset pack. Gunakan fungsi AssetPackManager_requestInfo() guna memulai permintaan asinkron untuk ukuran download dan untuk memeriksa apakah paket sudah mulai didownload. Kemudian gunakan AssetPackManager_getDownloadState() untuk memilih status download (misalnya, memanggil fungsi ini satu kali per frame dalam game loop Anda). Jika permintaan gagal, periksa kode error asset pack.

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

Fungsi AssetPackManager_getDownloadState() akan menampilkan AssetPackDownloadState buram sebagai pointer output. Gunakan pointer ini untuk memanggil fungsi berikut:

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);

Instal

Gunakan AssetPackManager_requestDownload() untuk mulai mendownload asset pack pertama kalinya atau untuk meminta proses update asset pack diselesaikan:

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

Fungsi AssetPackManager_getDownloadState() menampilkan tipe buram AssetPackDownloadState. Untuk informasi mengenai cara menggunakan jenis ini, lihat Mendapatkan informasi download.

Hasil download berukuran besar

Jika hasil download lebih besar dari 150 MB dan pengguna tidak menggunakan Wi-Fi, proses download tidak akan dimulai sebelum pengguna mengizinkan secara eksplisit agar proses download dilanjutkan melalui koneksi data seluler. Demikian pula, jika hasil download berukuran besar dan koneksi Wi-Fi pengguna terputus, download akan dijeda dan perlu izin eksplisit untuk melanjutkan proses download melalui koneksi data seluler. Paket yang dijeda akan berstatus WAITING_FOR_WIFI. Untuk memicu alur UI yang meminta pengguna memberikan persetujuan, gunakan cara berikut:

Mengakses asset pack

Anda dapat mengakses asset pack dengan menggunakan panggilan sistem file setelah permintaan download mencapai status COMPLETED. Setiap asset pack disimpan dalam direktori terpisah dalam penyimpanan internal aplikasi. Gunakan AssetPackManager_getAssetPackLocation() guna mendapatkan AssetPackLocation untuk asset pack yang ditentukan. Gunakan AssetPackLocation_getStorageMethod() di lokasi tersebut untuk menentukan metode penyimpanannya:

  • ASSET_PACK_STORAGE_APK: Asset pack diinstal sebagai APK. Lihat Pengiriman saat penginstalan untuk mengakses aset ini.
  • ASSET_PACK_STORAGE_FILES: Gunakan AssetPackLocation_getAssetsPath() untuk memperoleh jalur file ke direktori yang berisi aset, atau null jika aset belum didownload. Jangan ubah file yang didownload dalam jalur file ini.
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);
}

Setelah Anda menemukan aset, gunakan fungsi seperti fopen atau ifstream untuk mengakses file tersebut.

Metode Play Core API lainnya

Berikut ini adalah beberapa metode API tambahan yang mungkin ingin Anda gunakan pada aplikasi.

Membatalkan permintaan

Gunakan AssetPackManager_cancelDownload() untuk membatalkan permintaan asset pack aktif. Perhatikan bahwa permintaan ini adalah operasi dengan upaya terbaik.

Minta penghapusan

Gunakan AssetPackManager_requestRemoval() untuk menjadwalkan penghapusan asset pack.

Langkah berikutnya

Uji Play Asset Delivery secara lokal dan dari Google Play.