Erweiterungs-Apps und lokale Befehle

Mit dem SDK für die Android Management API (AMAPI) kann eine von einem EMM-Anbieter angegebene Erweiterungs-App direkt mit Android Device Policy (ADP) kommunizieren und Commands auf dem Gerät ausführen.

AMAPI SDK einbinden enthält weitere Informationen zu dieser Bibliothek und dazu, wie Sie sie Ihrer Anwendung hinzufügen.

Nachdem Sie das SDK eingebunden haben, kann Ihre Erweiterungs-App mit ADP kommunizieren, um:

Befehlsanfragen senden
Status von Befehlsanfragen abfragen
Befehlsstatusänderungen empfangen

Befehl erteilen

Eine Erweiterungs-App kann anfordern, dass Befehle über ADP ausgegeben werden. IssueCommandRequest enthält das Anfrageobjekt mit Details zum auszuführenden Befehl und zu bestimmten Parametern.

Das folgende Snippet zeigt, wie eine Anfrage zum Löschen der Daten des Pakets gesendet wird:

import android.util.Log;
...
import com.google.android.managementapi.commands.LocalCommandClientFactory;
import com.google.android.managementapi.commands.model.Command;
import com.google.android.managementapi.commands.model.GetCommandRequest;
import com.google.android.managementapi.commands.model.IssueCommandRequest;
import com.google.android.managementapi.commands.model.IssueCommandRequest.ClearAppsData;
import com.google.common.collect.ImmutableList;
import com.google.common.util.concurrent.FutureCallback;
import com.google.common.util.concurrent.Futures;
import com.google.common.util.concurrent.MoreExecutors;

...
  void issueClearAppDataCommand(ImmutableList<String> packageNames) {
    Futures.addCallback(
        LocalCommandClientFactory.create(getContext())
            .issueCommand(createClearAppRequest(packageNames)),
        new FutureCallback<Command>() {
          @Override
          public void onSuccess(Command result) {
            // Process the returned command result here
            Log.i(TAG, "Successfully issued command");
          }

          @Override
          public void onFailure(Throwable t) {
            Log.e(TAG, "Failed to issue command", t);
          }
        },
        MoreExecutors.directExecutor());
  }

  IssueCommandRequest createClearAppRequest(ImmutableList<String> packageNames) {
    return IssueCommandRequest.builder()
        .setClearAppsData(
            ClearAppsData.builder()
                .setPackageNames(packageNames)
                .build()
        )
        .build();
  }
...

Im vorherigen Beispiel wird eine Anfrage zum Löschen von App-Daten für bestimmte Pakete gesendet und gewartet, bis der Befehl erfolgreich ausgeführt wurde. Wenn der Befehl erfolgreich ausgegeben wurde, wird ein Command-Objekt mit dem aktuellen Befehlsstatus und der Befehls-ID zurückgegeben. Die Befehls-ID kann später verwendet werden, um den Status von Befehlen mit langer Ausführungszeit abzufragen.

Befehl abrufen

Eine Erweiterungs-App kann den Status zuvor ausgegebener Befehlsanfragen abfragen. Um den Status eines Befehls abzurufen, benötigen Sie die Befehls-ID (verfügbar über die Anfrage zum Ausführen eines Befehls). Das folgende Snippet zeigt, wie ein GetCommandRequest an ADP gesendet wird.

import android.util.Log;
...
import com.google.android.managementapi.commands.LocalCommandClientFactory;
...
import com.google.android.managementapi.commands.model.GetCommandRequest;
import com.google.common.util.concurrent.FutureCallback;
import com.google.common.util.concurrent.Futures;
import com.google.common.util.concurrent.MoreExecutors;

...
  void getCommand(String commandId) {
    Futures.addCallback(
        LocalCommandClientFactory.create(getApplication())
            .getCommand(GetCommandRequest.builder().setCommandId(commandId).build()),
        new FutureCallback<Command>() {
          @Override
          public void onSuccess(Command result) {
            // Process the returned command result here
            Log.i(Constants.TAG, "Successfully issued command");
          }

          @Override
          public void onFailure(Throwable t) {
            Log.e(Constants.TAG, "Failed to issue command", t);
          }
        },
        MoreExecutors.directExecutor());
  }
  ...

Rückrufe für Änderungen des Befehlsstatus abhören

Eine Erweiterungs-App kann optional einen Callback registrieren, um Aktualisierungen für Statusänderungen von lang andauernden Befehlen zu erhalten. Gehen Sie dazu so vor:

Statusänderungen von Befehlen werden an CommandListener gemeldet. Implementieren Sie diese Schnittstelle in Ihrer App und geben Sie an, wie die empfangenen Statusaktualisierungen verarbeitet werden sollen.
Erweitern Sie NotificationReceiverService und stellen Sie eine CommandListener-Instanz über die Methode getCommandListener bereit.

Konfigurieren Sie die Anwendungsrichtlinie, um Ihrer App die Rolle COMPANION_APP zuzuweisen (siehe Richtlinienkonfiguration).

import com.google.android.managementapi.commands.CommandListener;
import com.google.android.managementapi.notification.NotificationReceiverService;

...

public class SampleCommandService extends NotificationReceiverService {

 @Override
 public CommandListener getCommandListener() {
   // return the concrete implementation from previous step
   return ...;
 }
}

Richtlinienkonfiguration

Damit die Erweiterungs-App direkt mit ADP kommunizieren kann, muss der EMM der App die Rolle COMPANION_APP über das Feld roles in der Anwendungsrichtlinie zuweisen.

 "applications": [{
   "packageName": "com.amapi.extensibility.demo",
   "installType": "FORCE_INSTALLED",
   "roles": [
     { "roleType": "COMPANION_APP" }
   ]
 }]

Weitere verfügbare Optionen finden Sie unter Gerät mit App-Rollenrichtlinien bereitstellen.

Test

Unittest

LocalCommandClient ist eine Schnittstelle und ermöglicht daher die Bereitstellung einer testbaren Implementierung.

Integrationstests

Für Tests mit ADP sind folgende Informationen erforderlich:

Paketname der Erweiterungs-App.
Der Base64-codierte SHA-256-Hash der Signatur, die mit dem App-Paket verknüpft ist.
Optional: Wenn Sie den Callback testen möchten, geben Sie den vollständig qualifizierten Namen des Dienstes aus dem neu eingeführten Dienst zur Unterstützung von Callbacks an. (Vollständig qualifizierter Name von CommandService im Beispiel).