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

ทำตามขั้นตอนในคู่มือนี้เพื่อเข้าถึงแพ็กชิ้นงานของแอปจากโค้ด 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. สร้างไฟล์ 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 ของโปรเจ็กต์ ให้รวมแพ็กชิ้นงานทั้งหมดในโปรเจ็กต์ตามที่แสดงด้านล่าง

    // 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 แผนภาพโฟลว์สำหรับการเข้าถึงแพ็กเกจชิ้นงาน

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. เลือกดำเนินการอย่างหนึ่งดังต่อไปนี้

  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 เมื่อคุณอัปโหลดแพ็กเกจแอป ไปยัง 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 เพื่อเริ่ม การดาวน์โหลด และวิธีเข้าถึงแพ็กที่ดาวน์โหลด ส่วนเหล่านี้มีผลกับ fast-follow และ on-demand Asset Pack

การเปิดแอป

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

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

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

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

การยืนยันผู้ใช้ที่จำเป็น

หากแพ็กมีสถานะเป็น 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