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

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

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

สร้างสําหรับเวอร์ชันเนทีฟ

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

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

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

  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: ไดเรกทอรีที่มีชิ้นงานทั้งหมดที่ส่งเป็นส่วนหนึ่งของแพ็กเกจชิ้นงาน

    Gradle จะสร้างไฟล์ Manifest สำหรับแพ็กเกจเนื้อหาแต่ละรายการและแสดงผล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.15.3.zip

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

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

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

    ลิงก์ดาวน์โหลด ขนาด ผลรวมตรวจสอบ SHA-256
    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.2.2'
        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.2.2")
    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 ออกในไฟล์ build.gradle

โปรดทราบว่าการเก็บรวบรวมข้อมูลนี้เกี่ยวข้องกับการใช้ Play Core Native SDK และการใช้ข้อมูลที่เก็บรวบรวมของ Google นั้นแยกจากกันและไม่ได้ขึ้นอยู่กับการเก็บรวบรวมทรัพยากร Dependency ของไลบรารีที่ Google ประกาศไว้ใน 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, วิธีรับข้อมูลเกี่ยวกับชุดชิ้นงานก่อนดาวน์โหลด, วิธีเรียก 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

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

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

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

เข้าถึง Asset Pack

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

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