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

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

סקירה כללית על SDK מקורי

Play Core Native SDK הוא חלק ממשפחת Play Core SDK. ערכת ה-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 של האפליקציה, כפי שמתואר בהמשך:

   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
           ...)
   

איסוף נתונים

ערכת ה-SDK של Play Core Native עשויה לאסוף נתונים שקשורים לגרסה כדי לאפשר ל-Google לשפר את המוצר, כולל:

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

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

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

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

int32_t staleness_days = AppUpdateInfo_getClientVersionStalenessDays(info);

בדיקת העדיפות של העדכון

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

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

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

השלבים הבאים

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