Cómo enviar comentarios sobre la app a EMM

Los proveedores de administración de movilidad empresarial (EMM) ofrecen soluciones para que las organizaciones administren dispositivos Android y las apps instaladas en ellos. Por lo general, estas soluciones están disponibles como consolas web, llamadas consolas de EMM. Con una consola de EMM, los administradores de TI realizan tareas de administración de apps y dispositivos en nombre de su organización.

Las apps orientadas a organizaciones empresariales pueden enviar comentarios a EMM en forma de estados de app con clave. Las APIs están disponibles para que las EMM recuperen datos del estado de la app con clave, que luego pueden mostrar en su consola de EMM. Este canal de comunicación permite a los administradores de TI recibir comentarios sobre el estado de las apps instaladas en los dispositivos que administran.

Por ejemplo, una app cliente de correo electrónico podría usar estados de la app con clave para confirmar que una cuenta se configuró correctamente, informar cuando se producen errores de sincronización o enviar cualquier otra actualización de estado que el desarrollador de la app considere adecuada.

Componentes del estado de una app con clave

El estado de la app con clave consta de lo siguiente:

  • Clave: Es el identificador único del estado de la app. Se admiten hasta 100 caracteres.
  • Mensaje: Es un mensaje opcional que describe el estado de la app. Se admiten hasta 1,000 caracteres. Nota: En general, los mensajes deberían ser mucho más cortos.
  • Datos: Es un valor opcional legible por máquina destinado a los EMM que permite a los administradores de TI configurar alertas o filtros basados en el valor. Por ejemplo, un administrador de TI podría configurar una alerta si el campo de datos battery_percentage < 10. Se admiten hasta 1,000 caracteres.
  • Gravedad: Es la gravedad del estado de la app. Los valores permitidos son SEVERITY_ERROR y SEVERITY_INFO (predeterminados). Solo establece la gravedad en SEVERITY_ERROR para las condiciones de error genuinas que una organización deba tomar medidas para corregir.
  • Marca de tiempo: Cuando se establece el estado de una app con clave, se envía automáticamente con una marca de tiempo en milisegundos desde la época.

Enviar comentarios sobre las configuraciones administradas

Si tu app admite configuraciones administradas, se recomienda enviar estados de app con clave como una forma de actualizar a los administradores de TI sobre el estado de las configuraciones que establecen. En el siguiente flujo de trabajo de ejemplo, se describe una forma de hacerlo.

estados de apps con clave para configuraciones administradas
  1. Los administradores de TI usan su consola de EMM para establecer y enviar configuraciones administradas para una app instalada en un dispositivo completamente administrado o en un perfil de trabajo. Por ejemplo:
    • Volumen: “50%”
    • Moneda: "USDD"
  2. La app intenta aplicar los parámetros de configuración. El volumen se configuró correctamente en 50%, pero el código de moneda no es válido y no se puede aplicar.
  3. Según el estado de cada configuración, la app establece un estado de app con clave. Cada estado de app con clave contiene una clave única y un mensaje con detalles del estado. Recomendamos hacer coincidir la clave de configuración administrada siempre que sea posible. Por ejemplo:
    Clave Mensajes Gravedad Marca de tiempo
    volume Establecer en 50% SEVERITY_INFO 1554461130
    currency No se reconoce la moneda “USDD” SEVERITY_ERROR 1554461130
  4. El proveedor de EMM recupera los estados de la app con clave que esta estableció y los muestra en su consola de EMM. Por ejemplo:
    Configuración Estado Acción obligatoria Hora
    Volumen Establecer en 50% No 5 de abril de 2019; 10:45:30 a.m.
    Moneda ERROR: No se reconoce la moneda "USDD". 5 de abril de 2019; 10:45:30 a.m.

    El proveedor de EMM también debe marcar de manera explícita los estados recibidos con SEVERITY_ERROR al administrador de TI. Los administradores de TI pueden ver la información en su consola de EMM y tomar medidas para rectificar cualquier error en los parámetros de configuración que establezcan.

Informar errores resueltos

Una vez que se resuelve un error, envía de inmediato un estado de seguimiento de la app para evitar que los EMM muestren el mensaje de error de forma indefinida. Este estado de seguimiento debe incluir lo siguiente:

  • La misma clave que el mensaje de error inicial.
  • Una gravedad de SEVERITY_INFO, que indica que el estado no está en una condición de error y no requiere que la organización realice ninguna otra acción.

Cómo agregar a tu app compatibilidad con estados de apps con clave

En los siguientes pasos, se describe cómo integrar estados de apps con clave en tu app.

Paso 1: Agrega el repositorio Maven de Google a tu archivo settings.gradle

Agrega el repositorio Maven de Google como una ubicación del repositorio en el archivo settings.gradle de tu proyecto, como se muestra a continuación:

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
       google()
  }
}

Paso 2: Agrega la biblioteca de comentarios para empresas al archivo build.gradle de nivel de módulo

Agrega la siguiente dependencia a tu archivo build.gradle a nivel del módulo:

dependencies {
    implementation 'androidx.enterprise:enterprise-feedback:1.0.0'
}

Paso 3: Obtén una instancia de KeyedAppStatesReporter

En el método onCreate(), obtén y almacena una instancia de KeyedAppStatesReporter. Esto habilita un canal de comunicación entre tu app y los proveedores de EMM.

Kotlin

val reporter = KeyedAppStatesReporter.create(context)

Java

KeyedAppStatesReporter reporter = KeyedAppStatesReporter.create(context);

Paso 4: Crea una colección de estados de la app con clave

Sigue las prácticas recomendadas que se describen a continuación cuando crees estados de apps con clave:

  • Nunca incluyas información de identificación personal (PII) en un estado, ya que los estados de las apps con clave no son adecuados para datos sensibles.
  • Mantén los estados de las apps con clave dentro de los límites definidos en MAX_KEY_LENGTH, MAX_MESSAGE_LENGTH y MAX_DATA_LENGTH.
  • Una sola llamada a setStates o setStatesImmediate tiene un límite total de 300 KB (aproximadamente 1/3 del total que se puede almacenar por día). Si superas esta regla, se generará un comportamiento indefinido.
  • Solo configura la gravedad de un estado en SEVERITY_ERROR si existe una condición que una organización debe tomar para corregirla.
  • Cuando envíes un estado de app que contenga errores, asegúrate de enviar también un estado de seguimiento cuando se resuelvan los errores para que EMM pueda dejar de marcarlos en su consola.
  • Para el estado de seguimiento, usa la misma clave que el estado inicial que mostró el error y establece la gravedad en SEVERITY_INFO.

El siguiente fragmento crea una colección de estados de apps con clave:

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

Paso 5: Configura los estados de la app con clave

El método setStates() envía de inmediato estados de apps con clave a la app de Play Store (nombre del paquete: com.android.vending) si está instalada en el dispositivo, además de a los administradores del dispositivo o del perfil de trabajo.

Kotlin

keyedAppStatesReporter.setStates(states)

Java

keyedAppStatesReporter.setStates(states);

Cómo probar estados de apps con clave

Para obtener instrucciones detalladas de la prueba, consulta Cómo probar los comentarios sobre la app.