Menyiapkan konfigurasi terkelola

Jika mengembangkan aplikasi untuk pasar perusahaan, Anda mungkin perlu untuk memenuhi persyaratan tertentu yang ditetapkan oleh kebijakan organisasi. Konfigurasi terkelola, yang sebelumnya dikenal sebagai pembatasan aplikasi, mengizinkan admin IT organisasi untuk menentukan setelan dari jarak jauh aplikasi. Kemampuan ini sangat berguna untuk organisasi yang aplikasi yang di-deploy ke profil kerja.

Misalnya, organisasi mungkin mengharuskan aplikasi yang disetujui mengizinkan admin IT untuk:

• Mengizinkan atau memblokir URL untuk browser web
• Konfigurasi apakah aplikasi diizinkan untuk menyinkronkan konten melalui seluler, atau hanya dengan Wi-Fi
• Mengonfigurasi setelan email aplikasi

Panduan ini menunjukkan cara menerapkan setelan konfigurasi terkelola di aplikasi Anda. Untuk melihat aplikasi contoh dengan konfigurasi terkelola, lihat ManagedConfigurations. Jika Anda adalah developer pengelolaan mobilitas perusahaan (EMM), lihat panduan Android Management API.

Catatan: Karena alasan historis, setelan konfigurasi ini dikenal sebagai batasan,dan diterapkan dengan file serta class yang menggunakan (misalnya RestrictionsManager). Namun, sebenarnya dapat menerapkan berbagai opsi konfigurasi, tidak hanya batasan pada fungsi aplikasi.

Ringkasan konfigurasi jarak jauh

Aplikasi menentukan opsi konfigurasi terkelola yang dapat dilakukan dari jarak jauh yang ditetapkan oleh admin IT. Ini adalah pengaturan arbitrer yang dapat diubah oleh penyedia konfigurasi terkelola. Jika aplikasi Anda berjalan di profil kerja, admin IT dapat mengubah konfigurasi aplikasi yang dikelola.

Penyedia konfigurasi terkelola adalah aplikasi lain yang berjalan di perangkat yang sama. Aplikasi ini biasanya dikontrol oleh admin IT. Tujuan Admin IT memberitahukan perubahan konfigurasi ke bagian aplikasi penyedia konfigurasi Anda. Aplikasi tersebut, pada akhirnya, mengubah konfigurasi di aplikasi Anda.

Untuk memberikan konfigurasi yang dikelola secara eksternal:

• Deklarasikan konfigurasi terkelola dalam manifes aplikasi Anda. Melakukan sehingga admin IT dapat membaca konfigurasi kustom melalui API Google Play.
• Setiap kali aplikasi dilanjutkan, gunakan objek RestrictionsManager untuk memeriksa nilai saat ini terkelola, dan mengubah UI serta perilaku aplikasi Anda untuk sesuai dengan konfigurasi tersebut.
• Dengarkan ACTION_APPLICATION_RESTRICTIONS_CHANGED. Saat Anda menerima email ini siarkan, periksa RestrictionsManager untuk melihat konfigurasi terkelola saat ini, dan membuat perubahan yang diperlukan pada perilaku aplikasi Anda.

Menentukan konfigurasi terkelola

Aplikasi Anda dapat mendukung konfigurasi terkelola yang ingin Anda tentukan. Anda mendeklarasikan konfigurasi terkelola aplikasi dalam file konfigurasi terkelola, dan mendeklarasikan file konfigurasi dalam manifes. Membuat file konfigurasi memungkinkan aplikasi lain untuk memeriksa konfigurasi terkelola yang disediakan aplikasi Anda. Partner EMM dapat membaca konfigurasi aplikasi Anda dengan menggunakan API Google Play.

Untuk menentukan opsi konfigurasi jarak jauh aplikasi Anda, tempatkan elemen berikut dalam manifes Anda Elemen <application>:

<meta-data android:name="android.content.APP_RESTRICTIONS"
    android:resource="@xml/app_restrictions" />

Buat file bernama app_restrictions.xml di file aplikasi Direktori res/xml. Struktur file itu dijelaskan dalam referensi untuk RestrictionsManager. File tersebut memiliki elemen <restrictions> tingkat atas tunggal, yang berisi satu elemen turunan <restriction> untuk setiap konfigurasi yang dimiliki aplikasi.

Catatan: Jangan buat versi yang dilokalkan dari file konfigurasi terkelola. Aplikasi Anda hanya diizinkan memiliki satu file konfigurasi terkelola, jadi konfigurasi akan konsisten untuk aplikasi Anda di semua lokalitas.

Dalam lingkungan perusahaan, EMM biasanya akan menggunakan perangkat skema konfigurasi untuk menghasilkan konsol jarak jauh bagi tim IT admin, sehingga admin dapat mengonfigurasi konfigurasi aplikasi.

Penyedia konfigurasi terkelola dapat mengkueri aplikasi untuk menemukan detail pada konfigurasi aplikasi yang tersedia, termasuk deskripsinya teks. Penyedia konfigurasi dan admin IT dapat mengubah nama mengelola konfigurasi kapan saja, bahkan saat aplikasi sedang tidak berjalan.

Misalnya, aplikasi Anda dapat dikonfigurasi dari jarak jauh untuk mengizinkan atau melarang untuk mengunduh data melalui koneksi seluler. Aplikasi Anda bisa memiliki <restriction> seperti ini:

<?xml version="1.0" encoding="utf-8"?>
<restrictions xmlns:android="http://schemas.android.com/apk/res/android">

  <restriction
    android:key="downloadOnCellular"
    android:title="@string/download_on_cell_title"
    android:restrictionType="bool"
    android:description="@string/download_on_cell_description"
    android:defaultValue="true" />

</restrictions>

Anda menggunakan atribut android:key dari setiap konfigurasi untuk membaca nilainya dari paket konfigurasi terkelola. Karena alasan ini, setiap konfigurasi harus memiliki string kunci unik, dan string tidak dapat dilokalkan. Nilai ini harus ditentukan dengan literal string.

Catatan: Di aplikasi produksi, android:title dan android:description harus digambar dari resource yang dilokalkan seperti yang dijelaskan dalam Melokalkan dengan Referensi.

Aplikasi menentukan batasan menggunakan paket dalam bundle_array. Misalnya, aplikasi dengan beberapa opsi koneksi VPN dapat mendefinisikan setiap server VPN di bundle, dengan beberapa paket yang dikelompokkan bersama dalam array paket:

<?xml version="1.0" encoding="utf-8"?>
<restrictions xmlns:android="http://schemas.android.com/apk/res/android" >

  <restriction
    android:key="vpn_configuration_list"
    android:restrictionType="bundle_array">
    <restriction
      android:key="vpn_configuration"
      android:restrictionType="bundle">
      <restriction
        android:key="vpn_server"
        android:restrictionType="string"/>
      <restriction
        android:key="vpn_username"
        android:restrictionType="string"/>
      <restriction
        android:key="vpn_password"
        android:restrictionType="string"/>
    </restriction>
  </restriction>

</restrictions>

Jenis yang didukung untuk elemen android:restrictionType tercantum dalam Tabel 1 dan didokumentasikan di referensi untuk RestrictionsManager dan RestrictionEntry.

Tabel 1. Jenis dan penggunaan entri pembatasan.

Catatan: android:entryValues dapat dibaca oleh mesin dan tidak dapat dilokalkan. Gunakan android:entries untuk menampilkan nilai yang dapat dibaca manusia dan dapat dilokalkan. Setiap entri harus memiliki indeks yang sesuai di android:entryValues.

Memeriksa konfigurasi terkelola

Aplikasi Anda tidak otomatis diberi tahu saat aplikasi lain mengubahnya pengaturan konfigurasi. Sebagai gantinya, Anda perlu memeriksa adalah saat aplikasi dimulai atau dilanjutkan, dan memproses sebuah intent sistem untuk mengetahui apakah konfigurasi berubah saat aplikasi berjalan.

Untuk mengetahui pengaturan konfigurasi saat ini, aplikasi Anda menggunakan sebuah Objek RestrictionsManager. Aplikasi Anda harus periksa konfigurasi terkelola saat ini pada waktu-waktu berikut:

• Saat aplikasi dimulai atau dilanjutkan, dalam onResume() metode
• Saat aplikasi diberi tahu tentang perubahan konfigurasi, seperti yang dijelaskan dalam Memproses Konfigurasi Terkelola Perubahan

Untuk mendapatkan objek RestrictionsManager, dapatkan objek saat ini aktivitas dengan getActivity(), lalu panggil metode Activity.getSystemService() aktivitas tersebut:

var myRestrictionsMgr =
        activity?.getSystemService(Context.RESTRICTIONS_SERVICE) as RestrictionsManager

RestrictionsManager myRestrictionsMgr =
    (RestrictionsManager) getActivity()
        .getSystemService(Context.RESTRICTIONS_SERVICE);

Setelah memiliki RestrictionsManager, Anda bisa mendapatkan pengaturan konfigurasi saat ini dengan memanggil atribut Metode getApplicationRestrictions():

var appRestrictions: Bundle = myRestrictionsMgr.applicationRestrictions

Bundle appRestrictions = myRestrictionsMgr.getApplicationRestrictions();

Catatan: Untuk memudahkan, Anda juga dapat mengambil data saat ini dengan UserManager, dengan memanggil UserManager.getApplicationRestrictions(). Metode ini berperilaku sama sama seperti RestrictionsManager.getApplicationRestrictions().

Metode getApplicationRestrictions() memerlukan pembacaan dari penyimpanan data, jadi itu harus dilakukan dengan hemat. Jangan memanggil metode ini setiap kali Anda perlu mengetahui konfigurasi saat ini. Sebagai gantinya, Anda harus memanggilnya sekali ketika aplikasi dimulai atau dilanjutkan, dan menyimpan paket konfigurasi terkelola yang diambil ke cache. Lalu dengarkan untuk intent ACTION_APPLICATION_RESTRICTIONS_CHANGED guna mengetahui apakah konfigurasi berubah saat aplikasi Anda aktif, seperti yang dijelaskan di Memproses Perubahan Konfigurasi Terkelola.

Membaca dan menerapkan konfigurasi terkelola

Metode getApplicationRestrictions() akan menampilkan Bundle yang berisi pasangan nilai kunci untuk setiap konfigurasi yang telah ditetapkan. Tujuan nilai adalah semua jenis Boolean, int, String, dan String[]. Setelah Anda memiliki konfigurasi terkelola Bundle, Anda dapat memeriksa setelan konfigurasi dengan metode Bundle standar untuk jenis data tersebut, misalnya getBoolean() atau getString().

Catatan: Konfigurasi terkelola Bundle berisi satu item untuk setiap konfigurasi yang telah disetel secara eksplisit oleh penyedia konfigurasi terkelola. Namun, Anda tidak boleh berasumsi bahwa akan ada dalam paket hanya karena Anda menentukan konfigurasi dalam file XML konfigurasi terkelola.

Aplikasi Anda dapat mengambil tindakan yang sesuai berdasarkan setelan konfigurasi terkelola. Misalnya, jika aplikasi Anda memiliki yang menentukan apakah ia dapat mengunduh data melalui koneksi seluler, dan Anda menemukan bahwa konfigurasi sudah diatur ke false, Anda harus menonaktifkan download data kecuali jika perangkat memiliki koneksi Wi-Fi, seperti yang ditunjukkan pada kode contoh berikut:

val appCanUseCellular: Boolean =
        if (appRestrictions.containsKey("downloadOnCellular")) {
            appRestrictions.getBoolean("downloadOnCellular")
        } else {
            // cellularDefault is a boolean using the restriction's default value
            cellularDefault
        }

if (!appCanUseCellular) {
    // ...turn off app's cellular-download functionality
    // ...show appropriate notices to user
}

boolean appCanUseCellular;

if (appRestrictions.containsKey("downloadOnCellular")) {
    appCanUseCellular = appRestrictions.getBoolean("downloadOnCellular");
} else {
    // cellularDefault is a boolean using the restriction's default value
    appCanUseCellular = cellularDefault;
}

if (!appCanUseCellular) {
    // ...turn off app's cellular-download functionality
    // ...show appropriate notices to user
}

Untuk menerapkan beberapa pembatasan bertingkat, baca bundle_array entri pembatasan sebagai kumpulan objek Parcelable dan melakukan transmisi sebagai Bundle. Dalam contoh ini, setiap konfigurasi VPN data akan diuraikan dan digunakan untuk membuat daftar pilihan koneksi server:

// VpnConfig is a sample class used store config data, not defined
val vpnConfigs = mutableListOf<VpnConfig>()

val parcelables: Array<out Parcelable>? =
        appRestrictions.getParcelableArray("vpn_configuration_list")

if (parcelables?.isNotEmpty() == true) {
    // iterate parcelables and cast as bundle
    parcelables.map { it as Bundle }.forEach { vpnConfigBundle ->
        // parse bundle data and store in VpnConfig array
        vpnConfigs.add(VpnConfig()
                .setServer(vpnConfigBundle.getString("vpn_server"))
                .setUsername(vpnConfigBundle.getString("vpn_username"))
                .setPassword(vpnConfigBundle.getString("vpn_password")))
    }
}

if (vpnConfigs.isNotEmpty()) {
    // ...choose a VPN configuration or prompt user to select from list
}

// VpnConfig is a sample class used store config data, not defined
List<VpnConfig> vpnConfigs = new ArrayList<>();

Parcelable[] parcelables =
    appRestrictions.getParcelableArray("vpn_configuration_list");

if (parcelables != null && parcelables.length > 0) {
    // iterate parcelables and cast as bundle
    for (int i = 0; i < parcelables.length; i++) {
        Bundle vpnConfigBundle = (Bundle) parcelables[i];
        // parse bundle data and store in VpnConfig array
        vpnConfigs.add(new VpnConfig()
            .setServer(vpnConfigBundle.getString("vpn_server"))
            .setUsername(vpnConfigBundle.getString("vpn_username"))
            .setPassword(vpnConfigBundle.getString("vpn_password")));
    }
}

if (!vpnConfigs.isEmpty()) {
    // ...choose a VPN configuration or prompt user to select from list
}

Memproses perubahan konfigurasi terkelola

Setiap kali konfigurasi terkelola aplikasi berubah, sistem akan mengaktifkan ACTION_APPLICATION_RESTRICTIONS_CHANGED. Aplikasi Anda harus mendengarkan intent ini sehingga Anda dapat mengubah perilaku aplikasi saat setelan konfigurasi berubah.

Catatan: Intent ACTION_APPLICATION_RESTRICTIONS_CHANGED hanya dikirim ke pemroses yang terdaftar secara dinamis, bukan untuk pemroses yang dideklarasikan dalam manifes aplikasi.

Kode berikut menunjukkan cara mendaftarkan penerima siaran secara dinamis untuk intent ini:

val restrictionsFilter = IntentFilter(Intent.ACTION_APPLICATION_RESTRICTIONS_CHANGED)

val restrictionsReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {

        // Get the current configuration bundle
        val appRestrictions = myRestrictionsMgr.applicationRestrictions

        // Check current configuration settings, change your app's UI and
        // functionality as necessary.
    }
}

registerReceiver(restrictionsReceiver, restrictionsFilter)

IntentFilter restrictionsFilter =
    new IntentFilter(Intent.ACTION_APPLICATION_RESTRICTIONS_CHANGED);

BroadcastReceiver restrictionsReceiver = new BroadcastReceiver() {
  @Override public void onReceive(Context context, Intent intent) {

    // Get the current configuration bundle
    Bundle appRestrictions = myRestrictionsMgr.getApplicationRestrictions();

    // Check current configuration settings, change your app's UI and
    // functionality as necessary.
  }
};

registerReceiver(restrictionsReceiver, restrictionsFilter);

Catatan: Biasanya, aplikasi Anda tidak perlu mendapatkan notifikasi tentang perubahan konfigurasi saat dijeda. Sebaliknya, Anda harus membatalkan pendaftaran penerima siaran Anda saat aplikasi dijeda. Ketika aplikasi dilanjutkan, Anda pemeriksaan pertama untuk konfigurasi terkelola saat ini (seperti yang dibahas di Periksa Konfigurasi Terkelola), lalu daftar penerima siaran Anda untuk memastikan Anda diberi tahu tentang perubahan konfigurasi yang terjadi selama aplikasi aktif.

Mengirim masukan konfigurasi terkelola ke EMM

Setelah menerapkan perubahan konfigurasi terkelola ke aplikasi, sebaiknya beri tahu EMM tentang status perubahan. Android mendukung fitur yang disebut status aplikasi berupa tombol, yang dapat Anda untuk mengirim masukan setiap kali aplikasi mencoba menerapkan perubahan konfigurasi terkelola. Ini masukan dapat bertindak sebagai konfirmasi bahwa aplikasi Anda berhasil menetapkan konfigurasi terkelola atau dapat menyertakan pesan error jika aplikasi Anda gagal menerapkan perubahan yang ditentukan.

Penyedia EMM dapat mengambil masukan ini dan menampilkannya di konsol mereka untuk tim IT admin untuk melihatnya. Lihat Mengirim masukan aplikasi ke EMM untuk mengetahui informasi selengkapnya informasi tentang topik, termasuk panduan mendetail tentang cara menambahkan dukungan masukan ke aplikasi Anda.

Contoh kode lainnya

ManagedConfigurations contoh lebih lanjut menunjukkan penggunaan API yang tercakup dalam halaman ini.