Verwaltete Konfigurationen einrichten

Wenn Sie Apps für den Unternehmensmarkt entwickeln, müssen Sie möglicherweise bestimmte Anforderungen erfüllen, die in den Richtlinien einer Organisation festgelegt sind. Mit verwalteten Konfigurationen, die früher als Anwendungseinschränkungen bezeichnet wurden, können IT-Administratoren der Organisation Einstellungen für Apps per Remotezugriff festlegen. Diese Funktion ist besonders nützlich für von der Organisation genehmigte Apps, die in einem Arbeitsprofil bereitgestellt werden.

Eine Organisation kann beispielsweise verlangen, dass genehmigte Apps dem IT-Administrator Folgendes ermöglichen:

  • URLs für einen Webbrowser zulassen oder blockieren
  • Konfigurieren, ob eine App Inhalte über das Mobilfunknetz oder nur über WLAN synchronisieren darf
  • E-Mail-Einstellungen der App konfigurieren

In dieser Anleitung erfahren Sie, wie Sie Einstellungen für verwaltete Konfigurationen in Ihrer App implementieren. Beispiel-Apps mit einer verwalteten Konfiguration finden Sie unter ManagedConfigurations. Wenn Sie ein EMM-Entwickler (Enterprise Mobility Management) sind, lesen Sie den Leitfaden zur Android Management API.

Hinweis:Aus historischen Gründen werden diese Konfigurationseinstellungen als Einschränkungen bezeichnet und mit Dateien und Klassen implementiert, in denen dieser Begriff verwendet wird (z. B. RestrictionsManager). Mit diesen Einschränkungen können jedoch nicht nur Einschränkungen der App-Funktionen, sondern eine Vielzahl von Konfigurationsoptionen implementiert werden.

Fernkonfiguration – Übersicht

In Apps werden die Optionen für verwaltete Konfigurationen definiert, die von einem IT-Administrator per Remotezugriff festgelegt werden können. Dies sind beliebige Einstellungen, die von einem Anbieter für verwaltete Konfigurationen geändert werden können. Wenn Ihre App in einem Arbeitsprofil ausgeführt wird, kann der IT-Administrator die verwaltete Konfiguration Ihrer App ändern.

Der Anbieter der verwalteten Konfigurationen ist eine andere App, die auf demselben Gerät ausgeführt wird. Diese App wird in der Regel vom IT-Administrator gesteuert. Der IT-Administrator sendet Konfigurationsänderungen an die App des verwalteten Konfigurationsanbieters. Diese App ändert dann die Konfigurationen in Ihrer App.

So geben Sie extern verwaltete Konfigurationen an:

  • Deklarieren Sie die verwalteten Konfigurationen in Ihrem App-Manifest. So kann der IT-Administrator die Konfigurationen der App über Google Play APIs lesen.
  • Wenn die App fortgesetzt wird, prüfen Sie mit dem RestrictionsManager-Objekt die aktuellen verwalteten Konfigurationen und ändern Sie die Benutzeroberfläche und das Verhalten Ihrer App so, dass sie diesen Konfigurationen entsprechen.
  • Achte auf den Intent ACTION_APPLICATION_RESTRICTIONS_CHANGED. Wenn Sie diese Mitteilung erhalten, sehen Sie unter RestrictionsManager nach, welche verwalteten Konfigurationen derzeit aktiv sind, und nehmen Sie gegebenenfalls die erforderlichen Änderungen am Verhalten Ihrer App vor.

Verwaltete Konfigurationen definieren

Ihre App kann jede verwaltete Konfiguration unterstützen, die Sie definieren möchten. Die verwalteten Konfigurationen der App werden in einer verwalteten Konfigurationsdatei und die Konfigurationsdatei im Manifest deklariert. Wenn Sie eine Konfigurationsdatei erstellen, können andere Apps die von Ihrer App bereitgestellten verwalteten Konfigurationen prüfen. EMM-Partner können die Konfigurationen Ihrer App mithilfe von Google Play APIs lesen.

Wenn Sie die Remote-Konfigurationsoptionen Ihrer App definieren möchten, fügen Sie das folgende Element in das <application>-Element Ihres Manifests ein: 

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

Erstellen Sie im Verzeichnis res/xml Ihrer App eine Datei mit dem Namen app_restrictions.xml. Die Struktur dieser Datei wird in der Referenz für RestrictionsManager beschrieben. Die Datei enthält ein einzelnes <restrictions>-Element auf oberster Ebene, das für jede Konfigurationsoption der App ein untergeordnetes <restriction>-Element enthält.

Hinweis:Erstellen Sie keine lokalisierten Versionen der verwalteten Konfigurationsdatei. Ihre App darf nur eine einzige verwaltete Konfigurationsdatei haben, damit die Konfigurationen für Ihre App in allen Sprachen einheitlich sind.

In einer Unternehmensumgebung verwendet ein EMM in der Regel das Schema für verwaltete Konfigurationen, um eine Remote-Konsole für IT-Administratoren zu generieren, damit diese die Anwendung aus der Ferne konfigurieren können.

Der Anbieter der verwalteten Konfiguration kann die App abfragen, um Details zu den verfügbaren Konfigurationen der App zu erhalten, einschließlich der Beschreibungstexte. Der Konfigurationsanbieter und der IT-Administrator können die verwalteten Konfigurationen Ihrer App jederzeit ändern, auch wenn die App nicht ausgeführt wird.

Angenommen, Ihre App kann aus der Ferne so konfiguriert werden, dass der Download von Daten über eine Mobilfunkverbindung erlaubt oder verboten wird. Ihre App könnte ein <restriction>-Element wie dieses haben: 

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

Mit dem android:key-Attribut der einzelnen Konfigurationen können Sie den Wert aus einem verwalteten Konfigurationsbundle lesen. Aus diesem Grund muss jede Konfiguration einen eindeutigen Schlüsselstring haben und der String darf nicht lokalisiert werden. Sie muss mit einem Stringliteral angegeben werden.

Hinweis:In einer Produktions-App sollten android:title und android:description aus einer lokalisierten Ressourcendatei stammen, wie unter Mit Ressourcen lokalisieren beschrieben.

Eine App definiert Einschränkungen mithilfe von Bundles in einem bundle_array. In einer App mit mehreren VPN-Verbindungsoptionen könnte beispielsweise jede VPN-Serverkonfiguration in einer bundle definiert werden, wobei mehrere Bundles in einem Bundle-Array gruppiert werden: 

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

Die unterstützten Typen für das android:restrictionType-Element sind in Tabelle 1 aufgeführt und in der Referenz für RestrictionsManager und RestrictionEntry dokumentiert.

Tabelle 1 Eintragstypen und Verwendung von Einschränkungen

Eingeben android:restrictionType Typische Verwendung
TYPE_BOOLEAN "bool" Ein boolescher Wert, „wahr“ oder „falsch“.
TYPE_STRING "string" Ein Stringwert, z. B. ein Name.
TYPE_INTEGER "integer" Eine Ganzzahl zwischen MIN_VALUE und MAX_VALUE.
TYPE_CHOICE "choice" Ein Stringwert, der aus android:entryValues ausgewählt wurde, wird in der Regel als Liste mit Einzelauswahl dargestellt.
TYPE_MULTI_SELECT "multi-select" Ein String-Array mit Werten, die aus android:entryValues ausgewählt wurden. Verwende diese Option, um eine Mehrfachauswahlliste anzuzeigen, in der mehrere Einträge ausgewählt werden können, z. B. um bestimmte Titel auf die Zulassungsliste zu setzen.
TYPE_NULL "hidden" Ausgeblendeter Einschränkungstyp. Verwenden Sie diesen Typ für Informationen, die übertragen werden müssen, aber nicht in der Benutzeroberfläche angezeigt werden sollen. Hier wird ein einzelner Stringwert gespeichert.
TYPE_BUNDLE_ARRAY "bundle_array" Verwenden Sie diese Funktion, um Arrays von Einschränkungen zu speichernbundles. Verfügbar in Android 6.0 (API-Level 23).

Hinweis:android:entryValues sind maschinenlesbar und können nicht lokalisiert werden. Verwenden Sie android:entries, um visuell lesbare Werte anzugeben, die lokalisiert werden können. Jeder Eintrag muss einem Index in android:entryValues entsprechen.

Verwaltete Konfigurationen prüfen

Ihre App wird nicht automatisch benachrichtigt, wenn andere Apps ihre Konfigurationseinstellungen ändern. Stattdessen müssen Sie prüfen, welche verwalteten Konfigurationen beim Starten oder Fortsetzen Ihrer App gelten, und auf eine Systemabsicht warten, um herauszufinden, ob sich die Konfigurationen ändern, während Ihre App ausgeführt wird.

Ihre App verwendet ein RestrictionsManager-Objekt, um die aktuellen Konfigurationseinstellungen abzurufen. Ihre App sollte zu den folgenden Zeiten nach den aktuellen verwalteten Konfigurationen suchen:

Wenn Sie ein RestrictionsManager-Objekt abrufen möchten, rufen Sie die aktuelle Aktivität mit getActivity() ab und rufen Sie dann die Activity.getSystemService()-Methode dieser Aktivität auf:

Kotlin

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

Java

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

Sobald du eine RestrictionsManager hast, kannst du die aktuellen Konfigurationseinstellungen abrufen, indem du die Methode getApplicationRestrictions() aufrufst:

Kotlin

var appRestrictions: Bundle = myRestrictionsMgr.applicationRestrictions

Java

Bundle appRestrictions = myRestrictionsMgr.getApplicationRestrictions();

Hinweis:Sie können die aktuellen Konfigurationen auch mit einer UserManager abrufen, indem Sie UserManager.getApplicationRestrictions() aufrufen. Diese Methode verhält sich genau wie RestrictionsManager.getApplicationRestrictions().

Die getApplicationRestrictions()-Methode erfordert das Lesen aus dem Datenspeicher und sollte daher sparsam eingesetzt werden. Sie müssen diese Methode nicht jedes Mal aufrufen, wenn Sie die aktuelle Konfiguration benötigen. Stattdessen sollten Sie die Funktion einmal beim Starten oder Fortsetzen Ihrer App aufrufen und das abgerufene Bundle mit den verwalteten Konfigurationen im Cache speichern. Hören Sie dann auf die ACTION_APPLICATION_RESTRICTIONS_CHANGED-Intent, um herauszufinden, ob sich die Konfiguration ändert, während Ihre App aktiv ist, wie unter Auf Änderungen an verwalteten Konfigurationen achten beschrieben.

Verwaltete Konfigurationen lesen und anwenden

Die Methode getApplicationRestrictions() gibt eine Bundle zurück, die für jede festgelegte Konfiguration ein Schlüssel/Wert-Paar enthält. Die Werte sind alle vom Typ Boolean, int, String und String[]. Sobald Sie die verwalteten Konfigurationen Bundle haben, können Sie die aktuellen Konfigurationseinstellungen mit den Standardmethoden Bundle für diese Datentypen prüfen, z. B. getBoolean() oder getString().

Hinweis: „Verwaltete Konfigurationen“ Bundle enthält ein Element für jede Konfiguration, die explizit von einem Anbieter verwalteter Konfigurationen festgelegt wurde. Sie können jedoch nicht davon ausgehen, dass eine Konfiguration im Bundle vorhanden ist, nur weil Sie in der XML-Datei für verwaltete Konfigurationen einen Standardwert definiert haben.

Es liegt in der Verantwortung Ihrer App, auf Grundlage der aktuellen Einstellungen der verwalteten Konfiguration entsprechende Maßnahmen zu ergreifen. Wenn Ihre App beispielsweise eine Konfiguration hat, die angibt, ob Daten über eine Mobilfunkverbindung heruntergeladen werden können, und Sie feststellen, dass die Konfiguration auf false festgelegt ist, müssen Sie den Datendownload deaktivieren, es sei denn, das Gerät hat eine WLAN-Verbindung, wie im folgenden Beispielcode gezeigt:

Kotlin

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
}

Java

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
}

Wenn Sie mehrere verschachtelte Einschränkungen anwenden möchten, lesen Sie den Eintrag für die bundle_array-Einschränkung als Sammlung von Parcelable-Objekten und wandeln Sie ihn in eine Bundle um. In diesem Beispiel werden die Konfigurationsdaten jedes VPN analysiert und verwendet, um eine Liste der Serververbindungsoptionen zu erstellen:

Kotlin

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

Java

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

Auf Änderungen an verwalteten Konfigurationen achten

Jedes Mal, wenn die verwalteten Konfigurationen einer App geändert werden, löst das System die ACTION_APPLICATION_RESTRICTIONS_CHANGED-Intent aus. Ihre App muss auf diesen Intent achten, damit Sie das Verhalten der App ändern können, wenn sich die Konfigurationseinstellungen ändern.

Hinweis:Die ACTION_APPLICATION_RESTRICTIONS_CHANGED-Intent wird nur an dynamisch registrierte Listener gesendet, nicht an Listener, die im App-Manifest deklariert sind.

Im folgenden Code wird gezeigt, wie ein Broadcast-Empfänger dynamisch für diese Absicht registriert wird:

Kotlin

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)

Java

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

Hinweis:Normalerweise muss Ihre App nicht über Konfigurationsänderungen benachrichtigt werden, wenn sie pausiert ist. Stattdessen sollten Sie Ihren Broadcast-Empfänger unregistern, wenn die App pausiert ist. Wenn die App fortgesetzt wird, prüfen Sie zuerst die aktuellen verwalteten Konfigurationen (wie unter Verwaltete Konfigurationen prüfen beschrieben) und registrieren Sie dann Ihren Broadcast-Empfänger, damit Sie über Konfigurationsänderungen informiert werden, die auftreten, während die App aktiv ist.

Feedback zu verwalteten Konfigurationen an EMMs senden

Nachdem Sie Änderungen an der verwalteten Konfiguration auf Ihre App angewendet haben, sollten Sie EMMs über den Status der Änderung informieren. Android unterstützt die Funktion App-Status mit Schlüssel. Damit können Sie jedes Mal Feedback senden, wenn Ihre App versucht, Änderungen an der verwalteten Konfiguration anzuwenden. Dieses Feedback kann als Bestätigung dienen, dass Ihre App verwaltete Konfigurationen erfolgreich festgelegt hat. Es kann auch eine Fehlermeldung enthalten, wenn die angegebenen Änderungen nicht angewendet werden konnten.

EMM-Anbieter können dieses Feedback abrufen und in ihren Konsolen für IT-Administratoren anzeigen. Weitere Informationen zu diesem Thema, einschließlich einer detaillierten Anleitung zum Hinzufügen von Feedbackfunktionen zu Ihrer App, finden Sie unter App-Feedback an EMMs senden.

Weitere Codebeispiele

Im Beispiel ManagedConfigurations wird die Verwendung der auf dieser Seite beschriebenen APIs veranschaulicht.

Apps im privaten Profil auf die Zulassungs- oder Sperrliste setzen

App-Shops von Drittanbietern können sich für die Verwendung verwalteter Konfigurationen interessieren, um eine App-Sperre oder -Zulassungsliste sowohl auf das private Profil als auch auf die Verbraucherfunktion Vertraulicher Bereich anzuwenden. Letzterer ist ein zusätzlicher privater Bereich, in dem Nutzer ihre sensiblen Apps aufbewahren können. Wenn Sie einen App-Shop für die Unternehmensnutzung entwickeln und diese Funktion verwenden möchten, füllen Sie dieses Formular aus und wählen Sie im Formular als Begründung die Option Interesse an der Zulassungsliste für Drittanbieter-App-Shops aus.