תמיכה בעדכונים בתוך האפליקציה (מקור)

במדריך הזה מוסבר איך להוסיף תמיכה בעדכונים בתוך האפליקציה באפליקציה באמצעות קוד מקורי (C או C++‎). יש מדריכים נפרדים למקרים שבהם ההטמעה משתמשת בשפת התכנות Kotlin או בשפת התכנות Java, ולמקרים שבהם ההטמעה משתמשת ב-Unity או ב-Unreal Engine.

סקירה כללית של Native SDK

‫Play Core Native SDK הוא חלק ממשפחת Play Core SDK. ‫Native SDK כולל קובץ כותרת C‏, app_update.h, שעוטף את AppUpdateManager מתוך Java Play In-App Update Library. קובץ הכותרת הזה מאפשר לאפליקציה שלכם לקרוא לממשק ה-API לעדכונים בתוך האפליקציה ישירות מהקוד המקורי.

הגדרת סביבת הפיתוח

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.

אחרי שמשלבים את Play Core Native SDK בפרויקט, צריך לכלול את השורה הבאה בקבצים שמכילים קריאות ל-API:

#include "play/app_update.h"

הפעלת ה-API לעדכון בתוך האפליקציה

בכל פעם שמשתמשים ב-API לעדכון בתוך האפליקציה, צריך לאתחל אותו קודם באמצעות קריאה לפונקציה AppUpdateManager_init(), כמו בדוגמה הבאה שנוצרה באמצעות android_native_app_glue.h:

void android_main(android_app* app) {
  app->onInputEvent = HandleInputEvent;

  AppUpdateErrorCode error_code =
    AppUpdateManager_init(app->activity->vm, app->activity->clazz);
  if (error_code == APP_UPDATE_NO_ERROR) {
    // You can use the API.
  }
}

בדיקה אם יש עדכונים שצריך להתקין

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

AppUpdateErrorCode error_code = AppUpdateManager_requestInfo()

if (error_code == APP_UPDATE_NO_ERROR) {
    // The request has successfully started, check the result using
    // AppUpdateManager_getInfo.
}

אפשר לעקוב אחרי התהליך והתוצאה של הבקשה באמצעות AppUpdateManager_getInfo(). בנוסף לקוד השגיאה, הפונקציה הזו מחזירה מבנה אטום של AppUpdateInfo, שאפשר להשתמש בו כדי לאחזר מידע על בקשת העדכון. לדוגמה, יכול להיות שתרצו לקרוא לפונקציה הזו בכל לולאת משחק עד שהיא תחזיר תוצאה שאינה null עבור info:

AppUpdateInfo* info;
GameUpdate() {

   // Keep calling this in every game loop until info != nullptr
   AppUpdateErrorCode error_code = AppUpdateManager_getInfo(&info);

   if (error_code == APP_UPDATE_NO_ERROR && info != nullptr) {
       // Successfully started, check the result in the following functions
   }
...
}

בדיקת עדכונים ישנים

בנוסף לבדיקה אם יש עדכון זמין, כדאי גם לבדוק כמה זמן עבר מאז שהמשתמש קיבל לאחרונה הודעה על עדכון דרך חנות Play. המידע הזה יכול לעזור לכם להחליט אם כדאי להתחיל עדכון גמיש או עדכון מיידי. לדוגמה, אפשר לחכות כמה ימים לפני שמודיעים למשתמש על עדכון גמיש, וכמה ימים אחרי זה לפני שדורשים עדכון מיידי.

כדי לבדוק כמה ימים עברו מאז שהעדכון הפך לזמין דרך חנות Play, משתמשים ב-AppUpdateInfo_getClientVersionStalenessDays():

int32_t staleness_days = AppUpdateInfo_getClientVersionStalenessDays(info);

בדיקת סדר העדיפויות של העדכונים

ממשק Google Play Developer API מאפשר להגדיר את העדיפות של כל עדכון. כך האפליקציה יכולה להחליט עד כמה מומלץ למשתמש לעדכן אותה. לדוגמה, אפשר להשתמש באסטרטגיה הבאה להגדרת עדיפות העדכון:

• שיפורים קלים בממשק המשתמש: עדכון בסדר עדיפות נמוך. לא נדרש עדכון גמיש או עדכון מיידי. העדכון יתבצע רק כשאין אינטראקציה של המשתמש עם האפליקציה.
• שיפורים בביצועים: עדכון בעדיפות בינונית. אפשר לבקש עדכון גמיש.
• עדכון אבטחה קריטי: עדכון בעדיפות גבוהה; צריך לבקש עדכון מיידי.

כדי לקבוע את העדיפות, מערכת Google Play משתמשת בערך מספרי שלם בין 0 ל-5, כאשר 0 הוא ברירת המחדל ו-5 היא העדיפות הגבוהה ביותר. כדי להגדיר את העדיפות של עדכון, צריך להשתמש בשדה inAppUpdatePriority בקטע Edits.tracks.releases ב-Google Play Developer API. כל הגרסאות החדשות שנוספו לגרסה נחשבות בעדיפות זהה לגרסה. אפשר להגדיר עדיפות רק כשמשיקים גרסה חדשה, ואי אפשר לשנות אותה מאוחר יותר.

מגדירים את העדיפות באמצעות Google Play Developer API, כמו שמתואר במסמכי התיעוד של Play Developer API. מציינים את העדיפות של העדכון באפליקציה במשאב Edit.tracks שמועבר בשיטה Edit.tracks: update. בדוגמה הבאה מוצג תהליך של פרסום אפליקציה עם קוד גרסה 88 ועם inAppUpdatePriority 5:

{
  "releases": [{
      "versionCodes": ["88"],
      "inAppUpdatePriority": 5,
      "status": "completed"
  }]
}

בקוד של האפליקציה, אפשר לבדוק את רמת העדיפות של עדכון מסוים באמצעות AppUpdateInfo_getPriority():

int32_t priority = AppUpdateInfo_getPriority(info);

התחלת עדכון

אחרי שתאשרו שיש עדכון זמין, תוכלו לבקש עדכון באמצעות AppUpdateManager_requestStartUpdate(). לפני שמבקשים עדכון, צריך לקבל אובייקט AppUpdateInfo עדכני וליצור אובייקט AppUpdateOptions כדי להגדיר את תהליך העדכון. אובייקט AppUpdateOptions מגדיר אפשרויות לתהליך עדכון בתוך האפליקציה, כולל האם העדכון צריך להיות גמיש או מיידי.

בדוגמה הבאה נוצר אובייקט AppUpdateOptions לתהליך עדכון גמיש:

// Creates an AppUpdateOptions configuring a flexible in-app update flow.
AppUpdateOptions* options;
AppUpdateErrorCode error_code = AppUpdateOptions_createOptions(APP_UPDATE_TYPE_FLEXIBLE, &options);

בדוגמה הבאה נוצר אובייקט AppUpdateOptions לתהליך עדכון מיידי:

// Creates an AppUpdateOptions configuring an immediate in-app update flow.
AppUpdateOptions* options;
AppUpdateErrorCode error_code = AppUpdateOptions_createOptions(APP_UPDATE_TYPE_IMMEDIATE, &options);

האובייקט AppUpdateOptions מכיל גם את השדה AllowAssetPackDeletion שקובע אם העדכון יכול למחוק חבילות נכסים במקרה של נפח אחסון מוגבל במכשיר. כברירת מחדל, השדה הזה מוגדר כ-false, אבל אפשר להשתמש בשיטה AppUpdateOptions_setAssetPackDeletionAllowed() כדי להגדיר אותו כ-true:

bool allow = true;
AppUpdateErrorCode error_code = AppUpdateOptions_setAssetPackDeletionAllowed(options, allow);

אחרי שיש לכם אובייקט AppUpdateInfo עדכני ואובייקט AppUpdateOptions מוגדר כראוי, קוראים ל-AppUpdateManager_requestStartUpdate() כדי לבקש באופן אסינכרוני תהליך עדכון, ומעבירים פעילות של Android‏ jobject כפרמטר הסופי.

AppUpdateErrorCode request_error_code =
AppUpdateManager_requestStartUpdate(info, options, app->activity->clazz);

כדי לפנות משאבים, צריך להפסיק את השימוש במופעים של AppUpdateInfo ושל AppUpdateOptions שלא זקוקים להם יותר. לשם כך, קוראים ל-AppUpdateInfo_destroy() ול-AppUpdateOptions_destroy(), בהתאמה.

AppUpdateInfo_destroy(info);
AppUpdateOptions_destroy(options);

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

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

AppUpdateStatus status = AppUpdateInfo_getStatus(info);
if (status == APP_UPDATE_DOWNLOADED) {
    AppUpdateErrorCode error_code = AppUpdateManager_requestCompleteUpdate();
    if (error_code != APP_UPDATE_NO_ERROR)
    {
      // There was an error while completing the update flow.
    }
}

כדי לפנות משאבים, מפעילים את הפונקציה AppUpdateManager_destroy() אחרי שהאפליקציה מסיימת להשתמש ב-API.

טיפול בשגיאות

בקטע הזה מפורטים פתרונות לשגיאות נפוצות שמצוינות על ידי ערכים ספציפיים של AppUpdateErrorCode:

• קוד השגיאה -110, APP_UPDATE_INITIALIZATION_NEEDED מציין שה-API לא אותחל בהצלחה. שולחים קריאה ל-AppUpdateManager_init() כדי לאתחל את ה-API.
• קוד השגיאה -4, APP_UPDATE_INVALID_REQUEST מציין שחלק מהפרמטרים של בקשת תהליך העדכון הם בפורמט שגוי. צריך לוודא שאובייקטים AppUpdateInfo ו-AppUpdateOptions לא ריקים ושהפורמט שלהם תקין.
• קוד השגיאה -5, APP_UPDATE_UNAVAILABLE מציין שאין עדכון רלוונטי זמין. מוודאים שלגרסת היעד יש את אותו שם חבילה, מזהה אפליקציה ומפתח חתימה. אם יש עדכון זמין, מנקים את המטמון של האפליקציה ומתקשרים שוב אל AppUpdateManager_requestAppUpdateInfo() כדי לרענן את AppUpdateInfo.
• קוד השגיאה -6, APP_UPDATE_NOT_ALLOWED מציין שאסור להשתמש בסוג העדכון שמצוין באובייקט AppUpdateOption. לפני שמתחילים את תהליך העדכון, בודקים אם האובייקט AppUpdateInfo מציין שסוג העדכון מותר.

השלבים הבאים

בודקים את העדכונים בתוך האפליקציה כדי לוודא שההטמעה פועלת כמו שצריך.