ผสานรวมการนำส่งชิ้นงาน (เนทีฟ)

ใช้ขั้นตอนในคู่มือนี้เพื่อเข้าถึง Asset Pack ของแอปจากโค้ด C และ C++

โค้ดการผสานรวมตัวอย่างมีอยู่ใน GitHub

สร้างเพื่อเนทีฟ

ทำตามขั้นตอนต่อไปนี้เพื่อสร้างการนำส่งเนื้อหา Play ลงใน Android App Bundle ของโปรเจ็กต์ คุณไม่จำเป็นต้องใช้ Android Studio เพื่อทำตามขั้นตอนเหล่านี้

  1. อัปเดตเวอร์ชันของปลั๊กอิน Android Gradle ในไฟล์ build.gradle ของโปรเจ็กต์เป็น 4.0.0 ขึ้นไป

  2. ในไดเรกทอรีระดับบนสุดของโปรเจ็กต์ ให้สร้างไดเรกทอรีสำหรับ Asset Pack ระบบจะใช้ชื่อไดเรกทอรีนี้เป็นชื่อ Asset Pack ชื่อ Asset Pack ต้องขึ้นต้นด้วยตัวอักษรและมีได้เฉพาะตัวอักษร ตัวเลข และขีดล่างเท่านั้น

  3. ในไดเรกทอรี Asset Pack ให้สร้างไฟล์ build.gradle และเพิ่มโค้ดต่อไปนี้ ตรวจสอบว่าได้ระบุชื่อ Asset Pack และประเภทการนำส่งเพียงประเภทเดียว ดังนี้

    // 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. ในไฟล์ build.gradle ของแอปในโปรเจ็กต์ ให้เพิ่มชื่อ Asset Pack ทุกรายการในโปรเจ็กต์ตามที่แสดงด้านล่าง

    // In the app build.gradle file:
android {
    ...
    assetPacks = [":asset-pack-name", ":asset-pack2-name"]
}

  5. ในไฟล์ settings.gradle ของโปรเจ็กต์ ให้รวม Asset Pack ทั้งหมดในโปรเจ็กต์ตามที่แสดงด้านล่าง

    // In the settings.gradle file:
include ':app'
include ':asset-pack-name'
include ':asset-pack2-name'

  6. ในไดเรกทอรี Asset Pack ให้สร้างไดเรกทอรีย่อยต่อไปนี้ src/main/assets

  7. วางเนื้อหาในไดเรกทอรี src/main/assets คุณสร้างไดเรกทอรีย่อยในนี้ได้ด้วย ตอนนี้โครงสร้างไดเรกทอรีของแอปควรมีลักษณะดังนี้

    • build.gradle
    • settings.gradle
    • app/
    • asset-pack-name/build.gradle
    • asset-pack-name/src/main/assets/your-asset-directories

  8. สร้าง Android App Bundle ด้วย Gradle ใน App Bundle ที่สร้างขึ้น ไดเรกทอรีระดับรูทจะมีสิ่งต่อไปนี้รวมอยู่ด้วย

    • asset-pack-name/manifest/AndroidManifest.xml: กำหนดค่าตัวระบุและโหมดการนำส่งของ Asset Pack
    • asset-pack-name/assets/your-asset-directories: ไดเรกทอรีที่มีเนื้อหาทั้งหมดที่ส่งเป็นส่วนหนึ่งของ Asset Pack

    Gradle จะสร้างไฟล์ Manifest สำหรับ Asset Pack แต่ละรายการและแสดงผลไดเรกทอรี assets/ ให้คุณ

  9. (ไม่บังคับ) กำหนดค่า App Bundle ให้รองรับรูปแบบการบีบอัดพื้นผิวที่แตกต่างกัน

ผสานรวมกับไลบรารีการนำส่งเนื้อหา Play

คุณใช้ API นี้ตามประเภทการนำส่งของ Asset Pack ที่ต้องการเข้าถึง ขั้นตอนเหล่านี้แสดงอยู่ในผังงานต่อไปนี้

แผนภาพขั้นตอนของ Asset Pack สำหรับโค้ดแบบเนทีฟ

รูปที่ 1 แผนภาพโฟลว์สำหรับการเข้าถึง Asset Pack

Play Core Native SDK มีไฟล์ส่วนหัว C play/asset_pack.h สำหรับขอ Asset Pack, จัดการการดาวน์โหลด และเข้าถึงเนื้อหา

ตั้งค่าสภาพแวดล้อมในการพัฒนาซอฟต์แวร์สำหรับ Play Core Native SDK

ดาวน์โหลด Play Core Native SDK

คุณต้องยอมรับข้อกำหนดและเงื่อนไขต่อไปนี้ก่อนดาวน์โหลด

ข้อกำหนดและเงื่อนไข

Last modified: September 24, 2020
  1. By using the Play Core Software Development Kit, you agree to these terms in addition to the Google APIs Terms of Service ("API ToS"). If these terms are ever in conflict, these terms will take precedence over the API ToS. Please read these terms and the API ToS carefully.
  2. For purposes of these terms, "APIs" means Google's APIs, other developer services, and associated software, including any Redistributable Code.
  3. “Redistributable Code” means Google-provided object code or header files that call the APIs.
  4. Subject to these terms and the terms of the API ToS, you may copy and distribute Redistributable Code solely for inclusion as part of your API Client. Google and its licensors own all right, title and interest, including any and all intellectual property and other proprietary rights, in and to Redistributable Code. You will not modify, translate, or create derivative works of Redistributable Code.
  5. Google may make changes to these terms at any time with notice and the opportunity to decline further use of the Play Core Software Development Kit. Google will post notice of modifications to the terms at https://developer.android.com/guide/playcore/license. Changes will not be retroactive.
ดาวน์โหลด Play Core Native SDK

play-core-native-sdk-1.16.0.zip

  1. เลือกดำเนินการอย่างหนึ่งดังต่อไปนี้

    • ติดตั้ง Android Studio เวอร์ชัน 4.0 ขึ้นไป ใช้ UI ของเครื่องมือจัดการ SDK เพื่อติดตั้ง Android SDK Platform เวอร์ชัน 10.0 (ระดับ API 29)
    • ติดตั้งเครื่องมือบรรทัดคำสั่ง Android SDK และใช้ sdkmanager เพื่อติดตั้งแพลตฟอร์ม Android SDK เวอร์ชัน 10.0 (ระดับ API 29)

  2. เตรียม Android Studio สำหรับการพัฒนาแบบเนทีฟโดยใช้เครื่องมือจัดการ SDK เพื่อติดตั้ง CMake และ Android Native Development Kit (NDK) เวอร์ชันล่าสุด ดูข้อมูลเพิ่มเติมเกี่ยวกับการสร้างหรือนำเข้าโปรเจ็กต์เนทีฟได้ที่เริ่มต้นใช้งาน NDK

  3. ดาวน์โหลดไฟล์ ZIP และแตกไฟล์ไว้ข้างโปรเจ็กต์

    ลิงก์ดาวน์โหลด ขนาด การตรวจสอบข้อผิดพลาดด้วย SHA-256
    54.8 MiB 008b8fedc6179a6dc6ccc21af75591afc7036f78f3d5559d844f1b923934fef0

  4. อัปเดตไฟล์ build.gradle ของแอปตามที่แสดงด้านล่าง

    ดึงดูด

        // 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.1.0'
        implementation 'com.google.android.play:asset-delivery:2.3.0'
        implementation 'com.google.android.play:integrity:1.6.0'
        implementation 'com.google.android.play:review:2.0.2'

        // 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.1.0")
    implementation("com.google.android.play:asset-delivery:2.3.0")
    implementation("com.google.android.play:integrity:1.6.0")
    implementation("com.google.android.play:review:2.0.2")

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

  5. อัปเดตไฟล์ 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

ระบบจะรวบรวมข้อมูลนี้เมื่อคุณอัปโหลดแพ็กเกจแอปไปยัง Play Console หากต้องการเลือกไม่ใช้กระบวนการเก็บรวบรวมข้อมูลนี้ ให้นำการนําเข้า $playcoreDir/playcore-native-metadata.jar ในไฟล์ build.gradle ออก

โปรดทราบว่าการเก็บรวบรวมข้อมูลที่เกี่ยวข้องกับการใช้ Play Core Native SDK และการใช้ข้อมูลที่เก็บรวบรวมของ Google นั้นแยกต่างหากและไม่เกี่ยวข้องกับการเก็บรวบรวมทรัพยากร Dependency ของไลบรารีที่ประกาศใน Gradle ของ Google เมื่อคุณอัปโหลดแพ็กเกจแอปไปยัง Play Console

การนำส่งขณะติดตั้ง

Asset Pack ที่กำหนดค่าเป็น install-time จะพร้อมใช้งานทันทีเมื่อเปิดแอป ใช้ 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);

การจัดส่งแบบเร่งด่วนและแบบออนดีมานด์

ส่วนต่อไปนี้จะแสดงวิธีเริ่มต้น API, วิธีรับข้อมูลเกี่ยวกับ Asset Pack ก่อนดาวน์โหลด, วิธีเรียก API เพื่อเริ่มการดาวน์โหลด และวิธีเข้าถึงแพ็กที่ดาวน์โหลด ส่วนเหล่านี้ใช้กับ Asset Pack แบบfast-followและon-demand

การเปิดแอป

เรียกใช้ AssetPackManager_init() เสมอเพื่อเริ่มต้น Asset Pack API ก่อนเรียกใช้ฟังก์ชันอื่นๆ ตรวจสอบรหัสข้อผิดพลาดของ Asset Pack

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

นอกจากนี้ อย่าลืมเรียกใช้ฟังก์ชันต่อไปนี้ใน onPause() และ onResume() ของ ANativeActivityCallbacks

ดูข้อมูลการดาวน์โหลดเกี่ยวกับ Asset Pack

แอปต้องเปิดเผยขนาดของการดาวน์โหลดก่อนดึงข้อมูล Asset Pack ใช้ฟังก์ชัน AssetPackManager_requestInfo() เพื่อเริ่มคำขอที่โหลดแบบอะซิงโครนัสสำหรับขนาดการดาวน์โหลดและดูว่าแพ็กกำลังดาวน์โหลดอยู่หรือไม่ จากนั้นใช้ AssetPackManager_getDownloadState() เพื่อสำรวจสถานะการดาวน์โหลด (เช่น เรียกใช้ฟังก์ชันนี้ 1 ครั้งต่อเฟรมใน Game Loop) หากคำขอไม่สำเร็จ ให้ตรวจสอบรหัสข้อผิดพลาดของ 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);

ติดตั้ง

ใช้ AssetPackManager_requestDownload() เพื่อเริ่มดาวน์โหลด Asset Pack เป็นครั้งแรกหรือเพื่อขออัปเดต Asset Pack ให้เสร็จสมบูรณ์

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

ฟังก์ชัน AssetPackManager_getDownloadState() จะแสดงผลประเภททึบแสง AssetPackDownloadState ดูข้อมูลเกี่ยวกับวิธีใช้ประเภทนี้ได้ที่หัวข้อรับข้อมูลการดาวน์โหลด

การดาวน์โหลดขนาดใหญ่

หากการดาวน์โหลดมีขนาดใหญ่กว่า 200 MB และผู้ใช้ไม่ได้ใช้ Wi-Fi การดาวน์โหลดจะไม่เริ่มจนกว่าผู้ใช้จะให้ความยินยอมอย่างชัดแจ้งเพื่อดำเนินการดาวน์โหลดต่อโดยใช้การเชื่อมต่ออินเทอร์เน็ตมือถือ ในทำนองเดียวกัน หากการดาวน์โหลดมีขนาดใหญ่และผู้ใช้สูญเสียการเชื่อมต่อ Wi-Fi การดาวน์โหลดจะหยุดชั่วคราวและต้องได้รับความยินยอมอย่างชัดแจ้งเพื่อดำเนินการต่อโดยใช้การเชื่อมต่ออินเทอร์เน็ตมือถือ แพ็กที่หยุดชั่วคราวมีสถานะเป็น WAITING_FOR_WIFI หากต้องการเรียกใช้ขั้นตอน UI เพื่อแจ้งให้ผู้ใช้ให้ความยินยอม ให้ใช้สิ่งต่อไปนี้

ต้องมีการยืนยันจากผู้ใช้

หากแพ็กมีสถานะ REQUIRES_USER_CONFIRMATION การดาวน์โหลดจะไม่ดำเนินการต่อจนกว่าผู้ใช้จะยอมรับกล่องโต้ตอบที่แสดงพร้อมกับ AssetPackManager_showConfirmationDialog() สถานะนี้อาจเกิดขึ้นหาก Play ไม่รู้จักแอป โปรดทราบว่าการเรียกใช้ AssetPackManager_showConfirmationDialog() ในกรณีนี้จะทำให้แอปได้รับการอัปเดต หลังจากอัปเดตแล้ว ให้ขอชิ้นงานอีกครั้ง

เข้าถึง Asset Pack

คุณสามารถเข้าถึง Asset Pack โดยใช้การเรียกใช้ระบบไฟล์หลังจากคำขอดาวน์โหลดถึงสถานะ COMPLETED ระบบจะจัดเก็บ Asset Pack แต่ละรายการไว้ในไดเรกทอรีแยกต่างหากในที่จัดเก็บข้อมูลภายในของแอป ใช้ AssetPackManager_getAssetPackLocation() เพื่อรับ AssetPackLocation สำหรับ Asset Pack ที่ระบุ ใช้ AssetPackLocation_getStorageMethod() ในตำแหน่งนั้นเพื่อกำหนดวิธีการจัดเก็บข้อมูล ดังนี้

  • ASSET_PACK_STORAGE_APK: ระบบจะติดตั้ง Asset Pack เป็น APK ดูการนำส่งขณะติดตั้งเพื่อเข้าถึงเนื้อหาเหล่านี้
  • 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() เพื่อกำหนดเวลาการนำ Asset Pack ออก

ขั้นตอนถัดไป

ทดสอบการนำส่งเนื้อหา Play ในเครื่องและจาก Google Play