Mendukung update dalam aplikasi (Unity)

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

Menyiapkan lingkungan pengembangan

Download rilis terbaru Plugin Play In-App Update Unity dari paket Google untuk Unity.

Catatan: Download dan penggunaan Google Play Unity Plugins tunduk pada Persyaratan Layanan Software Development Kit Play Core. Dengan mendownload dan menggunakan Google Play Unity Plugins, Anda menyetujui Persyaratan Layanan Software Development Kit Play Core.

Ringkasan Unity SDK

Play in-app update API adalah bagian dari kelompok Play Core SDK. Plugin Unity menawarkan class AppUpdateManager untuk menangani komunikasi antara aplikasi Anda dan Play API. Anda harus membuat instance class ini sebelum dapat menggunakannya untuk mengelola update dalam aplikasi:

AppUpdateManager appUpdateManager = new AppUpdateManager();

Memeriksa ketersediaan update

Sebelum meminta update, periksa apakah update tersedia untuk aplikasi Anda. Gunakan AppUpdateManager untuk memeriksa update di coroutine:

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.
  }
}

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

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 ClientVersionStalenessDays untuk memeriksa jumlah hari sejak update tersedia di Play Store:

var stalenessDays = appUpdateInfoOperation.ClientVersionStalenessDays;

Memeriksa prioritas update

Dengan Google Play Developer API, Anda dapat menyetel prioritas setiap update. Hal ini memungkinkan aplikasi Anda menentukan seberapa kuat rekomendasi update kepada pengguna. Sebagai contoh, pertimbangkan strategi berikut untuk menyetel 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 di dokumentasi Play Developer API. Prioritas update dalam aplikasi harus ditentukan di resource Edit.tracks yang diteruskan di 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 UpdatePriority:

var priority = appUpdateInfoOperation.UpdatePriority;

Memulai update

Setelah memastikan update tersedia, Anda dapat meminta update menggunakan AppUpdateManager.StartUpdate(). Sebelum meminta update, pastikan Anda memiliki objek AppUpdateInfo terbaru. Anda juga harus membuat objek AppUpdateOptions untuk mengonfigurasi alur update.

Contoh berikut membuat objek AppUpdateOptions untuk alur update langsung:

// Creates an AppUpdateOptions defining an immediate in-app
// update flow and its parameters.
var appUpdateOptions = AppUpdateOptions.ImmediateAppUpdateOptions();

Contoh berikut membuat objek AppUpdateOptions untuk alur update yang fleksibel:

// Creates an AppUpdateOptions defining a flexible in-app
// update flow and its parameters.
var appUpdateOptions = AppUpdateOptions.FlexibleAppUpdateOptions();

Objek AppUpdateOptions juga berisi kolom AllowAssetPackDeletion yang menentukan apakah update diizinkan untuk menghapus paket aset jika penyimpanan perangkat terbatas. Kolom ini disetel ke false secara default, tetapi Anda dapat meneruskan argumen opsional allowAssetPackDeletion ke ImmediateAppUpdateOptions() atau FlexibleAppUpdateOptions() untuk menyetelnya ke 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);

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

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

Menangani update fleksibel

Setelah memiliki objek AppUpdateInfo terbaru dan objek AppUpdateOptions yang dikonfigurasi dengan benar, Anda dapat memanggil AppUpdateManager.StartUpdate() untuk meminta alur update secara asinkron.

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

}

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

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

Menangani update langsung

Setelah memiliki objek AppUpdateInfo terbaru dan objek AppUpdateOptions yang dikonfigurasi dengan benar, Anda dapat memanggil AppUpdateManager.StartUpdate() untuk meminta alur update secara asinkron.

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

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 StartUpdate() memunculkan ArgumentNullException, artinya AppUpdateInfo adalah null. Pastikan objek AppUpdateInfo yang ditampilkan dari GetAppUpdateInfo() tidak null sebelum memulai alur update.
• Jika PlayAsyncOperation menampilkan kode error ErrorUpdateUnavailable, pastikan versi aplikasi terbaru tersedia yang memiliki ID aplikasi dan kunci penandatanganan yang sama.
• Jika PlayAsyncOperation menampilkan kode error ErrorUpdateNotAllowed, artinya objek AppUpdateOptions menunjukkan jenis update yang tidak diizinkan untuk update yang tersedia. Periksa apakah objek AppUpdateInfo menunjukkan bahwa jenis update yang dipilih diizinkan sebelum memulai alur update.

Langkah berikutnya

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