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

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

סקירה כללית על Unreal Engine SDK

Play In-App Updates API הוא חלק ממשפחת Play Core SDK. ה-API של Unreal Engine מציע את הכיתה UInAppUpdatesManager לטיפול בתקשורת בין האפליקציה ל-Play API. אחרי שליחת הבקשה, האפליקציה יכולה לבדוק את סטטוס הבקשה באמצעות EAppUpdateErrorCode.

גרסאות נתמכות של Unreal Engine

הפלאגין תומך ב-Unreal Engine 5.0 ובכל הגרסאות הבאות.

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

  1. מורידים את Play Unreal Engine Plugin מהמאגר של GitHub.

  2. מעתיקים את התיקייה GooglePlay לתוך התיקייה Plugins בפרויקט ב-Unreal Engine.

  3. פותחים את הפרויקט ב-Unreal Engine ולוחצים על Edit (עריכה) → Plugins (פלאגינים).

  4. מחפשים את Google Play ומסמנים את התיבה מופעל.

  5. מפעילים מחדש את פרויקט המשחק ומפעילים build.

  6. פותחים את הקובץ Build.cs של הפרויקט ומוסיפים את המודול PlayInAppUpdates ל-PublicDependencyModuleNames:

    using UnrealBuildTool;

public class MyGame : ModuleRules
{
  public MyGame(ReadOnlyTargetRules Target) : base(Target)
  {
    // ...

    PublicDependencyModuleNames.Add("PlayInAppUpdates");

    // ...
  }
}

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

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

MyClass.h

void MyClass::OnRequestInfoOperationCompleted(
  EAppUpdateErrorCode ErrorCode,
  UAppUpdateInfo* UpdateInfo)
{
  // Check the resulting error code.
  if (ErrorCode == EAppUpdateErrorCode::AppUpdate_NO_ERROR)
  {
    // Check AppUpdateInfo's UpdateAvailability, UpdatePriority,
    // IsUpdateTypeAllowed(), ... and decide whether to ask the user
    // to start an in-app update.
  }
}

MyClass.cpp

void MyClass::CheckForUpdateAvailability()
{
  // Create a delegate to bind the callback function.
  FRequestInfoOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnRequestInfoOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnRequestInfoOperationCompleted);

  // Initiate the request info operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->RequestInfo(Delegate);
}

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

בדיקת העדכון

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

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

int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();

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

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"
  }]
}

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

int32 Priority = UpdateInfo->GetPriority();

התחלת עדכון

אחרי שמאשרים שיש עדכון זמין, אפשר לבקש עדכון באמצעות UInAppUpdatesManager::StartUpdate. לפני ששולחים בקשה לעדכון, חשוב לוודא שיש אובייקט UAppUpdateInfo עדכני. צריך גם ליצור אובייקט UAppUpdateOptions כדי להגדיר את תהליך העדכון.

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

// Creates an UAppUpdateOptions defining an immediate in-app
// update flow and its parameters.
UAppUpdateOptions* Options = NewObject<UAppUpdateOptions>();
Options->CreateOptions(EAppUpdateType::AppUpdate_TYPE_IMMEDIATE);

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

// Creates an UAppUpdateOptions defining a flexible in-app
// update flow and its parameters.
UAppUpdateOptions* Options = NewObject<UAppUpdateOptions>();
Options->CreateOptions(EAppUpdateType::AppUpdate_TYPE_FLEXIBLE);

האובייקט UAppUpdateOptions מכיל גם את הפונקציה IsAssetPackDeletionAllowed שמחזירה אם מותר למחוק חבילות נכסים במסגרת העדכון במקרה של נפח אחסון מוגבל במכשיר. כברירת מחדל, השדה מוגדר כ-false, אבל אפשר להגדיר אותו כ-true באמצעות UAppUpdateOptions::SetAssetPackDeletionAllowed:

// Sets the AssetPackDeletionAllowed field to true.
Options->SetAssetPackDeletionAllowed(true);

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

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

אחרי שיוצרים אובייקט UAppUpdateInfo עדכני ואובייקט UAppUpdateOptions שהוגדר בצורה נכונה, אפשר לבצע קריאה ל-UInAppUpdatesManager::StartUpdate כדי לבקש תהליך עדכון.

MyClass.h

void MyClass::OnStartUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

MyClass.cpp

// .cpp
void MyClass::StartUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnStartUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnStartUpdateOperationCompleted);

  // Initiate the start update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->StartUpdate(UpdateInfo, UpdateOptions, Delegate);
}

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

MyClass.h

void MyClass::OnCompleteUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

MyClass.cpp

void MyClass::CompleteFlexibleUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnCompleteUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnCompleteUpdateOperationCompleted);

  // Initiate the complete update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->CompleteUpdate(UpdateInfo, UpdateOptions, Delegate);
}

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

אחרי שיוצרים אובייקט UAppUpdateInfo עדכני ואובייקט UAppUpdateOptions שהוגדר בצורה נכונה, אפשר לבצע קריאה ל-InAppUpdatesManager::StartUpdate כדי לבקש תהליך עדכון.

MyClass.h

void MyClass::OnStartUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

MyClass.cpp

void MyClass::StartUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnStartUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnStartUpdateOperationCompleted);

  // Initiate the start update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->StartUpdate(UpdateInfo, UpdateOptions, Delegate);
}

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

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

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

  • אם הפונקציה UInAppUpdatesManager::StartUpdate מחזירה את השגיאה AppUpdate_INVALID_REQUEST, סימן ש-UAppUpdateInfo לא תקין. לפני שמתחילים את תהליך העדכון, צריך לוודא שהאובייקט UAppUpdateInfo שמוחזר מ-UInAppUpdatesManager::RequestInfo הוא לא null.
  • אם הפונקציה UInAppUpdatesManager::StartUpdate מחזירה את השגיאה AppUpdate_NOT_ALLOWED, המשמעות היא שהאובייקט UAppUpdateOptions מציין סוג עדכון שאינו מורשה לעדכון הזמין. לפני שמתחילים את תהליך העדכון, בודקים אם האובייקט UAppUpdateInfo מציין שסוג העדכון שנבחר מותר.

השלבים הבאים

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