App Center Distribute – Pembaruan MAUI dan Xamarin Dalam Aplikasi

  • Artikel

Penting

Visual Studio App Center dijadwalkan untuk dihentikan pada 31 Maret 2025. Meskipun Anda dapat terus menggunakan Visual Studio App Center hingga sepenuhnya dihentikan, ada beberapa alternatif yang direkomendasikan yang dapat Anda pertimbangkan untuk bermigrasi.

Pelajari selengkapnya tentang garis waktu dukungan dan alternatif.

App Center Distribute akan memungkinkan pengguna Anda menginstal versi baru aplikasi saat Anda mendistribusikannya melalui App Center. Dengan versi baru aplikasi yang tersedia, SDK akan menyajikan dialog pembaruan kepada pengguna untuk mengunduh atau menunda versi baru. Setelah mereka memilih untuk memperbarui, SDK akan mulai memperbarui aplikasi Anda.

Peringatan

Google Play menganggap kode pembaruan dalam aplikasi sebagai perilaku berbahaya meskipun tidak digunakan saat runtime. Gunakan varian SDK Distribusi seperti yang diarahkan di bagian ini sebelum mengirimkan aplikasi Anda ke Google Play. Kegagalan untuk tidak menghapus kode pembaruan dalam aplikasi dapat menyebabkan ketidakpatuhan dan penghapusan aplikasi dari Google Play.

Catatan

Jika Anda menjalankan pengujian UI otomatis, pembaruan dalam aplikasi yang diaktifkan akan memblokir pengujian UI otomatis Anda karena akan mencoba mengautentikasi terhadap backend App Center. Kami menyarankan untuk tidak mengaktifkan Distribusi App Center untuk pengujian UI Anda.

Menambahkan pembaruan dalam aplikasi ke aplikasi Anda

Ikuti bagian Memulai jika Anda belum menyiapkan dan memulai SDK di aplikasi Anda.

1. Tambahkan modul Distribusi App Center

App Center SDK dirancang dengan pendekatan modular – pengembang hanya perlu mengintegrasikan modul layanan yang mereka minati.

Visual Studio untuk Mac

  • Buka Visual Studio untuk Mac.
  • Klik Buka File> dan pilih solusi Anda.
  • Di navigator solusi, klik kanan bagian Paket , dan pilih Tambahkan paket NuGet....
  • Cari App Center, dan instal App Center Distribute.
  • Klik Tambahkan Paket.

Visual Studio untuk Windows

  • Buka Visual Studio untuk Windows.
  • Klik Buka File> dan pilih solusi Anda.
  • Di navigator solusi, klik kanan Referensi dan pilih Kelola Paket NuGet.
  • Cari App Center, dan instal Microsoft.AppCenter.Distribute.

Konsol Manajer Paket

  • Buka konsol di Visual Studio. Untuk melakukan ini, pilih Alat>NuGet Package Manager>Package Manager Console.
  • Jika Anda bekerja di Visual Studio untuk Mac, pastikan Anda telah menginstal Ekstensi Manajemen Paket NuGet. Untuk ini, pilihEkstensiVisual Studio>, cari NuGet dan instal, jika perlu.
  • Ketik perintah berikut di konsol:
Install-Package Microsoft.AppCenter.Distribute

Catatan

Jika Anda menggunakan App Center SDK dalam proyek portabel (seperti Xamarin.Forms), Anda harus menginstal paket di setiap proyek: yang portabel, Android, dan iOS. Untuk melakukannya, Anda harus membuka setiap sub-proyek dan mengikuti langkah-langkah terkait yang dijelaskan di bagian Visual Studio untuk Mac atau Visual Studio untuk Windows .

Catatan

Android 10 atau lebih tinggi memiliki batasan aktivitas peluncuran dari latar belakang. Silakan lihat artikel tentang pembatasan memulai aktivitas dari latar belakang.

Catatan

Aplikasi yang berjalan di Android 10 (edisi Go) tidak dapat menerima izin SYSTEM_ALERT_WINDOW . Silakan lihat artikel tentang SYSTEM_ALERT_WINDOW di perangkat Go.

Catatan

Dimulai dengan Android 11, ACTION_MANAGE_OVERLAY_PERMISSION niat selalu membawa pengguna ke layar Pengaturan tingkat atas, di mana pengguna dapat memberikan atau mencabut SYSTEM_ALERT_WINDOW izin untuk aplikasi. Silakan lihat artikel tentang pembaruan izin di Android 11.

2. Mulai Distribusi App Center

Konfigurasikan App Center SDK dengan memanggil AppCenter.Start(...) seperti yang dijelaskan dalam panduan Memulai.

Untuk aplikasi iOS Anda, buka AppDelegate.cs dan tambahkan baris berikut sebelum panggilan ke LoadApplication:

Distribute.DontCheckForUpdatesInDebug();

Langkah ini tidak diperlukan di Android tempat konfigurasi debug terdeteksi secara otomatis saat runtime.

Untuk mengaktifkan pembaruan dalam aplikasi untuk build debug di Android, panggil metode berikut dalam file MainActivity.cs proyek, dalam OnCreate metode dan sebelum LoadApplication.

Distribute.SetEnabledForDebuggableBuild(true);

Catatan

Metode ini hanya memengaruhi build debug, dan tidak berdampak pada build rilis.

2.3 [Hanya untuk iOS] Ubah Info.plist proyek

App Center SDK memeriksa url yang dialihkan ke aplikasi untuk menghindari sideloading, jadi agar pembaruan yang didistribusikan melalui portal ditangani dengan benar, Anda harus menentukan CFBundleURLSchemes di CFBundleURLTypes bagian Info.plist file:

Catatan

Info.plist, atau file daftar properti informasi adalah file teks terstruktur yang berisi informasi konfigurasi penting untuk executable yang dibundel. Anda dapat menemukan informasi selengkapnya tentang hal itu di dokumentasi pengembang Apple.

  1. Tambahkan kunci baru untuk URL types atau CFBundleURLTypes di file Info.plist Anda (jika Xcode menampilkan Info.plist Anda sebagai kode sumber).
  2. Ubah kunci item anak pertama menjadi URL Schemes atau CFBundleURLSchemes.
  3. Masukkan appcenter-${APP_SECRET} sebagai skema URL dan ganti ${APP_SECRET} dengan Rahasia Aplikasi aplikasi Anda.

Tip

Jika Anda ingin memverifikasi bahwa Anda memodifikasi Info.plist dengan benar, buka sebagai kode sumber. Ini harus berisi entri berikut dengan Rahasia Aplikasi Anda alih-alih ${APP_SECRET}:

<key>CFBundleURLTypes</key>
  <array>
      <dict>
          <key>CFBundleURLSchemes</key>
          <array>
              <string>appcenter-${APP_SECRET}</string>
          </array>
      </dict>
  </array>

Menghapus pembaruan dalam aplikasi untuk build Google Play

Google Play menganggap kode pembaruan dalam aplikasi sebagai perilaku berbahaya meskipun tidak digunakan saat runtime. Kegagalan untuk tidak menghapus kode pembaruan dalam aplikasi dapat menyebabkan ketidakpatuhan dan penghapusan aplikasi dari Google Play. Untuk mempermudah, kami menyediakan versi App Center Distribute SDK dengan API yang tersandung, sehingga satu-satunya perubahan untuk Anda adalah pertukaran dependensi.

  1. Tambahkan konfigurasi build baru bernama GooglePlay untuk Xamarin.Android dan proyek bersama Anda. Pastikan bahwa konfigurasi build proyek dipetakan dengan benar ke konfigurasi solusi yang sesuai. Lihat Instruksi Visual Studio atau Visual Studio untuk Mac untuk detail selengkapnya.

  2. Buka Xamarin.Android dan proyek bersama' .csproj di editor teks apa pun dan pindahkan referensi distribusi ke dalam grup item kondisional:

    <ItemGroup Condition=" '$(Configuration)' != 'GooglePlay' ">
    <PackageReference Include="Microsoft.AppCenter.Distribute" Version="3.3.0" />
</ItemGroup>
<ItemGroup Condition=" '$(Configuration)' == 'GooglePlay' ">
    <PackageReference Include="Microsoft.AppCenter.DistributePlay" Version="3.3.0" />
</ItemGroup>

    Catatan

    Jika Anda menggunakan format packages.config lama untuk mengelola referensi NuGet, Anda dapat bermigrasi ke format PackageReference , ikuti instruksi migrasi.

  3. Simpan perubahan Anda dan pulihkan paket NuGet.

  4. Anda dapat mengubah konfigurasi di bilah perintah di bagian atas IDE.

Menggunakan grup distribusi privat

Secara default, Distribusikan menggunakan grup distribusi publik. Jika Anda ingin menggunakan grup distribusi privat, Anda harus mengaturnya secara eksplisit melalui UpdateTrack properti .

Distribute.UpdateTrack = UpdateTrack.Private;

Catatan

Nilai defaultnya adalah UpdateTrack.Public. Properti ini hanya dapat diperbarui sebelum AppCenter.Start panggilan metode. Perubahan pada trek pembaruan tidak bertahan saat proses aplikasi dimulai ulang, dan jadi jika properti tidak selalu diperbarui sebelum AppCenter.Start panggilan, itu akan menjadi publik, secara default.

Setelah panggilan ini, jendela browser akan terbuka untuk mengautentikasi pengguna. Semua pemeriksaan pembaruan berikutnya akan mendapatkan rilis terbaru di trek privat. Trek pembaruan tidak bertahan di SDK di seluruh peluncuran aplikasi.

Jika pengguna berada di trek privat, itu berarti bahwa setelah autentikasi berhasil, mereka akan mendapatkan rilis terbaru dari grup distribusi privat tempat mereka menjadi anggotanya. Jika pengguna berada di trek publik, itu berarti mereka akan mendapatkan rilis terbaru dari grup distribusi publik apa pun.

Nonaktifkan Pemeriksaan Otomatis untuk Pembaruan

Secara default, SDK secara otomatis memeriksa rilis baru:

  • Ketika aplikasi dimulai.
  • Ketika aplikasi masuk ke latar belakang kemudian di latar depan lagi.
  • Saat mengaktifkan modul Distribusikan jika sebelumnya dinonaktifkan.

Jika Anda ingin memeriksa rilis baru secara manual, Anda dapat menonaktifkan pemeriksaan otomatis untuk pembaruan. Untuk melakukan ini, panggil metode berikut sebelum SDK dimulai:

Distribute.DisableAutomaticCheckForUpdate();

Catatan

Metode ini harus dipanggil sebelum AppCenter.Start panggilan metode.

Kemudian Anda dapat menggunakan CheckForUpdate API yang dijelaskan di bagian berikut.

Periksa Pembaruan secara Manual

Distribute.CheckForUpdate();

Catatan

Pemeriksaan manual untuk panggilan pembaruan berfungsi bahkan ketika pembaruan otomatis diaktifkan. Pemeriksaan manual untuk pembaruan diabaikan jika pemeriksaan lain sudah dilakukan. Pemeriksaan manual untuk pembaruan tidak akan diproses jika pengguna telah menunda pembaruan (kecuali versi terbaru adalah pembaruan wajib).

Menyesuaikan atau melokalisasi dialog pembaruan dalam aplikasi

1. Menyesuaikan atau melokalisasi teks

Anda dapat dengan mudah menyediakan string sumber daya Anda sendiri jika Anda ingin melokalisasi teks yang ditampilkan dalam dialog pembaruan. Lihat file string untuk iOS dalam file sumber daya ini dan file untuk Android dalam file sumber daya ini. Gunakan nama/kunci string yang sama dan tentukan nilai yang dilokalkan untuk direfleksikan dalam dialog dalam file sumber daya aplikasi Anda sendiri.

2. Sesuaikan dialog pembaruan

Anda dapat menyesuaikan tampilan dialog pembaruan default dengan menerapkan ReleaseAvailable panggilan balik. Anda perlu mendaftarkan panggilan balik sebelum memanggil AppCenter.Start seperti yang ditunjukkan dalam contoh berikut:

// In this example OnReleaseAvailable is a method name in same class
Distribute.ReleaseAvailable = OnReleaseAvailable;
AppCenter.Start(...);

Berikut adalah contoh implementasi panggilan balik yang menggantikan dialog SDK dengan yang kustom:

bool OnReleaseAvailable(ReleaseDetails releaseDetails)
{
    // Look at releaseDetails public properties to get version information, release notes text or release notes URL
    string versionName = releaseDetails.ShortVersion;
    string versionCodeOrBuildNumber = releaseDetails.Version;
    string releaseNotes = releaseDetails.ReleaseNotes;
    Uri releaseNotesUrl = releaseDetails.ReleaseNotesUrl;

    // custom dialog
    var title = "Version " + versionName + " available!";
    Task answer;

    // On mandatory update, user can't postpone
    if (releaseDetails.MandatoryUpdate)
    {
        answer = Current.MainPage.DisplayAlert(title, releaseNotes, "Download and Install");
    }
    else
    {
        answer = Current.MainPage.DisplayAlert(title, releaseNotes, "Download and Install", "Maybe tomorrow...");
    }
    answer.ContinueWith((task) =>
    {
        // If mandatory or if answer was positive
        if (releaseDetails.MandatoryUpdate || (task as Task<bool>).Result)
        {
            // Notify SDK that user selected update
            Distribute.NotifyUpdateAction(UpdateAction.Update);
        }
        else
        {
            // Notify SDK that user selected postpone (for 1 day)
            // This method call is ignored by the SDK if the update is mandatory
            Distribute.NotifyUpdateAction(UpdateAction.Postpone);
        }
    });

    // Return true if you're using your own dialog, false otherwise
    return true;
}

Catatan implementasi untuk Xamarin.Android:

Seperti yang ditunjukkan dalam contoh, Anda harus memanggil Distribute.NotifyUpdateAction(UpdateAction.UPDATE); atau Distribute.NotifyUpdateAction(UpdateAction.POSTPONE); jika panggilan balik Anda mengembalikan true.

Jika Anda tidak memanggil NotifyUpdateAction, panggilan balik akan diulang pada setiap perubahan aktivitas.

Panggilan balik dapat dipanggil lagi dengan rilis yang sama jika aktivitas berubah sebelum tindakan pengguna diberi tahu ke SDK.

Perilaku ini diperlukan untuk mencakup skenario berikut:

  • Aplikasi Anda dikirim ke latar belakang (seperti menekan HOME) lalu dilanjutkan dalam aktivitas yang berbeda.
  • Aktivitas Anda dicakup oleh yang lain tanpa meninggalkan aplikasi (seperti mengklik beberapa pemberitahuan).
  • Skenario serupa lainnya.

Dalam hal ini, aktivitas yang menghosting dialog mungkin diganti tanpa interaksi pengguna. Jadi SDK memanggil pendengar lagi sehingga Anda dapat memulihkan dialog kustom.

3. Jalankan kode jika tidak ada pembaruan yang ditemukan

Dalam kasus ketika SDK memeriksa pembaruan dan tidak menemukan pembaruan apa pun yang tersedia lebih baru dari yang saat ini digunakan, NoReleaseAvailable panggilan balik dipanggil. Ini memungkinkan Anda untuk menjalankan kode kustom dalam skenario tersebut. Anda perlu mendaftarkan panggilan balik sebelum memanggil AppCenter.Start seperti yang ditunjukkan dalam contoh berikut:

// In this example OnNoReleaseAvailable is a method name in same class
Distribute.NoReleaseAvailable = OnNoReleaseAvailable;
AppCenter.Start(...);

void OnNoReleaseAvailable()
{
    AppCenterLog.Info(LogTag, "No release available callback invoked.");
}

Mengaktifkan atau menonaktifkan DistribusiKan App Center saat runtime

Anda dapat mengaktifkan dan menonaktifkan App Center Distribute pada runtime. Jika Anda menonaktifkannya, SDK tidak akan menyediakan fungsionalitas pembaruan dalam aplikasi tetapi Anda masih dapat menggunakan layanan Distribusikan di portal App Center.

Distribute.SetEnabledAsync(false);

Untuk mengaktifkan App Center Distribute lagi, gunakan API yang sama tetapi teruskan true sebagai parameter.

Distribute.SetEnabledAsync(true);

Anda tidak perlu menunggu panggilan ini untuk melakukan panggilan API lain (seperti IsEnabledAsync) konsisten.

Status ini bertahan di penyimpanan perangkat di seluruh peluncuran aplikasi.

Catatan

Metode ini hanya boleh digunakan setelah Distribute dimulai.

Periksa apakah Distribusi App Center diaktifkan

Anda juga dapat memeriksa apakah App Center Distribute diaktifkan atau tidak:

bool enabled = await Distribute.IsEnabledAsync();

Catatan

Metode ini hanya boleh digunakan setelah Distribute dimulai, metode ini akan selalu kembali false sebelum dimulai.

Lakukan pembersihan tepat sebelum aplikasi ditutup untuk pembaruan (hanya iOS)

Daftarkan panggilan balik seperti yang ditunjukkan dalam contoh berikut:

// In this example, OnWillExitApp is a method name in same class
Distribute.WillExitApp = OnWillExitApp;

void OnWillExitApp()
{
    // Perform clean up here
}

Dengan itu, OnWillExitApp() akan dipanggil ketika Distribusi akan ditutup.

Bagaimana cara kerja pembaruan dalam aplikasi?

Catatan

Agar pembaruan dalam aplikasi berfungsi, build aplikasi harus diunduh dari tautan. Ini tidak akan berfungsi jika diinstal dari IDE atau secara manual.

Fitur pembaruan dalam aplikasi berfungsi sebagai berikut:

  1. Fitur ini hanya berfungsi dengan build RILIS (secara default) yang didistribusikan menggunakan layanan Distribusi App Center . Ini tidak akan berfungsi jika fitur Akses Terpandu iOS diaktifkan.

  2. Setelah mengintegrasikan SDK, buat versi rilis aplikasi Anda dan unggah ke App Center, pengguna di grup distribusi tersebut akan diberi tahu untuk rilis baru melalui email.

  3. Ketika setiap pengguna membuka tautan dalam email mereka, aplikasi akan diinstal di perangkat mereka. Penting bahwa mereka menggunakan tautan email untuk diinstal - kami tidak mendukung pemuatan samping. Ketika aplikasi diunduh dari tautan, SDK menyimpan informasi penting dari cookie untuk memeriksa pembaruan nanti, jika tidak, SDK tidak memiliki informasi utama tersebut.

  4. Jika aplikasi mengatur trek ke privat, browser akan terbuka untuk mengautentikasi pengguna dan mengaktifkan pembaruan dalam aplikasi. Browser tidak akan terbuka lagi selama informasi autentikasi tetap valid bahkan ketika beralih kembali ke trek publik dan kembali ke privat lagi nanti. Jika autentikasi browser berhasil, pengguna dialihkan kembali ke aplikasi secara otomatis. Jika trek bersifat publik (yang merupakan default), langkah berikutnya terjadi secara langsung.

    • Di iOS 9 dan 10, instans SFSafariViewController akan terbuka dalam aplikasi untuk mengautentikasi pengguna. Ini akan menutup dirinya sendiri secara otomatis setelah autentikasi berhasil.
    • Di iOS 11, pengalaman pengguna mirip dengan iOS 10 tetapi iOS 11 akan meminta izin kepada pengguna untuk mengakses informasi masuk. Ini adalah dialog tingkat sistem dan tidak dapat disesuaikan. Jika pengguna membatalkan dialog, mereka dapat terus menggunakan versi yang mereka uji, tetapi mereka tidak akan mendapatkan pembaruan dalam aplikasi. Mereka akan diminta untuk mengakses informasi masuk lagi saat meluncurkan aplikasi di lain waktu.

  5. Rilis baru aplikasi menunjukkan dialog pembaruan dalam aplikasi yang meminta pengguna untuk memperbarui aplikasi Anda jika:

    • iOS:

      • nilai CFBundleShortVersionString atau yang lebih tinggi
      • nilai CFBundleShortVersionString yang sama tetapi nilai yang lebih tinggi dari CFBundleVersion.
      • versinya sama tetapi pengidentifikasi unik build berbeda.

    • Android:

      • nilai versionCode atau yang lebih tinggi
      • nilai yang sama tetapi versionCode nilai yang berbeda dari versionName.

Tip

Jika Anda mengunggah apk/ipa yang sama untuk kedua kalinya, dialog TIDAK akan muncul karena biner identik. Di iOS, jika Anda mengunggah build baru dengan properti versi yang sama, build tersebut akan menampilkan dialog pembaruan. Alasan untuk ini adalah bahwa itu adalah biner yang berbeda . Di Android, biner dianggap sama jika kedua properti versi sama.

Bagaimana cara menguji pembaruan dalam aplikasi?

Anda perlu mengunggah build rilis (yang menggunakan modul Distribusikan SDK App Center) ke Portal App Center untuk menguji pembaruan dalam aplikasi, meningkatkan nomor versi setiap saat.

  1. Buat aplikasi Anda di Portal App Center jika Anda belum melakukannya.
  2. Buat grup distribusi baru dan beri nama, sehingga Anda dapat mengenalinya dimaksudkan untuk menguji fitur pembaruan dalam aplikasi.
  3. Tambahkan diri Anda sendiri (atau semua orang yang ingin Anda sertakan pada pengujian fitur pembaruan dalam aplikasi). Gunakan alamat email baru atau buang untuk ini, yang tidak digunakan untuk aplikasi tersebut di App Center. Ini memastikan bahwa pengalaman Anda dekat dengan pengalaman penguji nyata Anda.
  4. Buat build baru aplikasi Anda yang menyertakan Distribusi App Center dan berisi logika penyiapan seperti yang dijelaskan di bawah ini. Jika grup bersifat privat, jangan lupa untuk mengatur trek pembaruan dalam aplikasi privat sebelum mulai menggunakan UpdateTrack properti .
  5. Klik tombol Distribusikan rilis baru di portal dan unggah build aplikasi Anda.
  6. Setelah pengunggahan selesai, klik Berikutnya dan pilih Grup distribusi yang Anda buat sebagai Tujuan distribusi aplikasi tersebut.
  7. Tinjau Distribusi dan distribusikan build ke grup pengujian dalam aplikasi Anda.
  8. Orang dalam grup tersebut akan menerima undangan untuk menjadi penguji aplikasi. Setelah menerima undangan, mereka dapat mengunduh aplikasi dari Portal App Center dari perangkat seluler mereka. Setelah menginstal pembaruan dalam aplikasi, Anda siap untuk menguji pembaruan dalam aplikasi.
  9. Menabrak versi aplikasi Anda (CFBundleShortVersionString atau CFBundleVersion untuk iOS, versionCode untuk Android)
  10. Buat versi rilis aplikasi Anda dan unggah build baru aplikasi seperti yang Anda lakukan di langkah sebelumnya dan distribusikan ini ke Grup Distribusi yang Anda buat sebelumnya. Anggota Grup Distribusi akan dimintai versi baru saat aplikasi dimulai lagi.

Tip

Lihat informasi tentang cara menggunakan App Center Distribute untuk informasi lebih rinci tentang Grup Distribusi , dll. Meskipun dimungkinkan untuk menggunakan App Center Distribute untuk mendistribusikan versi baru aplikasi Anda tanpa menambahkan kode apa pun, menambahkan App Center Distribute ke kode aplikasi Anda akan menghasilkan pengalaman yang lebih mulus bagi penguji dan pengguna saat mereka mendapatkan pengalaman pembaruan dalam aplikasi.

Menonaktifkan penerusan otomatis metode delegasi aplikasi ke layanan App Center

App Center menggunakan swizzling untuk meneruskan metode delegasi aplikasi Anda secara otomatis ke layanan App Center untuk meningkatkan integrasi SDK. Ada kemungkinan konflik dengan pustaka pihak ketiga lainnya atau delegasi aplikasi itu sendiri. Dalam hal ini, Anda mungkin ingin menonaktifkan penerusan delegasi aplikasi App Center untuk semua layanan App Center dengan mengikuti langkah-langkah di bawah ini:

  1. Buka file Info.plist proyek.
  2. Tambahkan AppCenterAppDelegateForwarderEnabled kunci dan atur nilainya ke 0. Ini menonaktifkan penerusan delegasi aplikasi untuk semua layanan App Center.
  3. Tambahkan OpenUrl panggilan balik di file Anda AppDelegate.cs .
public override bool OpenUrl(UIApplication application, NSUrl url, string sourceApplication, NSObject annotation)
{
    Distribute.OpenUrl(url);
    return true;
}