Este guia para desenvolvedores explica como o controlador de política de dispositivo (DPC, na sigla em inglês) pode gerenciar vários usuários do Android em dispositivos dedicados.
Visão geral
Seu DPC pode ajudar várias pessoas a compartilhar um único dispositivo dedicado. O DPC executado em um dispositivo totalmente gerenciado pode criar e gerenciar dois tipos de usuários:
- Os usuários secundários são usuários do Android com apps e dados separados salvos entre sessões. Você gerencia o usuário com um componente de administrador. Esses usuários são úteis para os casos em que um dispositivo é retirado no início de um turno, como motoristas de entrega ou profissionais de segurança.
- Usuários temporários são usuários secundários que o sistema exclui quando o usuário para, sai da página ou o dispositivo é reinicializado. Esses usuários são úteis nos casos em que os dados podem ser excluídos após o término da sessão, como em quiosques de Internet de acesso público.
Você usa o DPC existente para gerenciar o dispositivo dedicado e os usuários secundários. Um componente de administrador no DPC define a si mesmo como administrador para novos usuários secundários quando você os cria.
Os administradores de um usuário secundário precisam pertencer ao mesmo pacote que o administrador do dispositivo totalmente gerenciado. Para simplificar o desenvolvimento, recomendamos compartilhar um administrador entre o dispositivo e os usuários secundários.
Normalmente, gerenciar vários usuários em dispositivos dedicados requer o Android 9.0. No entanto, alguns dos métodos usados neste guia para desenvolvedores estão disponíveis em versões anteriores do Android.
Criar usuários
O DPC pode criar outros usuários em segundo plano e depois trocá-los para o primeiro plano. O processo é quase o mesmo para usuários secundários e temporários. Implemente as etapas a seguir nos administradores do dispositivo totalmente gerenciado e do usuário secundário:
- Chame
DevicePolicyManager.createAndManageUser()
. Para criar um usuário temporário, incluaMAKE_USER_EPHEMERAL
no argumento de flags. - Chame
DevicePolicyManager.startUserInBackground()
para iniciar o usuário em segundo plano. O usuário começa a correr, mas você precisa concluir a configuração antes de levar o usuário ao primeiro plano e mostrá-lo para a pessoa que usa o dispositivo. - No administrador do usuário secundário, chame
DevicePolicyManager.setAffiliationIds()
para afiliar o novo usuário ao usuário principal. Consulte Coordenação de DPC abaixo. - De volta ao administrador do dispositivo totalmente gerenciado, chame
DevicePolicyManager.switchUser()
para colocar o usuário em primeiro plano.
O exemplo a seguir mostra como adicionar a etapa 1 ao DPC:
Kotlin
val dpm = getContext().getSystemService(Context.DEVICE_POLICY_SERVICE) as DevicePolicyManager // If possible, reuse an existing affiliation ID across the // primary user and (later) the ephemeral user. val identifiers = dpm.getAffiliationIds(adminName) if (identifiers.isEmpty()) { identifiers.add(UUID.randomUUID().toString()) dpm.setAffiliationIds(adminName, identifiers) } // Pass an affiliation ID to the ephemeral user in the admin extras. val adminExtras = PersistableBundle() adminExtras.putString(AFFILIATION_ID_KEY, identifiers.first()) // Include any other config for the new user here ... // Create the ephemeral user, using this component as the admin. try { val ephemeralUser = dpm.createAndManageUser( adminName, "tmp_user", adminName, adminExtras, DevicePolicyManager.MAKE_USER_EPHEMERAL or DevicePolicyManager.SKIP_SETUP_WIZARD) } catch (e: UserManager.UserOperationException) { if (e.userOperationResult == UserManager.USER_OPERATION_ERROR_MAX_USERS) { // Find a way to free up users... } }
Java
DevicePolicyManager dpm = (DevicePolicyManager) getContext().getSystemService(Context.DEVICE_POLICY_SERVICE); // If possible, reuse an existing affiliation ID across the // primary user and (later) the ephemeral user. Set<String> identifiers = dpm.getAffiliationIds(adminName); if (identifiers.isEmpty()) { identifiers.add(UUID.randomUUID().toString()); dpm.setAffiliationIds(adminName, identifiers); } // Pass an affiliation ID to the ephemeral user in the admin extras. PersistableBundle adminExtras = new PersistableBundle(); adminExtras.putString(AFFILIATION_ID_KEY, identifiers.iterator().next()); // Include any other config for the new user here ... // Create the ephemeral user, using this component as the admin. try { UserHandle ephemeralUser = dpm.createAndManageUser( adminName, "tmp_user", adminName, adminExtras, DevicePolicyManager.MAKE_USER_EPHEMERAL | DevicePolicyManager.SKIP_SETUP_WIZARD); } catch (UserManager.UserOperationException e) { if (e.getUserOperationResult() == UserManager.USER_OPERATION_ERROR_MAX_USERS) { // Find a way to free up users... } }
Ao criar ou iniciar um novo usuário, é possível verificar o motivo das falhas
capturando a exceção UserOperationException
e chamando
getUserOperationResult()
. Exceder os limites de
usuários são motivos comuns para falhas:
A criação de um usuário pode levar algum tempo. Se você cria usuários com frequência, pode melhorar a experiência deles preparando um usuário pronto para uso em segundo plano. Talvez seja necessário equilibrar as vantagens de um usuário pronto para usar e o número máximo de usuários permitidos em um dispositivo.
Identificação
Depois de criar um novo usuário, você deve se referir a ele com um número de série
persistente. Não mantenha os UserHandle
, porque o sistema os recicla conforme você
cria e exclui usuários. Consiga o número de série chamando
UserManager.getSerialNumberForUser()
:
Kotlin
// After calling createAndManageUser() use a device-unique serial number // (that isn’t recycled) to identify the new user. secondaryUser?.let { val userManager = getContext().getSystemService(UserManager::class.java) val ephemeralUserId = userManager!!.getSerialNumberForUser(it) // Save the serial number to storage ... }
Java
// After calling createAndManageUser() use a device-unique serial number // (that isn’t recycled) to identify the new user. if (secondaryUser != null) { UserManager userManager = getContext().getSystemService(UserManager.class); long ephemeralUserId = userManager.getSerialNumberForUser(secondaryUser); // Save the serial number to storage ... }
Configuração do usuário
Dependendo das necessidades dos usuários, você pode personalizar a configuração de usuários
secundários. É possível incluir as seguintes sinalizações ao chamar createAndManageUser()
:
SKIP_SETUP_WIZARD
- Ignora a execução do assistente de configuração de novo usuário que verifica e instala atualizações, solicita que o usuário adicione uma Conta do Google com os serviços do Google e define um bloqueio de tela. Isso pode levar algum tempo e pode não ser aplicável a todos os usuários, como quiosques de Internet públicos, por exemplo.
LEAVE_ALL_SYSTEM_APPS_ENABLED
- Deixa todos os apps do sistema ativados para o novo usuário. Se você não definir essa flag, o novo usuário terá apenas o conjunto mínimo de apps necessários para o smartphone operar, geralmente um navegador de arquivos, discador de telefone, contatos e mensagens SMS.
Seguir o ciclo de vida do usuário
Seu DPC, se for um administrador do dispositivo totalmente gerenciado, pode achar útil
saber quando os usuários secundários mudam. Para executar tarefas subsequentes após mudanças, substitua
esses métodos de callback na subclasse DeviceAdminReceiver
do DPC:
onUserStarted()
- Chamado após o sistema iniciar um usuário. Esse usuário ainda pode estar com a configuração
ou em execução em segundo plano. Você pode buscar o usuário pelo argumento
startedUser
. onUserSwitched()
- Chamado depois que o sistema alterna para um usuário diferente. Você pode usar o argumento
switchedUser
para chamar o novo usuário que está em execução em primeiro plano. onUserStopped()
- Chamado depois que o sistema interrompe um usuário porque ele saiu, mudou para um
novo usuário (se for temporário) ou o DPC o interrompeu. É possível conseguir o usuário do argumento
stoppedUser
. onUserAdded()
- Chamado quando o sistema adiciona um novo usuário. Normalmente, os usuários secundários não estão
totalmente configurados quando o DPC recebe o callback. Você pode buscar o usuário do argumento
newUser
. onUserRemoved()
- Chamado depois que o sistema exclui um usuário. Como o usuário já foi excluído,
não é possível acessar o usuário representado pelo argumento
removedUser
.
Para saber quando o sistema traz um usuário para o primeiro plano ou o envia para o
segundo plano, os apps podem registrar um receptor para as transmissões
ACTION_USER_FOREGROUND
e
ACTION_USER_BACKGROUND
.
Descobrir usuários
Para conseguir todos os usuários secundários, um administrador de um dispositivo totalmente gerenciado pode chamar
DevicePolicyManager.getSecondaryUsers()
. Os resultados incluem todos os usuários secundários ou temporários criados pelo administrador. Os resultados também
incluem usuários secundários (ou um usuário convidado) que uma pessoa que usa o dispositivo possa
ter criado. Os resultados não incluem perfis de trabalho porque eles não são
usuários secundários. O exemplo a seguir mostra como usar esse método:
Kotlin
// The device is stored for the night. Stop all running secondary users. dpm.getSecondaryUsers(adminName).forEach { dpm.stopUser(adminName, it) }
Java
// The device is stored for the night. Stop all running secondary users. for (UserHandle user : dpm.getSecondaryUsers(adminName)) { dpm.stopUser(adminName, user); }
Veja outros métodos que você pode chamar para descobrir o status de usuários secundários:
DevicePolicyManager.isEphemeralUser()
- Chame este método do administrador de um usuário secundário para descobrir se esse é um usuário temporário.
DevicePolicyManager.isAffiliatedUser()
- Chame esse método do administrador de um usuário secundário para descobrir se esse usuário é afiliado ao usuário principal. Para saber mais sobre afiliação, consulte a coordenação de DPC abaixo.
Gerenciamento de usuários
Se você quiser gerenciar completamente o ciclo de vida do usuário, chame APIs para controlar quando e como o dispositivo muda os usuários. Por exemplo, é possível excluir um usuário quando um dispositivo não é usado por um período ou enviar pedidos não enviados a um servidor antes que o turno da pessoa termine.
Sair
O Android 9.0 adicionou um botão de logout à tela de bloqueio para que um usuário do dispositivo possa encerrar a sessão. Depois de tocar no botão, o sistema interrompe o usuário secundário, exclui o usuário se ele for temporário e o usuário principal retorna ao primeiro plano. O Android oculta o botão quando o usuário principal está em primeiro plano porque ele não pode sair da conta.
Por padrão, o Android não mostra o botão "Encerrar sessão", mas o administrador de um
dispositivo totalmente gerenciado pode ativá-lo chamando
DevicePolicyManager.setLogoutEnabled()
. Se você precisar
confirmar o estado atual do botão, chame
DevicePolicyManager.isLogoutEnabled()
.
O administrador de um usuário secundário pode desconectar o usuário de maneira programática e retornar ao usuário principal. Primeiro, confirme se os usuários secundários e principais são
afiliados e, em seguida, chame DevicePolicyManager.logoutUser()
. Se
o usuário desconectado for um usuário temporário, o sistema será interrompido e
excluirá o usuário.
Trocar de usuário
Para alternar para um usuário secundário diferente, o administrador de um dispositivo totalmente gerenciado pode
chamar DevicePolicyManager.switchUser()
. Por conveniência, você
pode transmitir null
para alternar para o usuário principal.
Interromper um usuário
Para interromper um usuário secundário, um DPC proprietário de um dispositivo totalmente gerenciado pode chamar
DevicePolicyManager.stopUser()
. Se o usuário interrompido for um usuário temporário, ele será interrompido e excluído.
Recomendamos interromper os usuários sempre que possível para permanecer abaixo do número máximo de usuários em execução no dispositivo.
Excluir um usuário
Para excluir permanentemente um usuário secundário, um DPC pode chamar um destes
métodos DevicePolicyManager
:
- Um administrador de um dispositivo totalmente gerenciado pode chamar
removeUser()
. - Um administrador do usuário secundário pode chamar
wipeData()
.
O sistema exclui usuários temporários quando eles são desconectados, interrompidos ou desligados.
Desativar a interface padrão
Se o DPC fornecer uma interface para gerenciar usuários, você poderá desativar a interface
multiusuário integrada do Android. Para fazer isso, chame
DevicePolicyManager.setLogoutEnabled()
e adicione a restrição
DISALLOW_USER_SWITCH
, conforme mostrado no
exemplo a seguir:
Kotlin
// Explicitly disallow logging out using Android UI (disabled by default). dpm.setLogoutEnabled(adminName, false) // Disallow switching users in Android's UI. This DPC can still // call switchUser() to manage users. dpm.addUserRestriction(adminName, UserManager.DISALLOW_USER_SWITCH)
Java
// Explicitly disallow logging out using Android UI (disabled by default). dpm.setLogoutEnabled(adminName, false); // Disallow switching users in Android's UI. This DPC can still // call switchUser() to manage users. dpm.addUserRestriction(adminName, UserManager.DISALLOW_USER_SWITCH);
O usuário do dispositivo não pode adicionar usuários secundários com a interface integrada do Android
porque os administradores de dispositivos totalmente gerenciados adicionam automaticamente a
restrição de usuário DISALLOW_ADD_USER
.
Mensagens da sessão
Quando o usuário de um dispositivo muda para um novo usuário, o Android mostra um painel para destacar a chave. O Android mostra as seguintes mensagens:
- Mensagem de início da sessão do usuário mostrada quando o dispositivo alterna do usuário principal para um usuário secundário.
- Mensagem da sessão do usuário final exibida quando o dispositivo retorna de um usuário secundário ao usuário principal.
O sistema não mostra as mensagens ao alternar entre dois usuários secundários.
Como as mensagens podem não ser adequadas para todas as situações, é possível mudar o texto delas. Por exemplo, se sua solução usa sessões de usuário temporárias, você pode refletir isso em mensagens como: Interrompendo a sessão do navegador e excluindo dados pessoais...
O sistema mostra a mensagem por apenas alguns segundos, então cada mensagem
precisa ser uma frase curta e clara. Para personalizar as mensagens, o administrador pode chamar
os métodos DevicePolicyManager
setStartUserSessionMessage()
e
setEndUserSessionMessage()
, conforme mostrado no
exemplo a seguir:
Kotlin
// Short, easy-to-read messages shown at the start and end of a session. // In your app, store these strings in a localizable resource. internal val START_USER_SESSION_MESSAGE = "Starting guest session…" internal val END_USER_SESSION_MESSAGE = "Stopping & clearing data…" // ... dpm.setStartUserSessionMessage(adminName, START_USER_SESSION_MESSAGE) dpm.setEndUserSessionMessage(adminName, END_USER_SESSION_MESSAGE)
Java
// Short, easy-to-read messages shown at the start and end of a session. // In your app, store these strings in a localizable resource. private static final String START_USER_SESSION_MESSAGE = "Starting guest session…"; private static final String END_USER_SESSION_MESSAGE = "Stopping & clearing data…"; // ... dpm.setStartUserSessionMessage(adminName, START_USER_SESSION_MESSAGE); dpm.setEndUserSessionMessage(adminName, END_USER_SESSION_MESSAGE);
Transmita null
para excluir suas mensagens personalizadas e retornar às mensagens padrão do Android. Se você precisar verificar o texto da mensagem atual, chame
getStartUserSessionMessage()
ou
getEndUserSessionMessage()
.
Seu DPC precisa definir mensagens localizadas para a localidade atual do usuário. Também é necessário atualizar as mensagens quando a localidade do usuário muda:
Kotlin
override fun onReceive(context: Context?, intent: Intent?) { // Added the <action android:name="android.intent.action.LOCALE_CHANGED" /> // intent filter for our DeviceAdminReceiver subclass in the app manifest file. if (intent?.action === ACTION_LOCALE_CHANGED) { // Android's resources return a string suitable for the new locale. getManager(context).setStartUserSessionMessage( getWho(context), context?.getString(R.string.start_user_session_message)) getManager(context).setEndUserSessionMessage( getWho(context), context?.getString(R.string.end_user_session_message)) } super.onReceive(context, intent) }
Java
public void onReceive(Context context, Intent intent) { // Added the <action android:name="android.intent.action.LOCALE_CHANGED" /> // intent filter for our DeviceAdminReceiver subclass in the app manifest file. if (intent.getAction().equals(ACTION_LOCALE_CHANGED)) { // Android's resources return a string suitable for the new locale. getManager(context).setStartUserSessionMessage( getWho(context), context.getString(R.string.start_user_session_message)); getManager(context).setEndUserSessionMessage( getWho(context), context.getString(R.string.end_user_session_message)); } super.onReceive(context, intent); }
Coordenação de DPC
O gerenciamento de usuários secundários normalmente precisa de duas instâncias do DPC: uma que tenha o dispositivo totalmente gerenciado e a outra seja proprietária do usuário secundário. Ao criar um novo usuário, o administrador do dispositivo totalmente gerenciado define outra instância de si mesmo como administrador do novo usuário.
Usuários afiliados
Algumas das APIs deste guia para desenvolvedores só funcionam quando os usuários secundários são afiliados. Como o Android desativa alguns recursos (por exemplo, registro de rede) quando você adiciona novos usuários secundários não afiliados ao dispositivo, você precisa afiliar os usuários assim que possível. Veja o exemplo em Configuração abaixo.
Configurar
Configure novos usuários secundários (no DPC que é proprietário do usuário secundário) antes
de permitir que as pessoas os usem. É possível fazer essa configuração no callback
DeviceAdminReceiver.onEnabled()
. Se você
já definiu algum extra de administrador na chamada para createAndManageUser()
, poderá acessar os
valores do argumento intent
. O exemplo a seguir mostra um DPC filiando
um novo usuário secundário no callback:
Kotlin
override fun onEnabled(context: Context?, intent: Intent?) { super.onEnabled(context, intent) // Get the affiliation ID (our DPC previously put in the extras) and // set the ID for this new secondary user. intent?.getStringExtra(AFFILIATION_ID_KEY)?.let { val dpm = getManager(context) dpm.setAffiliationIds(getWho(context), setOf(it)) } // Continue setup of the new secondary user ... }
Java
public void onEnabled(Context context, Intent intent) { // Get the affiliation ID (our DPC previously put in the extras) and // set the ID for this new secondary user. String affiliationId = intent.getStringExtra(AFFILIATION_ID_KEY); if (affiliationId != null) { DevicePolicyManager dpm = getManager(context); dpm.setAffiliationIds(getWho(context), new HashSet<String>(Arrays.asList(affiliationId))); } // Continue setup of the new secondary user ... }
RPCs entre DPCs
Mesmo que as duas instâncias de DPC estejam sendo executadas em usuários separados, os DPCs
que têm o dispositivo e os usuários secundários podem se comunicar entre si.
Como a chamada do serviço de outro DPC ultrapassa os limites do usuário, seu DPC não pode
chamar bindService()
como você normalmente no
Android. Para vincular um serviço em execução em
outro usuário, chame
DevicePolicyManager.bindDeviceAdminServiceAsUser()
.
O DPC só pode se vincular a serviços em execução nos usuários retornados por
DevicePolicyManager.getBindDeviceAdminTargetUsers()
.
O exemplo a seguir mostra o administrador de uma vinculação secundária do usuário ao administrador
do dispositivo totalmente gerenciado:
Kotlin
// From a secondary user, the list contains just the primary user. dpm.getBindDeviceAdminTargetUsers(adminName).forEach { // Set up the callbacks for the service connection. val intent = Intent(mContext, FullyManagedDeviceService::class.java) val serviceconnection = object : ServiceConnection { override fun onServiceConnected(componentName: ComponentName, iBinder: IBinder) { // Call methods on service ... } override fun onServiceDisconnected(componentName: ComponentName) { // Clean up or reconnect if needed ... } } // Bind to the service as the primary user [it]. val bindSuccessful = dpm.bindDeviceAdminServiceAsUser(adminName, intent, serviceconnection, Context.BIND_AUTO_CREATE, it) }
Java
// From a secondary user, the list contains just the primary user. List<UserHandle> targetUsers = dpm.getBindDeviceAdminTargetUsers(adminName); if (targetUsers.isEmpty()) { // If the users aren't affiliated, the list doesn't contain any users. return; } // Set up the callbacks for the service connection. Intent intent = new Intent(mContext, FullyManagedDeviceService.class); ServiceConnection serviceconnection = new ServiceConnection() { @Override public void onServiceConnected( ComponentName componentName, IBinder iBinder) { // Call methods on service ... } @Override public void onServiceDisconnected(ComponentName componentName) { // Clean up or reconnect if needed ... } }; // Bind to the service as the primary user. UserHandle primaryUser = targetUsers.get(0); boolean bindSuccessful = dpm.bindDeviceAdminServiceAsUser( adminName, intent, serviceconnection, Context.BIND_AUTO_CREATE, primaryUser);
Outros recursos
Para saber mais sobre dispositivos dedicados, leia os seguintes documentos:
- A Visão geral de dispositivos dedicados é uma visão geral de dispositivos dedicados.
- O artigo Modo de bloqueio de tarefas explica como bloquear um dispositivo dedicado a um único app ou conjunto de apps.
- Manual de dispositivos dedicados com mais exemplos para restringir os dispositivos dedicados e melhorar a experiência do usuário.