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

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

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

สร้างสำหรับโฆษณาเนทีฟ

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

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

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

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

   // 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 ของแอปในโปรเจ็กต์ ให้เพิ่มชื่อของทุกๆ แอสเซ็ตแพ็ก ในโปรเจ็กต์ตามที่แสดงด้านล่าง

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

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

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

6. สร้างไดเรกทอรีย่อยต่อไปนี้ในไดเรกทอรีแพ็กชิ้นงาน 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 สำหรับแต่ละแพ็กเกจเนื้อหาและเอาต์พุตassets/ ไดเรกทอรีให้คุณ

9. (ไม่บังคับ) กำหนดค่า App Bundle เพื่อรองรับรูปแบบการบีบอัด เท็กซ์เจอร์ที่แตกต่างกัน

ผสานรวมกับไลบรารี Play Asset Delivery

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

รูปที่ 1 แผนภาพลำดับงานสำหรับการเข้าถึงแพ็กชิ้นงาน

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

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

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

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

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

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

   ลิงก์ดาวน์โหลด	ขนาด	ผลรวมตรวจสอบ SHA-256
   play-core-native-sdk-1.15.3.zip	37.8 MiB	9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

4. อัปเดตไฟล์ 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.1.0'
           implementation 'com.google.android.play:asset-delivery:2.3.0'
           implementation 'com.google.android.play:integrity:1.4.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.4.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 import ในไฟล์ build.gradle ออก

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

การนำส่งเมื่อติดตั้ง

แพ็กเกจชิ้นงานที่กำหนดค่าเป็น 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() เสมอ เพื่อเริ่มต้น API ของชุดชิ้นงานก่อนเรียกใช้ฟังก์ชันอื่นๆ ตรวจสอบรหัสข้อผิดพลาดของแพ็กเกจเนื้อหา

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

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

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_onResume()

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

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

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() เพื่อเริ่มดาวน์โหลดแพ็กเนื้อหาเป็นครั้งแรกหรือขออัปเดตแพ็กเนื้อหาให้เสร็จสมบูรณ์

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

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

• ASSET_PACK_STORAGE_APK: ระบบจะติดตั้งแพ็กเนื้อหาเป็น 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() เพื่อยกเลิกคำขอแพ็กเกจเนื้อหาที่ใช้งานอยู่ โปรดทราบว่าคำขอนี้เป็นการดำเนินการ อย่างเต็มความสามารถ

ขอให้นำออก

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

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

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