Mendukung update dalam aplikasi (Unreal Engine)

Panduan ini menjelaskan cara mendukung update dalam aplikasi di aplikasi Anda menggunakan Unreal Engine. Ada panduan terpisah untuk kasus saat penerapan menggunakan bahasa pemrograman Kotlin atau bahasa pemrograman Java, dan kasus saat penerapan menggunakan kode native (C/C++) atau Unity.

Ringkasan Unreal Engine SDK

Play In-App Updates API adalah bagian dari keluarga Play Core SDK. API untuk Unreal Engine menawarkan class UInAppUpdatesManager untuk menangani komunikasi antara aplikasi Anda dan Play API. Setelah permintaan dibuat, aplikasi Anda dapat memeriksa status permintaan menggunakan EAppUpdateErrorCode.

Versi Unreal Engine yang didukung

Plugin ini mendukung Unreal Engine 5.0 dan semua versi berikutnya.

Menyiapkan lingkungan pengembangan

Catatan: Jika sudah menggunakan plugin Ulasan dalam Aplikasi atau Update dalam Aplikasi di Unreal Engine, Anda dapat langsung ke langkah terakhir.

1. Download Plugin Unreal Engine Play dari repositori GitHub.

2. Salin folder GooglePlay di dalam folder Plugins di project Unreal Engine Anda.

3. Buka project Unreal Engine Anda, lalu klik Edit → Plugins.

4. Telusuri Google Play, lalu centang kotak Diaktifkan.

5. Mulai ulang project game dan picu build.

6. Buka file Build.cs project Anda dan tambahkan modul PlayInAppUpdates ke PublicDependencyModuleNames:

   using UnrealBuildTool;
   
   public class MyGame : ModuleRules
   {
     public MyGame(ReadOnlyTargetRules Target) : base(Target)
     {
       // ...
   
       PublicDependencyModuleNames.Add("PlayInAppUpdates");
   
       // ...
     }
   }
   

Memeriksa ketersediaan update

Sebelum meminta update, periksa apakah ada update yang tersedia untuk aplikasi Anda. Gunakan UInAppUpdatesManager::RequestInfo untuk memeriksa update:

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

Instance UAppUpdateInfo yang ditampilkan berisi status ketersediaan update. Jika update dalam aplikasi sedang berlangsung, instance juga melaporkan status update yang sedang berlangsung.

Memeriksa penghentian update

Selain memeriksa apakah update tersedia, Anda juga perlu memeriksa jumlah waktu yang telah berlalu sejak pengguna terakhir kali diberi tahu tentang update melalui Play Store. Hal ini dapat membantu Anda menentukan apakah harus melakukan inisialisasi update fleksibel atau update langsung. Misalnya, Anda mungkin menunggu beberapa hari sebelum memberi tahu pengguna dengan update fleksibel, dan beberapa hari setelahnya sebelum meminta update langsung.

Gunakan UAppUpdateInfo:GetClientVersionStalenessDays untuk memeriksa jumlah hari sejak update tersedia melalui Play Store:

int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();

Memeriksa prioritas update

Google Play Developer API memungkinkan Anda menetapkan prioritas setiap update. Hal ini memungkinkan aplikasi Anda menentukan seberapa kuat rekomendasi update kepada pengguna. Misalnya, pertimbangkan strategi berikut untuk menetapkan prioritas update:

• Peningkatan kecil pada UI: Update prioritas rendah; tidak meminta update fleksibel atau update langsung.
• Peningkatan performa: Update prioritas sedang; meminta update fleksibel.
• Update keamanan penting: Update prioritas tinggi; meminta update langsung.

Untuk menentukan prioritas, Google Play menggunakan nilai bilangan bulat antara 0 dan 5, dengan 0 adalah nilai default dan 5 adalah prioritas tertinggi. Guna menyetel prioritas untuk update, gunakan kolom inAppUpdatePriority di bawah Edits.tracks.releases di Google Play Developer API. Semua versi yang baru ditambahkan dalam rilis dianggap sebagai prioritas yang sama dengan rilis tersebut. Prioritas hanya dapat disetel saat meluncurkan rilis baru, dan tidak dapat diubah setelahnya.

Tetapkan prioritas menggunakan Google Play Developer API seperti yang dijelaskan dalam dokumentasi Play Developer API. Prioritas update dalam aplikasi harus ditentukan di resource Edit.tracks yang diteruskan dalam metode Edit.tracks: update. Contoh berikut menunjukkan perilisan aplikasi dengan kode versi 88 dan inAppUpdatePriority 5:

{
  "releases": [{
      "versionCodes": ["88"],
      "inAppUpdatePriority": 5,
      "status": "completed"
  }]
}

Dalam kode aplikasi, Anda dapat memeriksa tingkat prioritas untuk update tertentu menggunakan UAppUpdateInfo::UpdatePriority:

int32 Priority = UpdateInfo->GetPriority();

Memulai update

Setelah memastikan bahwa update tersedia, Anda dapat meminta update menggunakan UInAppUpdatesManager::StartUpdate. Sebelum meminta update, pastikan Anda memiliki objek UAppUpdateInfo terbaru. Anda juga harus membuat objek UAppUpdateOptions untuk mengonfigurasi alur update.

Contoh berikut membuat objek UAppUpdateOptions untuk alur update langsung:

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

Contoh berikut membuat objek UAppUpdateOptions untuk alur update yang fleksibel:

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

Objek UAppUpdateOptions juga berisi fungsi IsAssetPackDeletionAllowed yang menampilkan apakah update diizinkan untuk menghapus paket aset jika penyimpanan perangkat terbatas. Kolom ini ditetapkan ke false secara default, tetapi Anda dapat menetapkan kolom menggunakan UAppUpdateOptions::SetAssetPackDeletionAllowed untuk menetapkannya ke true:

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

Catatan: Gunakan opsi AllowAssetPackDeletion API dengan hati-hati agar tidak menghapus aset secara tidak sengaja. Sebelum menetapkan opsi ini ke true, Anda harus memeriksa UAppUpdateInfo::IsUpdateTypeAllowed dengan opsi AllowAssetPackDeletion ditetapkan ke false.

Langkah berikutnya bergantung pada apakah Anda meminta update fleksibel atau update langsung.

Menangani update fleksibel

Setelah memiliki objek UAppUpdateInfo terbaru dan objek UAppUpdateOptions yang dikonfigurasi dengan benar, Anda dapat memanggil UInAppUpdatesManager::StartUpdate untuk meminta alur update.

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

Untuk alur update yang fleksibel, Anda harus memicu penginstalan update aplikasi setelah download berhasil selesai. Untuk melakukannya, panggil InAppUpdatesManager::CompleteUpdate, seperti yang ditunjukkan pada contoh berikut:

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

Menangani update langsung

Setelah memiliki objek UAppUpdateInfo terbaru dan objek UAppUpdateOptions yang dikonfigurasi dengan benar, Anda dapat memanggil InAppUpdatesManager::StartUpdate untuk meminta alur update.

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

Untuk alur update langsung, Google Play menampilkan dialog konfirmasi pengguna. Saat pengguna menerima permintaan, Google Play otomatis mendownload dan menginstal update, lalu memulai ulang aplikasi ke versi yang diperbarui jika penginstalan berhasil.

Penanganan error

Bagian ini menjelaskan solusi untuk error yang biasa terjadi.

• Jika UInAppUpdatesManager::StartUpdate menampilkan error AppUpdate_INVALID_REQUEST, artinya UAppUpdateInfo tidak valid. Pastikan objek UAppUpdateInfo yang ditampilkan dari UInAppUpdatesManager::RequestInfo tidak null sebelum memulai alur update.
• Jika UInAppUpdatesManager::StartUpdate menampilkan error AppUpdate_NOT_ALLOWED, artinya objek UAppUpdateOptions menunjukkan jenis update yang tidak diizinkan untuk update yang tersedia. Periksa apakah objek UAppUpdateInfo menunjukkan bahwa jenis update yang dipilih diizinkan sebelum memulai alur update.

Langkah berikutnya

Uji update dalam aplikasi pada aplikasi Anda untuk memverifikasi bahwa integrasi berfungsi dengan benar.