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

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

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

פיתוח לתכונות מותאמות

כדי לבנות את Play Asset Delivery במכשיר Android של הפרויקט, צריך לפעול לפי השלבים הבאים קובץ App Bundle לא צריך להשתמש ב-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 מספק את הכותרת C את הקובץ play/asset_pack.h כדי לבקש חבילות נכסים, לנהל הורדות, בתהליך גישה לנכסים.

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

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

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

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

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

   קישור להורדה	גודל	סיכום ביקורת (checksum) SHA-256
   play-core-native-sdk-1.14.0.zip	36MiB	782a8522d937848c83a715c9a258b95a3ff2879a7cd71855d137b41c00786a5e

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.2.2'
           implementation 'com.google.android.play:integrity:1.4.0'
           implementation 'com.google.android.play:review:2.0.1'
   
           // 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.1")
   
       // 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: לשפר את המוצר, כולל:

• שם החבילה של האפליקציה
• גרסת החבילה של האפליקציה
• גרסת ה-SDK של Play Core Native

הנתונים האלה ייאספו כשתעלו את חבילת האפליקציה אל Play Console. כדי לבטל את ההסכמה לתהליך איסוף הנתונים הזה, צריך להסיר את ייבוא של $playcoreDir/playcore-native-metadata.jar בקובץ build.gradle.

לתשומת ליבך, איסוף הנתונים הזה שקשור לשימוש שלך ב-Play Core Native SDK השימוש של 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 כדי להפעיל 'הורדות' ואיך ניגשים לחבילות שהורדתם. הקטעים האלה חלים על 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 באופן מקומי ודרך Google Play.