Impostare le configurazioni gestite

Se stai sviluppando app per il mercato aziendale, potresti aver bisogno di in modo da soddisfare particolari requisiti stabiliti dai criteri di un'organizzazione. Configurazioni gestite, precedentemente note come restrizioni delle applicazioni, consentire all'amministratore IT dell'organizzazione di specificare da remoto le impostazioni per app. Questa funzionalità è particolarmente utile per i modelli di cui è stato eseguito il deployment in un profilo di lavoro.

Ad esempio, un'organizzazione potrebbe richiedere che le app approvate consentano Amministratore IT per:

• Consentire o bloccare gli URL per un browser web
• Specifica se un'app può sincronizzare i contenuti tramite cellulare o solo tramite Wi-Fi
• Configurare le impostazioni email dell'app

Questa guida illustra come implementare le impostazioni di configurazione gestita in la tua app. Per visualizzare app di esempio con una configurazione gestita, consulta ManagedConfigurations. Se sei uno sviluppatore di gestione della mobilità aziendale (EMM), consulta la guida all'API Android Management.

Nota: per motivi storici, queste impostazioni di configurazione sono note come limitazioni e sono implementate con file e classi che utilizzano questo (ad esempio RestrictionsManager). Tuttavia, questi restrizioni possono implementare una vasta gamma di opzioni di configurazione, non solo limitazioni sulla funzionalità dell'app.

Panoramica della configurazione remota

Le app definiscono le opzioni di configurazione gestita che possono essere eseguite da remoto configurato da un amministratore IT. Si tratta di impostazioni arbitrarie che possono essere modificata da un fornitore di configurazione gestita. Se la tua app è in esecuzione in un profilo di lavoro, l'amministratore IT può cambiare la configurazione gestita dell'app.

Il fornitore di configurazioni gestite è un'altra app in esecuzione sullo stesso dispositivo. Questa app è generalmente controllata dall'amministratore IT. La L'amministratore IT comunica le modifiche alla configurazione del fornitore di servizi di configurazione. L'app, a sua volta, modifica le configurazioni.

Per fornire configurazioni gestite esternamente:

• Dichiara le configurazioni gestite nel file manifest dell'app. Attività consente all'amministratore IT di leggere i dati dell'app tramite le API di Google Play.
• Ogni volta che l'app riprende, usa l'oggetto RestrictionsManager per controllare lo stato attuale configurazioni gestite e modificare l'interfaccia utente e il comportamento dell'app in conformi a queste configurazioni.
• Tieni d'occhio l'evento Intenzione ACTION_APPLICATION_RESTRICTIONS_CHANGED. Quando ricevi questo trasmetti, controlla RestrictionsManager per vedere cosa le attuali configurazioni gestite e apporta le modifiche necessarie alle tue il comportamento dell'app.

Definisci le configurazioni gestite

La tua app può supportare qualsiasi configurazione gestita che vuoi definire. Dichiari le configurazioni gestite dell'app in un file di configurazioni gestite e dichiarare il file di configurazione nel manifest. La creazione di un file di configurazione ti consente altre app per esaminare le configurazioni gestite fornite dalla tua app. Partner EMM possono leggere le configurazioni dell'app utilizzando le API di Google Play.

Per definire le opzioni di configurazione remota dell'app, inserisci il seguente elemento nel file manifest Elemento <application>:

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

Crea un file denominato app_restrictions.xml nel Directory res/xml. La struttura di tale file è descritta in il riferimento per RestrictionsManager. Il file contiene singolo elemento <restrictions> di primo livello, che contiene un elemento secondario <restriction> per ogni configurazione l'opzione di cui dispone l'app.

Nota: non creare versioni localizzate del di configurazione gestita. La tua app può avere soltanto singolo file di configurazioni gestite, quindi le configurazioni saranno e lo stesso vale per la tua app in tutte le lingue.

In un ambiente aziendale, generalmente un EMM utilizza schema di configurazione per generare una console remota per l'IT , in modo che gli amministratori possano configurare da remoto un'applicazione.

Il fornitore della configurazione gestita può eseguire una query sull'app per trovare i dettagli sulle configurazioni disponibili dell'app, inclusa la relativa descrizione testo. Il fornitore di configurazioni e l'amministratore IT possono modificare configurazioni gestite in qualsiasi momento, anche quando l'app non è in esecuzione.

Ad esempio, supponiamo che la tua app possa essere configurata da remoto per consentire o vietare l'accesso per scaricare dati tramite una rete cellulare. La tua app potrebbe avere un <restriction> elemento come questo:

<?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>

Puoi utilizzare l'attributo android:key di ogni configurazione per leggere il valore da un bundle di configurazione gestita. Per questo motivo, ogni configurazione deve avere una stringa chiave univoca e la stringa non possono essere localizzati. Deve essere specificato con un valore letterale stringa.

Nota: in un'app di produzione, android:title e android:description deve essere estratto da una risorsa localizzata come descritto in Localizzazione con le risorse.

Un'app definisce le limitazioni utilizzando i bundle all'interno di un bundle_array. Ad esempio, un'app con più opzioni di connessione VPN può definire ciascun server VPN configurazione in un bundle, con più Gruppi raggruppati in un array di bundle:

<?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>

I tipi supportati per l'elemento android:restrictionType sono elencati nella Tabella 1 e documentati in il riferimento per RestrictionsManager e RestrictionEntry.

Tabella 1. Tipi di voci di limitazione e utilizzo.

Nota: i android:entryValues sono leggibili automaticamente e non possono essere localizzato. Utilizza android:entries per presentare valori leggibili che possono essere localizzati. Ogni voce deve avere un indice corrispondente in android:entryValues.

Controlla le configurazioni gestite

La tua app non riceve automaticamente notifiche quando altre app modificano il relativo le impostazioni di configurazione. È invece necessario verificare quale di configurazione sono l'avvio o il riavvio dell'app e resta in ascolto di un l'intento di sistema di capire se le configurazioni cambiano mentre sia in esecuzione.

Per conoscere le impostazioni di configurazione attuali, la tua app utilizza un RestrictionsManager oggetto. La tua app dovrebbe verifica le configurazioni gestite attuali nei seguenti orari:

• Quando l'app si avvia o riprende, nelle relative onResume() metodo
• Quando all'app viene inviata una notifica di modifica della configurazione, come descritto in Ascolta la configurazione gestita Modifiche

Per ottenere un oggetto RestrictionsManager, recupera lo stato attuale attività con getActivity(), poi chiama il metodo Activity.getSystemService() di quell'attività:

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

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

Una volta che hai un RestrictionsManager, puoi ottenere impostazioni di configurazione correnti richiamando il suo Metodo getApplicationRestrictions():

var appRestrictions: Bundle = myRestrictionsMgr.applicationRestrictions

Bundle appRestrictions = myRestrictionsMgr.getApplicationRestrictions();

Nota: per comodità, puoi anche recuperare i dati attuali configurazioni con un UserManager, chiamando UserManager.getApplicationRestrictions(). Questo metodo si comporta esattamente uguale a RestrictionsManager.getApplicationRestrictions().

Il metodo getApplicationRestrictions() richiede la lettura da spazio di archiviazione dati, quindi dovrebbe essere fatto con parsimonia. Non chiamare questo metodo ogni volta che devi la configurazione attuale. Devi chiamarla una volta quando l'app all'avvio o alla ripresa e nella cache del bundle di configurazioni gestite recuperato. Poi ascolta per l'intent ACTION_APPLICATION_RESTRICTIONS_CHANGED per scoprire se la configurazione modificare mentre l'app è attiva, come descritto nella Ascolta le modifiche alla configurazione gestita.

Lettura e applicazione delle configurazioni gestite

Il metodo getApplicationRestrictions() restituisce un Bundle contenente una coppia chiave-valore per ogni configurazione impostata. La sono tutti di tipo Boolean, int, String e String[]. Una volta che hai configurazioni gestite Bundle, puoi controllare lo stato attuale di configurazione con i metodi Bundle standard per questi tipi di dati, ad esempio getBoolean() o getString().

Nota: le configurazioni gestite Bundle contiene un elemento per ogni configurazione impostata esplicitamente da un del fornitore di configurazioni gestite. Tuttavia, non si può dare per scontato che una sarà presente nel bundle solo perché hai definito un valore predefinito nel file XML delle configurazioni gestite.

Spetta alla tua app intraprendere le azioni appropriate in base all'attuale impostazioni di configurazione gestita. Ad esempio, se la tua app include che specifica se può scaricare i dati su un rete mobile e scopri che la configurazione è impostata su false, dovrai disattivare il download dei dati, tranne quando il dispositivo disponga di una connessione Wi-Fi, come mostrato nel seguente codice di esempio:

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
}

Per applicare più restrizioni nidificate, leggi bundle_array voce della limitazione come raccolta di Parcelable oggetti e trasmetti come Bundle. In questo esempio, la configurazione di ogni VPN I dati vengono analizzati e utilizzati per creare un elenco di scelte per le connessioni al 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
}

Ascolta le modifiche alla configurazione gestita

Ogni volta che vengono modificate le configurazioni gestite di un'app, il sistema attiva Intenzione ACTION_APPLICATION_RESTRICTIONS_CHANGED. La tua app deve ascoltare questo intent per consentirti di modificare il comportamento dell'app quando le impostazioni di configurazione modifica.

Nota: l'intent ACTION_APPLICATION_RESTRICTIONS_CHANGED viene inviato solo agli ascoltatori registrati dinamicamente, non ai listener dichiarati nel file manifest dell'app.

Il seguente codice mostra come registrare dinamicamente un broadcast receiver per questo intent:

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

Nota: in genere non è necessario ricevere notifiche per la tua app sulle modifiche alla configurazione quando questo è in pausa. Dovresti invece annullare la registrazione il broadcast receiver quando l'app è in pausa. Quando l'app riprende, per prima cosa controllare le configurazioni gestite attuali (come discusso Controlla le configurazioni gestite), quindi registrati il tuo broadcast receiver per assicurarti di ricevere una notifica relativa alle modifiche alla configurazione che si verificano mentre l'app è attiva.

Invia feedback sulla configurazione gestita ai provider EMM

Dopo aver applicato le modifiche alla configurazione gestita alla tua app, ti consigliamo di informare gli EMM lo stato della modifica. Android supporta una funzionalità chiamata stati delle app con chiave, che puoi da utilizzare per inviare un feedback ogni volta che l'app tenta di applicare modifiche alla configurazione gestita. Questo un feedback può servire a confermare che la tua app ha impostato correttamente le configurazioni gestite oppure includi un messaggio di errore se l'applicazione delle modifiche specificate non è riuscita per l'app.

I provider EMM sono in grado di recuperare questo feedback e di mostrarlo nelle proprie console per l'IT amministratori. Per ulteriori informazioni, leggi l'articolo Inviare feedback sulle app ai provider EMM informazioni sull'argomento, inclusa una guida dettagliata su come aggiungere feedback alla tua app.

Altri esempi di codice

La colonna ManagedConfigurations l'esempio illustra ulteriormente l'uso delle API trattati in questa pagina.