Os provedores de gerenciamento de mobilidade empresarial (EMM) oferecem soluções para as organizações gerenciarem os dispositivos Android e os apps instalados neles. Essas soluções geralmente estão disponíveis como consoles da Web, chamados de consoles de EMM. Por meio de um console de EMM, os administradores de TI realizam tarefas de gerenciamento de dispositivos e apps em nome da organização.
Os apps voltados a organizações empresariais podem enviar feedback para EMMs na forma de estados de apps com chaves. As APIs estão disponíveis para que os EMMs recuperem dados de estado do app com chave, que podem ser exibidos no console de EMM. Esse canal de comunicação permite que os administradores de TI recebam feedback sobre o status dos apps instalados nos dispositivos que gerenciam.
Por exemplo, um app cliente de e-mail pode usar estados de app com chave para confirmar que uma conta foi configurada, informar quando ocorrem erros de sincronização ou enviar outras atualizações de status que o desenvolvedor do app considera adequadas.
Componentes de um estado de app com chave
Um estado de app com chave é composto pelo seguinte:
- Chave:identificador exclusivo do estado do app. Máximo de 100 caracteres.
- Mensagem:mensagem opcional que descreve o estado do app. Máximo de 1.000 caracteres. Observação: normalmente, as mensagens são significativamente mais curtas do que isso.
- Dados:valor opcional legível por máquina destinado a EMMs para permitir que os administradores de TI
configurem alertas ou filtros com base no valor. Por exemplo, um administrador de TI pode configurar um alerta se o campo de dados for
battery_percentage < 10
. Máximo de 1.000 caracteres. - Gravidade : a gravidade do estado do app. Os valores permitidos são
SEVERITY_ERROR
eSEVERITY_INFO
(padrão). Defina a gravidade comoSEVERITY_ERROR
apenas para condições de erro genuínos que uma organização precisa tomar para corrigir. - Carimbo de data/hora : quando um estado de app com chave é definido, ele é enviado automaticamente com um carimbo de data/hora em milissegundos desde a época.
Enviar feedback sobre as configurações gerenciadas
Se o app for compatível com configurações gerenciadas, recomendamos enviar estados de apps com chaves como uma maneira de atualizar os administradores de TI sobre o status das configurações definidas. O fluxo de trabalho de exemplo abaixo descreve uma maneira de fazer isso.
- Os administradores de TI usam o console de EMM para definir e enviar configurações gerenciadas para
um app instalado em um dispositivo totalmente gerenciado
ou dentro de um perfil de trabalho.
Por exemplo:
- Volume: "50%"
- Moeda: "USD"
- O app tenta aplicar as configurações. O volume foi definido como 50%, mas o código de moeda é inválido e não pode ser aplicado.
- Com base no status de cada configuração, o app define um estado vinculado.
Cada estado do app com chave contém uma chave exclusiva e uma mensagem com detalhes do
estado. Recomendamos associar a chave de configurações gerenciadas sempre que possível.
Por exemplo:
Tecla A mensagem Gravidade Timestamp volume
Definir como 50% SEVERITY_INFO
1554461130
currency
A moeda "USDD" não foi reconhecida SEVERITY_ERROR
1554461130
- O provedor de EMM recupera os estados do app com chave definidos pelo app e os exibe
no console de EMM. Por exemplo:
Configuração Status Ação necessária Hora Volume Definir como 50% Não 5 de abril de 2019, 10h45min30s Moeda ERRO: a moeda "USDD" não foi reconhecida. Sim 5 de abril de 2019, 10h45min30s O provedor de EMM também precisa sinalizar explicitamente todos os estados recebidos com
SEVERITY_ERROR
para o administrador de TI. Os administradores de TI podem visualizar as informações no console de EMM e tomar medidas para corrigir erros nas configurações definidas.
Informar erros resolvidos
Após a resolução de um erro, envie imediatamente um estado de acompanhamento do app para impedir que os EMMs exibam a mensagem de erro indefinidamente. Esse estado de acompanhamento precisa incluir:
- A mesma key da mensagem de erro inicial.
- Uma gravidade
SEVERITY_INFO
, que indica que o estado não está em uma condição de erro e não exige que a organização tome outras medidas.
Adicionar suporte a estados de apps com chave ao seu app
As etapas abaixo descrevem como integrar estados de apps com chave no seu app.
Etapa 1: adicionar o repositório Maven do Google ao seu arquivo settings.gradle
Adicione o repositório Maven do Google como um local de repositório no arquivo settings.gradle
do projeto, conforme mostrado abaixo:
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() } }
Etapa 2: adicionar a biblioteca de feedback da empresa ao arquivo build.gradle
do módulo
Adicione a seguinte dependência ao arquivo build.gradle
do módulo:
dependencies { implementation 'androidx.enterprise:enterprise-feedback:1.0.0' }
Etapa 3: acessar uma instância de KeyedAppStatesReporter
No método onCreate()
, receba e armazene uma instância de
KeyedAppStatesReporter
.
Isso permite um canal de comunicação entre seu app e os provedores de EMM.
Kotlin
val reporter = KeyedAppStatesReporter.create(context)
Java
KeyedAppStatesReporter reporter = KeyedAppStatesReporter.create(context);
Etapa 4: criar uma coleção de estados de apps com chave
Siga as práticas recomendadas abaixo ao criar estados de apps codificados:
- Nunca inclua informações de identificação pessoal (PII) em um estado. Os estados de apps com chaves não são adequados para dados sensíveis.
- Mantenha os estados do app com chave dentro dos limites definidos em
MAX_KEY_LENGTH
,MAX_MESSAGE_LENGTH
eMAX_DATA_LENGTH
. - Uma única chamada
setStates
ousetStatesImmediate
é limitada a 300 KB no total (aproximadamente 1/3 do total que pode ser armazenado por dia). Exceder esse valor resultará em um comportamento indefinido. - Defina a gravidade de um estado como
SEVERITY_ERROR
somente se existir uma condição que a organização precise corrigir. - Ao enviar um estado de app com erros, envie também um estado de acompanhamento quando os erros forem resolvidos, para que o EMM possa parar de sinalizar os erros no console.
- Para o estado de acompanhamento, use a mesma
chave do
estado inicial que retornou o erro e defina a gravidade como
SEVERITY_INFO
.
O snippet abaixo cria uma coleção de estados de apps codificados:
Kotlin
val states = hashSetOf(KeyedAppState.builder() .setKey("key") .setSeverity(KeyedAppState.SEVERITY_INFO) .setMessage("message") .setData("data") .build())
Java
Collectionstates = new HashSet<>(); states.add(KeyedAppState.builder() .setKey("key") .setSeverity(KeyedAppState.SEVERITY_INFO) .setMessage("message") .setData("data") .build());
Etapa 5: definir os estados do app com chave
O método setStates()
envia imediatamente os estados do app com chave ao app Play Store (nome do pacote:
com.android.vending
) se estiver instalado no dispositivo, assim como a qualquer administrador do
dispositivo ou perfil de trabalho.
Kotlin
keyedAppStatesReporter.setStates(states)
Java
keyedAppStatesReporter.setStates(states);