Migrar dispositivos existentes para AMAPI

Os dispositivos já gerenciados pelo seu DPC personalizado podem ser migrados para o Android Device Policy (ADP) e aproveitar a API Android Management.

Pré-requisitos

Integrar o SDK da AMAPI ao seu DPC personalizado

O processo de migração exige que o aplicativo DPC personalizado integre o SDK da AMAPI. Para mais informações sobre essa biblioteca e como adicioná-la ao seu aplicativo, consulte o guia de integração do SDK da AMAPI.

Etapas para migrar um dispositivo

  1. Configure uma política para ser usada pelo dispositivo após a migração para a AMAPI. Para uma melhor experiência do usuário, isso precisa ser equivalente à política já aplicada no dispositivo pelo DPC. A política na AMAPI precisa pertencer à mesma empresa a que o dispositivo já pertence na API Play EMM. Uma determinada empresa tem o mesmo nome na AMAPI e na API Play EMM.
  2. Crie um token de migração para o dispositivo chamando enterprises.migrationTokens.create.
  3. Envie o value desse token de migração para seu DPC personalizado.
  4. Verifique se o Android Device Policy está instalado no dispositivo usando a API Play EMM.
  5. Use DpcMigrationClientFactory para criar um DpcMigrationClient
  6. No DpcMigrationClient, chame o método migrateDeviceManagementToAndroidManagementApi. Isso conclui a migração.
  7. O deviceState muda para ACTIVE, e você recebe uma mensagem STATUS_REPORT pelo canal do Pub/Sub.

Quando a migração é concluída, o app de ligação perde os privilégios de proprietário do dispositivo ou do perfil, já que eles são transferidos para o Android Device Policy. Esse processo pode ser representado pelo seguinte diagrama de sequência:

Diagrama de sequência da migração do DPC

Observação: o dispositivo precisa estar conectado à Internet para iniciar a migração. O processo foi projetado para ser resiliente a desconexões de rede durante o processo de migração, de modo que as principais operações que exigem conectividade de rede sejam feitas antes da transferência real dos direitos de proprietário do dispositivo ou do perfil do seu DPC para o Android Device Policy.

Token de migração

O servidor de EMM solicita um token de migração para sinalizar a intenção de migrar um dispositivo específico gerenciado por um DPC personalizado. Um token de migração pode ser usado até que a migração seja concluída ou até que ele expire.

Integração de DPC personalizado

Primeiro, você precisa criar um DpcMigrationRequest, transmitindo o token e, se necessário, a lista de redes Wi-Fi configuradas para o builder:

// Create a DpcMigrationRequest
DpcMigrationRequest request =
        DpcMigrationRequest.builder()
            .setMigrationToken(token)
            .build();

Em seguida, use um DpcMigrationClient e inicie o processo de migração com migrateDeviceManagementToAndroidManagementApi:

// Create a DpcMigrationClient
DpcMigrationClient dpcMigrationClient = DpcMigrationClientFactory.create(context);
try {
  // Use helper function to retrieve Admin component name
  var adminComponentName = getAdminComponent(context);

  ListenableFuture<DpcMigrationAttempt> futureAttempt =
          dpcMigrationClient.migrateDeviceManagementToAndroidManagementApi(
              new ComponentName(context, DpcMigrationNotificationReceiver.class),
              adminComponentName,
              request);
  // handle futureAttempt
} catch (RuntimeException e) {
  // send failure feedback: "Error: " + e
}

Configurar um NotificationReceiverService e acompanhar a migração

Implemente um NotificationReceiverService no seu DPC personalizado.

O processo de migração é rastreado no dispositivo por um DpcMigrationAttempt.

É possível usar diretamente o retornado por migrateDeviceManagementToAndroidManagementApi ou usar os métodos getMigrationAttempt e listMigrationAttempts para receber e listar tentativas de migração.

// Passing an empty name, we retrieve the last attempt
var request = GetDpcMigrationAttemptRequest.builder().build();

var attempt = client.getMigrationAttempt(request);

Se quiser, configure um DpcMigrationListener usando seu NotificationReceiverService para detectar atualizações de status do DpcMigrationAttempt.

// DpcMigrationNotificationReceiver for callback handling
public class DpcMigrationNotificationReceiver extends NotificationReceiverService
    implements DpcMigrationListener {

  @Override
  protected DpcMigrationListener getDpcMigrationListener() {
    return this;
  }

  @Override
  public void onMigrationStateChanged(DpcMigrationAttempt migrationAttempt) {
    // send success feedback
  }
}

Gerenciar redes Wi-Fi

Se houver redes Wi-Fi gerenciadas pelo DPC personalizado, a política ONC da AMAPI precisa corresponder às configurações dessas redes para que a AMAPI comece a gerenciá-las sem problemas. A interação da migração do DPC com o gerenciamento de Wi-Fi varia dependendo do modo de gerenciamento.

Dispositivos totalmente gerenciados e perfis de trabalho em dispositivos corporativos

Durante a migração, o Android Device Policy assume que qualquer rede Wi-Fi configurada na política com o mesmo SSID e tipo de segurança de uma rede Wi-Fi configurada no dispositivo é idêntica à rede Wi-Fi configurada correspondente. Portanto, as redes Wi-Fi configuradas pelo DPC personalizado não são alteradas após a migração até que haja uma mudança na política de ONC correspondente à rede. No entanto, se o DPC personalizado for desinstalado após a migração, as redes Wi-Fi configuradas por ele serão removidas automaticamente. O Android Device Policy continua aplicando a política e, se alguma dessas redes estiver configurada na política, as redes configuradas na política serão adicionadas normalmente.

Perfil de trabalho em um dispositivo pessoal

Por motivos técnicos, as redes Wi-Fi configuradas pelo DPC personalizado precisam ser removidas por ele para que o Android Device Policy comece a gerenciar essas redes. O SDK da AMAPI cuida disso e remove essas redes Wi-Fi antes de transferir a propriedade do DPC personalizado para o Android Device Policy, mas exige que o DPC personalizado transmita informações sobre essas redes em DpcMigrationRequest. Após a migração, as redes configuradas na política serão adicionadas normalmente. Por isso, recomendamos que as redes adicionadas pelo DPC personalizado também sejam configuradas na política.

Há alguns pontos importantes que você precisa considerar:

  • Se a rede ativa for uma rede Wi-Fi configurada por um DPC personalizado, o dispositivo poderá ficar off-line por um breve período durante a migração.
  • Somente as redes Wi-Fi configuradas pelo DPC personalizado precisam ser transmitidas em DpcMigrationRequest. Caso contrário, a migração vai falhar se uma rede não puder ser removida pelo SDK da AMAPI (por exemplo, uma rede Wi-Fi adicionada pelo usuário).
  • As redes Wi-Fi precisam ser transmitidas em DpcMigrationRequest apenas quando o DPC personalizado for um proprietário do perfil em um dispositivo pessoal. Caso contrário, a migração vai falhar.
  • Por motivos técnicos, o Android 12 é um caso excepcional em que as redes transmitidas em DpcMigrationRequest são ignoradas e todas as redes Wi-Fi configuradas pelo DPC personalizado são removidas automaticamente. Além disso, é necessário que o DPC personalizado tenha a permissão ACCESS_WIFI_STATE no Android 12 para perfis de trabalho em dispositivos pessoais. Caso contrário, a migração vai falhar.

Advertências

Confira algumas ressalvas relacionadas a esse recurso.

ID específico da empresa

Para perfis de trabalho no Android 12 e versões mais recentes, o ID específico da empresa, que pode ser acessado em DevicePolicyManager.getEnrollmentSpecificId, não muda no momento da migração. No entanto, se um perfil de trabalho gerenciado pelo Android Device Policy for criado novamente no dispositivo (por exemplo, após excluir o anterior ou após a redefinição de fábrica do dispositivo), o ID específico da empresa vai mudar nesse momento.

Perfis de trabalho em dispositivos totalmente gerenciados

Esse recurso não está disponível em dispositivos totalmente gerenciados que têm um perfil de trabalho com o Android 9 ou 10. Não tente migrar esses dispositivos. Independentemente de um erro ser gerado, esses dispositivos não são compatíveis com a migração de DPC.

Comando RESET_PASSWORD

Se o dispositivo tiver uma senha de tela de bloqueio, o comando RESET_PASSWORD só vai funcionar depois que o usuário confirmar as credenciais (por exemplo, inserindo o PIN novamente) após a migração. Se o dispositivo não tiver uma senha de tela de bloqueio, o comando RESET_PASSWORD poderá ser usado logo após a migração.