Applications d'extension et commandes locales

Le SDK de l'API Android Management (AMAPI) permet à une application d'extension spécifiée par un fournisseur de gestion de la mobilité en entreprise (EMM) de communiquer directement avec Android Device Policy (ADP) et d'exécuter Commands sur l'appareil.

Remarque : Seule la commande ClearAppData est acceptée.

La section Intégrer le SDK AMAPI fournit plus d'informations sur cette bibliothèque et sur la façon de l'ajouter à votre application.

Une fois le SDK intégré, votre application d'extension peut communiquer avec ADP pour :

• envoyer des requêtes de commande ;
• interroger l'état des requêtes de commande ;
• recevoir les modifications de l'état des commandes.

Émettre une commande

Une application d'extension peut demander l'émission de commandes à l'aide d'ADP. IssueCommandRequest contient l'objet de requête qui contient des informations sur la commande à émettre et des paramètres spécifiques.

L'extrait suivant montre comment émettre une requête pour effacer les données du package :

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();
  }
...

L'exemple précédent montre comment émettre une requête d'effacement des données d'application pour des packages spécifiés et attendre que la commande ait été émise. Si l'émission réussit, un objet Command est renvoyé avec l'état actuel de la commande et l'ID de commande, qui peut être utilisé ultérieurement pour interroger l'état des commandes de longue durée.

Obtenir une commande

Une application d'extension peut interroger l'état des requêtes de commande émises précédemment. Pour récupérer l'état d'une commande, vous aurez besoin de son ID (disponible dans la requête d'émission de commande). L'extrait suivant montre comment envoyer un GetCommandRequest à ADP.

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());
  }
  ...

Écouter les rappels de modification de l'état des commandes

Une application d'extension peut éventuellement enregistrer un rappel pour recevoir des mises à jour sur les modifications d'état des commandes de longue durée en procédant comme suit :

1. Les modifications de l'état des commandes sont notifiées à CommandListener. Implémentez cette interface dans votre application et indiquez comment gérer les mises à jour d'état reçues.
2. Étendez NotificationReceiverService et fournissez une instance CommandListener via la méthode getCommandListener.

3. Configurez la règle d'application pour attribuer le rôle COMPANION_APP à votre application (voir Configuration des règles).

   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 ...;
    }
   }
   

Configuration des règles

Pour permettre à l'application d'extension de communiquer directement avec ADP, le fournisseur EMM doit attribuer le rôle COMPANION_APP à l'application à l'aide du champ roles dans la règle d'application.

Obsolète : Le champ extensionConfig est obsolète et ne doit pas être utilisé.

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

Pour obtenir d'autres options disponibles, consultez Provisionner l'appareil avec des règles de rôles d'application.

Remarque : Le service qui écoute les modifications de l’état des commandes est automatiquement détecté par ADP à l’aide des métadonnées du fichier manifeste de l’application. Il n’est plus nécessaire de le spécifier dans la règle en tant que notificationReceiver. Pour savoir comment préparer votre application et votre fichier manifeste,

consultez Gérer les rôles d'application.

Tests

Tests unitaires

LocalCommandClient est une interface qui permet de fournir une implémentation testable.

Tests d'intégration

Les informations suivantes sont nécessaires pour effectuer des tests avec ADP :

1. Nom du package de l'application d'extension.
2. Hachage SHA-256 encodé en base64 de la signature associée au package de l'application.
3. Éventuellement, si vous testez un rappel, nom complet du service du nouveau service introduit pour prendre en charge le rappel. (Nom complet de CommandService dans l'exemple).