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

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

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

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

הערה: ההורדה של יישומי הפלאגין של Google Play ל-Unity והשימוש בהם כפופים ל התנאים וההגבלות של ערכת פיתוח התוכנה ליבה של Play. הורדה של יישומי פלאגין ל-Unity של Google Play ושימוש בהם מבטאים את הסכמתך ל-Play התנאים וההגבלות של Core Software Development Kit.

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

Play in-app update API הוא חלק מ-Play Core משפחת ה-SDK. האחדות הפלאגין מציע AppUpdateManager class כדי לטפל בתקשורת בין האפליקציה שלכם לבין 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 בקובץ ה- ממשק API של Google Play למפתחים. כל הגרסאות החדשות שנוספו בגרסה הן נחשבת לאותה עדיפות כמו של פריט התוכן. ניתן להגדיר עדיפות רק כאשר בתהליך השקה של גרסה חדשה, ואי אפשר לשנות אותה מאוחר יותר.

הגדרת העדיפות באמצעות ממשק API למפתחים של Google Play כפי שמתואר ב-Play ממשק 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);

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

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

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

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

השלבים הבאים

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