Inviare feedback sull'app a EMM

I provider per la gestione della mobilità aziendale (EMM) offrono alle organizzazioni soluzioni per gestire i dispositivi Android e le app installate. Queste soluzioni sono generalmente disponibili come console web, chiamate console EMM. Utilizzando una console EMM, gli amministratori IT eseguono attività di gestione dei dispositivi e delle app per conto della propria organizzazione.

Le app che hanno come target le organizzazioni aziendali possono inviare feedback ai provider EMM sotto forma di stati chiave delle app. Le API sono disponibili per consentire ai provider EMM di recuperare i dati relativi allo stato delle app, che potranno poi visualizzare nella propria console EMM. Questo canale di comunicazione consente agli amministratori IT di ricevere feedback sullo stato delle app installate sui dispositivi che gestiscono.

Ad esempio, un'app client di posta potrebbe utilizzare gli stati dell'app con chiave per confermare che un account è stato configurato correttamente, segnalare quando si verificano errori di sincronizzazione o inviare altri aggiornamenti dello stato che lo sviluppatore dell'app ritiene appropriati.

Componenti di uno stato dell'app con chiave

Lo stato di un'app con chiave è costituito dai seguenti elementi:

• Chiave:identificatore univoco per lo stato dell'app. Massimo 100 caratteri.
• Messaggio: messaggio facoltativo che descrive lo stato dell'app. Massimo 1000 caratteri. Nota: in genere i messaggi dovrebbero essere notevolmente più brevi di questa.
• Dati: valore facoltativo leggibile dal computer destinato ai provider EMM per consentire agli amministratori IT di configurare avvisi o filtri in base al valore. Ad esempio, un amministratore IT potrebbe configurare un avviso se il campo dati battery_percentage < 10. Massimo 1000 caratteri.
• Gravità: la gravità dello stato dell'app. I valori consentiti sono SEVERITY_ERROR e SEVERITY_INFO (valore predefinito). Imposta la gravità su SEVERITY_ERROR solo per condizioni di errore reali che un'organizzazione deve intervenire per correggere.
• Timestamp: quando è impostato lo stato di un'app con chiave, questo viene inviato automaticamente con un timestamp in millisecondi dall'epoca.

Invia feedback sulle configurazioni gestite

Se la tua app supporta le configurazioni gestite, ti consigliamo di inviare stati dell'app con chiave per aggiornare gli amministratori IT sullo stato delle configurazioni che impostano. Il seguente flusso di lavoro di esempio descrive un modo per farlo.

1. Gli amministratori IT utilizzano la propria console EMM per impostare e inviare configurazioni gestite per un'app installata su un dispositivo completamente gestito o all'interno di un profilo di lavoro. Ad esempio:
   • Volume: "50%"
   • Valuta: 'USDD'
2. L'app tenta di applicare le configurazioni. Il volume è impostato correttamente al 50%, ma il codice valuta non è valido e non può essere applicato.
3. In base allo stato di ogni configurazione, l'app imposta uno stato con chiave. Ogni stato dell'app con chiave contiene una chiave univoca e un messaggio con i dettagli dello stato. Se possibile, ti consigliamo di far corrispondere la chiave delle configurazioni gestite. Ecco alcuni esempi:

   Chiave	Messaggio	Gravità	Timestamp
   volume	Impostata al 50%	SEVERITY_INFO	1554461130
   currency	Valuta "USDD" non riconosciuta	SEVERITY_ERROR	1554461130

4. Il provider EMM recupera gli stati dell'app associati alla chiave impostati dall'app e li visualizza nella console EMM. Ecco alcuni esempi:

   Configurazione	Stato	Azione richiesta	Tempo
   Volume	Impostata al 50%	No	5 aprile 2019; 10:45:30
   Valuta	ERRORE: valuta "USDD" non riconosciuta.	Sì	5 aprile 2019; 10:45:30

   Il provider EMM deve inoltre segnalare esplicitamente all'amministratore IT tutti gli stati ricevuti con SEVERITY_ERROR. Gli amministratori IT possono visualizzare le informazioni nella propria console EMM e intervenire per correggere eventuali errori nelle configurazioni che impostano.

Segnala errori risolti

Dopo aver risolto un errore, invia immediatamente uno stato dell'app di follow-up per impedire ai provider EMM di visualizzare il messaggio di errore a tempo indeterminato. Questo stato di follow-up deve includere:

• La stessa chiave del messaggio di errore iniziale.
• Una gravità di SEVERITY_INFO, che indica che lo stato non è in una condizione di errore e non richiede all'organizzazione di intraprendere ulteriori azioni.

Aggiungi alla tua app il supporto per gli stati associati della chiave

I passaggi riportati di seguito descrivono come integrare gli stati con chiave dell'app nella tua app.

Passaggio 1: aggiungi il Repository Maven di Google al tuo file settings.gradle

Aggiungi il Repository Maven di Google come posizione di repository nel file settings.gradle del tuo progetto, come mostrato di seguito:

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

Passaggio 2: aggiungi la libreria di feedback aziendale al file build.gradle a livello di modulo

Aggiungi la dipendenza seguente al file build.gradle a livello di modulo:

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

Passaggio 3: ottieni un'istanza di KeyedAppStatesReporter

Nel metodo onCreate(), recupera e archivia un'istanza di KeyedAppStatesReporter. In questo modo viene attivato un canale di comunicazione tra la tua app e i provider EMM.

Kotlin

val reporter = KeyedAppStatesReporter.create(context)

Java

KeyedAppStatesReporter reporter = KeyedAppStatesReporter.create(context);

Passaggio 4: crea una raccolta di stati dell'app con chiave

Segui le best practice descritte di seguito per la creazione di stati delle app con chiavi:

• Non includere mai informazioni che consentono l'identificazione personale (PII) in uno stato: gli stati delle app con chiave non sono adatti ai dati sensibili.
• Mantieni gli stati dell'app associati entro i limiti definiti in MAX_KEY_LENGTH, MAX_MESSAGE_LENGTH e MAX_DATA_LENGTH.
• Una singola chiamata setStates o setStatesImmediate è limitata a un totale di 300 kB (circa 1/3 del totale archiviabile al giorno). Il superamento di questo limite comporterà un comportamento indefinito.
• Imposta la gravità di uno stato su SEVERITY_ERROR solo se esiste una condizione per la quale un'organizzazione deve intervenire.
• Quando invii un'app che contiene errori, assicurati di inviare anche uno stato di follow-up quando gli errori sono stati risolti, in modo che l'EMM possa smettere di segnalare gli errori nella propria console.
• Per lo stato di follow-up, utilizza la stessa chiave dello stato iniziale che ha restituito l'errore e imposta la gravità su SEVERITY_INFO.

Lo snippet riportato di seguito crea una raccolta di stati dell'app con chiave:

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

Passaggio 5: imposta gli stati dell'app associati alla chiave

Nota: puoi configurare fino a 500 chiavi univoche al giorno per la tua app. Non esiste alcun limite al numero di stati che puoi impostare per ogni chiave univoca.

Il metodo setStates() invia immediatamente gli stati dell'app associati alla chiave all'app Play Store (nome del pacchetto: com.android.vending) se è installata sul dispositivo, nonché a eventuali amministratori del dispositivo o del profilo di lavoro.

Kotlin

keyedAppStatesReporter.setStates(states)

Java

keyedAppStatesReporter.setStates(states);

Testa gli stati dell'app con chiave

Per istruzioni dettagliate sul test, vedi Testare il feedback dell'app.