Enviar feedback do app para EMMs

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 e SEVERITY_INFO (padrão). Defina a gravidade como SEVERITY_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.

estados de apps com chaves para configurações gerenciadas
  1. 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"
  2. 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.
  3. 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
  4. 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 e MAX_DATA_LENGTH.
  • Uma única chamada setStates ou setStatesImmediate é 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

    Collection states = 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);

Testar estados de apps com chave

Para ver instruções detalhadas sobre o teste, consulte Feedback do app de teste.