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

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

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

สร้างมาเพื่อ Native

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

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

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

3. สร้างไฟล์ build.gradle ในไดเรกทอรี Asset Pack แล้วเพิ่มโค้ดต่อไปนี้ อย่าลืมระบุชื่อ 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 ที่ต้องการเข้าถึง ขั้นตอนเหล่านี้แสดงอยู่ในโฟลว์ชาร์ตต่อไปนี้

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

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

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

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

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

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

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

   ลิงก์ดาวน์โหลด	ขนาด	การตรวจสอบข้อผิดพลาดด้วย SHA-256
   play-core-native-sdk-1.16.0.zip	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 เมื่อคุณอัปโหลดแพ็กเกจแอปไปยัง Play Console

การนำส่งแบบ install-time

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

การนำส่งแบบดาวน์โหลดอัตโนมัติและ on-demand

ส่วนต่อไปนี้แสดงวิธีเริ่มต้น 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

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_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);

ติดตั้ง

ใช้ 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 เพื่อแจ้งให้ผู้ใช้ให้ความยินยอม ให้ใช้โค้ดต่อไปนี้

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

ต้องได้รับการยืนยันจากผู้ใช้

หากแพ็กมีสถานะ 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 ดู การนำส่งแบบ install-time เพื่อเข้าถึงเนื้อหาเหล่านี้
• ASSET_PACK_STORAGE_FILES: Use 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 เพื่อเข้าถึงไฟล์

เมธอด API อื่นๆ ของ Play Core

ต่อไปนี้คือเมธอด API เพิ่มเติมที่คุณอาจต้องการใช้ในแอป

ยกเลิกคำขอ

ใช้ AssetPackManager_cancelDownload() เพื่อยกเลิกคำขอ Asset Pack ที่ใช้งานอยู่ โปรดทราบว่าคำขอนี้เป็นการดำเนินการแบบพยายามอย่างเต็มที่

ขอให้นำออก

ใช้ AssetPackManager_requestRemoval() เพื่อกำหนดเวลาการนำ Asset Pack ออก

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

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