Aplikasi ekstensi dan perintah lokal

Android Management API (AMAPI) SDK memungkinkan aplikasi ekstensi yang ditentukan EMM untuk berkomunikasi langsung dengan Kebijakan Perangkat Android (ADP) dan menjalankan Commands di perangkat.

Mengintegrasikan dengan AMAPI SDK memberikan informasi selengkapnya tentang library ini dan cara menambahkannya ke aplikasi Anda.

Setelah mengintegrasikan SDK, aplikasi ekstensi Anda dapat berkomunikasi dengan ADP untuk:

• mengirim permintaan perintah
• membuat kueri status permintaan perintah
• menerima perubahan status perintah

Memberikan Perintah

Aplikasi ekstensi dapat meminta perintah untuk dikeluarkan menggunakan ADP. IssueCommandRequest berisi objek permintaan yang akan berisi detail tentang perintah yang akan dikeluarkan dan parameter tertentu.

Hapus data aplikasi

Cuplikan berikut menunjukkan cara mengeluarkan permintaan untuk menghapus data paket:

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

Contoh sebelumnya menunjukkan cara mengeluarkan permintaan hapus data aplikasi untuk paket yang ditentukan dan menunggu hingga perintah berhasil dikeluarkan. Jika berhasil dikeluarkan, objek Command akan ditampilkan dengan status perintah saat ini dan ID perintah yang nantinya dapat digunakan untuk mengkueri status perintah yang berjalan lama.

Menghapus total perangkat atau profil kerja

Aplikasi pendamping dapat mengeluarkan perintah Wipe lokal saat admin IT menetapkan peran COMPANION_APP dengan kemampuan tambahan LOCAL_DEVICE_WIPE_COMMAND_ALLOWED. Pada perangkat milik perusahaan, tindakan ini akan mereset perangkat ke setelan pabrik; pada perangkat milik pribadi dengan profil kerja, tindakan ini akan menghapus profil kerja. Jika aplikasi tidak memiliki peran dan kemampuan tambahan ini, permintaan akan gagal. Untuk mengetahui detailnya, lihat Konfigurasi Kebijakan.

Kedua parameter Wipe bersifat opsional. Jika Anda tidak ingin menentukan nilai, hapus setter builder atau teruskan koleksi kosong atau string kosong (jangan teruskan null).

• WipeDataFlag nilai mengontrol data yang dihapus total:
  • PRESERVE_RESET_PROTECTION_DATA: Menyimpan data perlindungan reset ke setelan pabrik, yang dihapus secara default. Hanya berlaku untuk perangkat milik perusahaan.
  • WIPE_EXTERNAL_STORAGE: Juga menghapus penyimpanan eksternal, seperti kartu SD. Hanya berlaku untuk perangkat milik perusahaan.
  • WIPE_ESIMS: Menghapus semua eSIM dari perangkat milik perusahaan. Di perangkat milik pribadi, hanya menghapus eSIM terkelola (di Android 16 atau yang lebih baru, eSIM terkelola selalu dihapus dengan profil kerja, terlepas dari apakah tanda ini ditetapkan atau tidak).
• wipeReason: Pesan singkat, maksimal 200 karakter, yang ditampilkan kepada pengguna saat profil kerja dihapus dari perangkat milik pribadi. Setelan ini tidak berpengaruh pada perangkat milik perusahaan.

Cuplikan berikut menunjukkan cara mengeluarkan permintaan untuk menghapus total perangkat atau profil kerja:

import android.content.Context
import android.util.Log
...
import com.google.android.managementapi.commands.CommandException
import com.google.android.managementapi.commands.LocalCommandClientFactory
import com.google.android.managementapi.commands.model.IssueCommandRequest
import com.google.android.managementapi.commands.model.IssueCommandRequest.Wipe
import com.google.android.managementapi.commands.model.IssueCommandRequest.Wipe.WipeDataFlag

...
  suspend fun issueWipeCommand(
      context: Context,
      wipeDataFlags: List<WipeDataFlag>,
      wipeReason: String,
  ) {
    try {
      val command =
          LocalCommandClientFactory.create(context)
              .issueCommandAwait(createWipeRequest(wipeDataFlags, wipeReason))
      Log.i(TAG, "Successfully issued wipe command: ${command.commandId}")
    } catch (e: CommandException) {
      Log.e(TAG, "Failed to issue wipe command", e)
    }
  }

  fun createWipeRequest(
      wipeDataFlags: List<WipeDataFlag>,
      wipeReason: String,
  ): IssueCommandRequest =
      IssueCommandRequest.builder()
          .setWipe(
              Wipe.builder()
                  .setWipeDataFlags(wipeDataFlags)
                  .setWipeReason(wipeReason)
                  .build()
          )
          .build()
...

import android.content.Context;
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.IssueCommandRequest;
import com.google.android.managementapi.commands.model.IssueCommandRequest.Wipe;
import com.google.android.managementapi.commands.model.IssueCommandRequest.Wipe.WipeDataFlag;
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 issueWipeCommand(
      Context context,
      ImmutableList<WipeDataFlag> wipeDataFlags,
      String wipeReason) {
    Futures.addCallback(
        LocalCommandClientFactory.create(context)
            .issueCommand(createWipeRequest(wipeDataFlags, wipeReason)),
        new FutureCallback<Command>() {
          @Override
          public void onSuccess(Command result) {
            Log.i(TAG, "Successfully issued wipe command: " + result.getCommandId());
          }

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

  IssueCommandRequest createWipeRequest(
      ImmutableList<WipeDataFlag> wipeDataFlags, String wipeReason) {
    return IssueCommandRequest.builder()
        .setWipe(
            Wipe.builder()
                .setWipeDataFlags(wipeDataFlags)
                .setWipeReason(wipeReason)
                .build())
        .build();
  }
...

Mendapatkan Perintah

Aplikasi ekstensi dapat mengkueri status permintaan perintah yang dikeluarkan sebelumnya. Untuk mengambil status perintah, Anda memerlukan ID perintah (tersedia dari permintaan perintah masalah). Cuplikan berikut menunjukkan cara mengirim GetCommandRequest ke 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());
  }
  ...

Memproses callback perubahan status Perintah

Aplikasi ekstensi dapat mendaftarkan callback secara opsional untuk menerima update terkait perubahan status perintah yang berjalan lama dengan mengikuti langkah-langkah berikut:

1. Perubahan status perintah akan diberitahukan ke CommandListener, implementasikan antarmuka ini di aplikasi Anda dan berikan implementasi tentang cara menangani update status yang diterima.
2. Perluas NotificationReceiverService dan berikan instance CommandListener melalui metode getCommandListener.

3. Konfigurasikan kebijakan aplikasi untuk menetapkan peran COMPANION_APP ke aplikasi Anda (lihat Konfigurasi Kebijakan).

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

Konfigurasi Kebijakan

Agar aplikasi pendamping dapat berkomunikasi langsung dengan ADP, EMM harus menetapkan peran COMPANION_APP ke aplikasi menggunakan kolom roles dalam kebijakan aplikasi:

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

Untuk mengizinkan aplikasi pendamping mengeluarkan perintah Wipe lokal, tetapkan extraCapabilities.localDeviceWipeCommand ke LOCAL_DEVICE_WIPE_COMMAND_ALLOWED:

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

Untuk opsi tambahan yang tersedia, lihat Menyediakan perangkat dengan kebijakan peran aplikasi.

Layanan yang memproses perubahan status perintah akan otomatis ditemukan oleh ADP menggunakan metadata dalam manifes aplikasi, dan tidak perlu lagi ditentukan dalam kebijakan sebagai notificationReceiver. Untuk mengetahui detail tentang cara menyiapkan aplikasi dan manifes, lihat Mengelola peran aplikasi.

Pengujian

Pengujian unit

LocalCommandClient adalah antarmuka sehingga memungkinkan untuk menyediakan implementasi yang dapat diuji.

Pengujian integrasi

Informasi berikut akan diperlukan untuk pengujian dengan ADP:

1. Nama paket aplikasi ekstensi.
2. Hash SHA-256 berenkode base64 dari Tanda Tangan yang terkait dengan paket aplikasi.
3. Secara opsional, jika menguji callback - nama layanan yang sepenuhnya memenuhi syarat dari layanan yang baru diperkenalkan untuk mendukung callback. (Nama CommandService yang sepenuhnya memenuhi syarat dalam contoh).