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

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

סקירה כללית על 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.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
           ...)
   

איסוף נתונים

ערכת ה-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 של העדכון בתוך האפליקציה

בכל פעם שמשתמשים ב-In-app update 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);

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

באמצעות 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, אבל אפשר להשתמש ב-method‏ 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 מציין שסוגי העדכונים מותרים.

השלבים הבאים

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