שילוב של העברת נכסים (גרסה מקורית)

אפשר להיעזר בשלבים במדריך הזה כדי לגשת לחבילות הנכסים של האפליקציה מקוד C ו-C++‎.

קוד שילוב לדוגמה זמין ב-GitHub.

פיתוח למודעות מותאמות

כדי לשלב את התכונה 'העברת נכסים ב-Play' בחבילת האפליקציות ל-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-name/assets/your-asset-directories: הספרייה שמכילה את כל הנכסים שנמסרו כחלק מחבילת הנכסים

   מערכת Gradle יוצרת את קובץ המניפסט לכל חבילת נכסים ומציגה את ספריית assets/ הפלט.

9. (אופציונלי) מגדירים את ה-App Bundle כך שיתמוך בפורמטים שונים של דחיסת טקסטורה.

שילוב עם ספריית Play Asset Delivery

מטמיעים את ה-API הזה בהתאם לסוג המסירה של חבילת הנכסים שרוצים לגשת אליה. השלבים האלה מוצגים בתרשים הזרימה הבא.

איור 1. תרשים זרימה לגישה לחבילות של נכסים

‫Play Core Native SDK מספק את קובץ הכותרת play/asset_pack.h ב-C לבקשת חבילות נכסים, לניהול הורדות ולגישה לנכסים.

הגדרת סביבת הפיתוח ל-Play Core Native SDK

1. בצע אחת מהפעולות הבאות:

   • מתקינים את Android Studio בגרסה 4.0 ואילך. משתמשים בממשק המשתמש של SDK Manager כדי להתקין את Android SDK Platform בגרסה 10.0 (רמת API‏ 29).
   • מתקינים את כלי שורת הפקודה של Android SDK ומשתמשים ב-sdkmanager כדי להתקין את Android SDK Platform בגרסה 10.0 (רמת API‏ 29).

2. כדי להכין את Android Studio לפיתוח מקורי, משתמשים בSDK Manager כדי להתקין את הגרסה העדכנית של CMake ושל Android Native Development Kit‏ (NDK). מידע נוסף על יצירה או ייבוא של פרויקטים מקוריים זמין במאמר תחילת העבודה עם NDK.

3. מורידים את קובץ ה-ZIP ומחלצים אותו לצד הפרויקט.

   קישור להורדה	גודל	סיכום ביקורת (checksum)‏ SHA-256
   play-core-native-sdk-1.15.3.zip	‫37.8 MiB	9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

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.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 בנתונים שנאספים הם נפרדים ועצמאיים מאיסוף יחסי התלות של הספריות שמוצהרים ב-Gradle על ידי Google כשאתם מעלים את חבילת האפליקציה שלכם ל-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 כדי להתחיל את ההורדה ואיך לגשת לחבילות שהורדו. הקטעים האלה רלוונטיים לחבילות נכסים מסוג 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()

קבלת מידע להורדה על חבילות נכסים

האפליקציות נדרשות לחשוף את גודל ההורדה לפני שליפת חבילת הנכסים. אפשר להשתמש בפונקציה AssetPackManager_requestInfo() כדי להתחיל בקשה אסינכרונית לגבי גודל ההורדה והאם החבילה כבר בהורדה. לאחר מכן משתמשים בפונקציה AssetPackManager_getDownloadState() כדי לבדוק את מצב ההורדה (לדוגמה, אפשר להפעיל את הפונקציה הזו פעם אחת בכל פריים בלולאת המשחק). אם בקשה נכשלת, צריך לבדוק את קודי השגיאה של חבילת הנכסים.

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. מידע על אופן השימוש בסוג הזה זמין במאמר קבלת מידע על הורדות.

הורדות גדולות

אם ההורדה גדולה מ-200MB והמשתמש לא מחובר ל-Wi-Fi, ההורדה לא מתחילה עד שהמשתמש נותן את הסכמתו המפורשת להמשיך בהורדה באמצעות חיבור לחבילת גלישה. באופן דומה, אם ההורדה גדולה והמשתמש מאבד את חיבור ה-Wi-Fi, ההורדה מושהית ונדרשת הסכמה מפורשת כדי להמשיך באמצעות חיבור לחבילת גלישה. חבילה מושהית היא במצב WAITING_FOR_WIFI. כדי להפעיל את תהליך ממשק המשתמש שבו מוצגת למשתמש בקשת הסכמה, משתמשים בקוד הבא:

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

נדרש אישור מהמשתמש

אם החבילה בסטטוס REQUIRES_USER_CONFIRMATION, ההורדה לא תמשיך עד שהמשתמש יאשר את תיבת הדו-שיח שמוצגת עם AssetPackManager_showConfirmationDialog(). הסטטוס הזה יכול להופיע אם האפליקציה לא מזוהה על ידי Play. חשוב לזכור שבמקרה הזה, אם מתקשרים אל AssetPackManager_showConfirmationDialog(), האפליקציה מתעדכנת. אחרי העדכון, שולחים שוב בקשה לקבלת הנכסים.

גישה לחבילות של נכסים

אפשר לגשת לחבילת נכסים באמצעות קריאות למערכת הקבצים אחרי שבקשת ההורדה מגיעה למצב 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() כדי לתזמן את ההסרה של חבילת נכסים.

השלבים הבאים

בדיקה של Play Asset Delivery באופן מקומי ומ-Google Play.