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

במדריך הזה מוסבר איך לתמוך בעדכונים לאפליקציה מתוך האפליקציה באמצעות Unreal Engine. יש מדריכים נפרדים למקרים שבהם ההטמעה משתמשת בשפת התכנות Kotlin או Java, ולמקרים שבהם ההטמעה משתמשת בקוד Native ‏(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 ובכל הגרסאות הבאות.

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

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

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

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

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

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

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

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();

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

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

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

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

מגדירים את העדיפות באמצעות ממשק ה-API של Google Play למפתחים, כפי שמתואר במאמרי העזרה של ה-API של Play למפתחים. צריך לציין את העדיפות של העדכון באפליקציה במשאב Edit.tracks שמועבר ב-method‏ 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, אבל אפשר להגדיר אותו באמצעות UAppUpdateOptions::SetAssetPackDeletionAllowed כדי להגדיר אותו ל-true:

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

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

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

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

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

השלבים הבאים

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