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
eSEVERITY_INFO
(valore predefinito). Imposta la gravità suSEVERITY_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.
- 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'
- L'app tenta di applicare le configurazioni. Il volume è impostato correttamente al 50%, ma il codice valuta non è valido e non può essere applicato.
- 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
- 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
eMAX_DATA_LENGTH
. - Una singola chiamata
setStates
osetStatesImmediate
è 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
Collectionstates = 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
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);