إتاحة التحديثات داخل التطبيق (Unreal Engine)

يوضّح هذا الدليل كيفية إتاحة التحديثات داخل التطبيق في تطبيقك باستخدام محرّك Unreal Engine. تتوفّر أدلة منفصلة للحالات التي تستخدم فيها عملية التنفيذ لغة البرمجة Kotlin أو لغة البرمجة Java، والحالات التي تستخدم فيها عملية التنفيذ الرموز البرمجية الأصلية (C/C++‎) أو Unity.

نظرة عامة على حزمة تطوير البرامج (SDK) الخاصة بمحرّك Unreal Engine

تُعدّ واجهة Play In-App Updates API جزءًا من مجموعة حِزم تطوير البرامج (SDK) في "مكتبة Play الأساسية". توفّر واجهة برمجة التطبيقات لمحرّك Unreal Engine فئة UInAppUpdatesManager للتعامل مع الاتصال بين تطبيقك وواجهة برمجة التطبيقات Play API. بعد تقديم الطلب، يمكن لتطبيقك التحقّق من حالة الطلب باستخدام EAppUpdateErrorCode.

إصدارات Unreal Engine المتوافقة

يتوافق المكوّن الإضافي مع Unreal Engine 5.0 وجميع الإصدارات اللاحقة.

إعداد بيئة التطوير

ملاحظة: إذا سبق لك استخدام المكوّنات الإضافية In-app Reviews أو تحديثات التطبيق في 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 لمعرفة عدد الأيام التي مرّت منذ أن أصبح التحديث متاحًا في "متجر Google 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 تلقائيًا، ولكن يمكنك ضبط الحقل باستخدام UAppUpdateOptions::SetAssetPackDeletionAllowed لضبطه على true بدلاً من ذلك:

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

ملاحظة: يجب استخدام خيار واجهة برمجة التطبيقات 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 ليس فارغًا قبل بدء عملية التحديث.
• إذا عرضت UInAppUpdatesManager::StartUpdate الخطأ AppUpdate_NOT_ALLOWED، يعني ذلك أنّ العنصر UAppUpdateOptions يشير إلى نوع تحديث غير مسموح به للتحديث المتاح. تحقَّق مما إذا كان العنصر UAppUpdateInfo يشير إلى أنّ نوع التحديث المحدّد مسموح به قبل بدء عملية التحديث.

الخطوات التالية

اختبِر التحديثات داخل التطبيق للتأكّد من أنّ عملية الدمج تعمل بشكل صحيح.