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

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

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

OpenUPM-CLI

אם OpenUPM CLI מותקן, אפשר להתקין את המרשם של OpenUPM באמצעות הפקודה הבאה:

openupm add com.google.play.appupdate

OpenUPM

  1. פותחים את הגדרות מנהל החבילות על ידי בחירה באפשרות בתפריט של Unity‏ Edit > Project Settings > Package Manager.

  2. מוסיפים את OpenUPM כמאגר ברמת ההיקף לחלון Package Manager:

    Name: package.openupm.com
URL: https://package.openupm.com
Scopes: com.google.external-dependency-manager
  com.google.play.common
  com.google.play.core
  com.google.play.appupdate

  3. פותחים את תפריט מנהל החבילות על ידי בחירה באפשרות בתפריט של Unity‏ Window (חלון) > Package Manager (מנהל החבילות).

  4. בתפריט הנפתח של היקף הניהול, בוחרים באפשרות My Registries.

  5. בוחרים את החבילה Google Play Integrity plugin for Unity מרשימת החבילות ולוחצים על Install.

ייבוא מ-GitHub

  1. מורידים את הגרסה האחרונה של .unitypackage מ-GitHub.

  2. מייבאים את הקובץ .unitypackage על ידי בחירה באפשרות התפריט ב-Unity‏ נכסים > ייבוא חבילה > חבילה מותאמת אישית וייבוא כל הפריטים.

סקירה כללית על Unity SDK

ממשק ה-API של עדכונים בתוך האפליקציה ב-Play הוא חלק ממשפחת Play Core SDK. הפלאגין של Unity כולל את הכיתה AppUpdateManager לטיפול בתקשורת בין האפליקציה ל-Play API. צריך ליצור מופע של הכיתה הזו כדי שתוכלו להשתמש בה לניהול עדכונים באפליקציה:

AppUpdateManager appUpdateManager = new AppUpdateManager();

בודקים אם יש עדכונים שזמינים להתקנה

לפני ששולחים בקשה לעדכון, כדאי לבדוק אם יש עדכון זמין לאפליקציה. אפשר להשתמש ב-AppUpdateManager כדי לבדוק אם יש עדכון בפונקציית קורוטין:

IEnumerator CheckForUpdate()
{
  PlayAsyncOperation<AppUpdateInfo, AppUpdateErrorCode> appUpdateInfoOperation =
    appUpdateManager.GetAppUpdateInfo();

  // Wait until the asynchronous operation completes.
  yield return appUpdateInfoOperation;

  if (appUpdateInfoOperation.IsSuccessful)
  {
    var appUpdateInfoResult = appUpdateInfoOperation.GetResult();
    // Check AppUpdateInfo's UpdateAvailability, UpdatePriority,
    // IsUpdateTypeAllowed(), etc. and decide whether to ask the user
    // to start an in-app update.
  }
  else
  {
    // Log appUpdateInfoOperation.Error.
  }
}

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

בדיקת עדכניות העדכון

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

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

var stalenessDays = appUpdateInfoOperation.ClientVersionStalenessDays;

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

באמצעות ממשק ה-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"
  }]
}

בקוד של האפליקציה, אפשר לבדוק את רמת העדיפות של עדכון נתון באמצעות UpdatePriority:

var priority = appUpdateInfoOperation.UpdatePriority;

התחלת עדכון

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

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

// Creates an AppUpdateOptions defining an immediate in-app
// update flow and its parameters.
var appUpdateOptions = AppUpdateOptions.ImmediateAppUpdateOptions();

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

// Creates an AppUpdateOptions defining a flexible in-app
// update flow and its parameters.
var appUpdateOptions = AppUpdateOptions.FlexibleAppUpdateOptions();

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

// Creates an AppUpdateOptions for an immediate flow that allows
// asset pack deletion.
var appUpdateOptions =
  AppUpdateOptions.ImmediateAppUpdateOptions(allowAssetPackDeletion: true);

// Creates an AppUpdateOptions for a flexible flow that allows asset
// pack deletion.
var appUpdateOptions =
  AppUpdateOptions.FlexibleAppUpdateOptions(allowAssetPackDeletion: true);

השלבים הבאים משתנים בהתאם לבקשת העדכון: עדכון גמיש או עדכון מיידי.

טיפול בעדכון גמיש

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

IEnumerator StartFlexibleUpdate()
{
  // Creates an AppUpdateRequest that can be used to monitor the
  // requested in-app update flow.
  var startUpdateRequest = appUpdateManager.StartUpdate(
    // The result returned by PlayAsyncOperation.GetResult().
    appUpdateInfoResult,
    // The AppUpdateOptions created defining the requested in-app update
    // and its parameters.
    appUpdateOptions);

  while (!startUpdateRequest.IsDone)
  {
  // For flexible flow,the user can continue to use the app while
  // the update downloads in the background. You can implement a
  // progress bar showing the download status during this time.
  yield return null;
  }

}

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

IEnumerator CompleteFlexibleUpdate()
{
  var result = appUpdateManager.CompleteUpdate();
  yield return result;

  // If the update completes successfully, then the app restarts and this line
  // is never reached. If this line is reached, then handle the failure (e.g. by
  // logging result.Error or by displaying a message to the user).
}

טיפול בעדכון מיידי

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

IEnumerator StartImmediateUpdate()
{
  // Creates an AppUpdateRequest that can be used to monitor the
  // requested in-app update flow.
  var startUpdateRequest = appUpdateManager.StartUpdate(
    // The result returned by PlayAsyncOperation.GetResult().
    appUpdateInfoResult,
    // The AppUpdateOptions created defining the requested in-app update
    // and its parameters.
    appUpdateOptions);
  yield return startUpdateRequest;

  // If the update completes successfully, then the app restarts and this line
  // is never reached. If this line is reached, then handle the failure (for
  // example, by logging result.Error or by displaying a message to the user).
}

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

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

בקטע הזה מתוארים פתרונות לשגיאות נפוצות.

  • אם StartUpdate() מחזירה ArgumentNullException, המשמעות היא ש-AppUpdateInfo הוא null. לפני שמתחילים בתהליך העדכון, צריך לוודא שהאובייקט AppUpdateInfo שמוחזר מ-GetAppUpdateInfo() הוא לא null.
  • אם הפונקציה PlayAsyncOperation מחזירה את קוד השגיאה ErrorUpdateUnavailable, צריך לוודא שיש גרסה מעודכנת של האפליקציה עם אותו מזהה אפליקציה ומפתח חתימה.
  • אם PlayAsyncOperation מחזיר את קוד השגיאה ErrorUpdateNotAllowed, המשמעות היא שאובייקט AppUpdateOptions מציין סוג עדכון שאינו מורשה לעדכון הזמין. לפני שמתחילים את תהליך העדכון, צריך לבדוק אם אובייקט AppUpdateInfo מציין שסוג העדכון שנבחר מותר.

השלבים הבאים

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