Configurazione avanzata di Android SDK per Azure Mobile EngagementAdvanced configuration for Azure Mobile Engagement Android SDK

Questa procedura descrive come configurare le diverse opzioni di configurazione per le app Android di Azure Mobile Engagement.This procedure describes how to configure various configuration options for Azure Mobile Engagement Android apps.

PrerequisitiPrerequisites

Prima di iniziare questa esercitazione, è necessario completare l'esercitazione introduttiva .Before starting this tutorial, you must first complete the Getting Started tutorial.

Importante

L'API di Android SDK deve essere almeno di livello 10 o superiore (Android 2.3.3 o versioni successive).Your minimum Android SDK API level must be 10 or higher (Android 2.3.3 or higher).

Requisiti di autorizzazionePermission Requirements

Alcune opzioni richiedono autorizzazioni specifiche, ognuna delle quali viene elencata di seguito a titolo di riferimento e inline nella funzionalità specifica.Some options require specific permissions, all of which are listed here for reference, and in-line in the specific feature. Aggiungere queste autorizzazioni al file AndroidManifest.xml del progetto immediatamente prima o dopo il tag <application>.Add these permissions to the AndroidManifest.xml of your project immediately before or after the <application> tag.

Il codice di autorizzazione deve essere simile al seguente. L'autorizzazione appropriata viene compilata in base alla tabella seguente.The permission code needs to look like the following, where you fill in the appropriate permission from the table that follows.

<uses-permission android:name="android.permission.[specific permission]"/>
AutorizzazionePermission Quando si usaWhen used
INTERNETINTERNET Obbligatorio.Required. Per report di baseFor basic reporting
ACCESS_NETWORK_STATEACCESS_NETWORK_STATE Obbligatorio.Required. Per report di baseFor basic reporting
RECEIVE_BOOT_COMPLETEDRECEIVE_BOOT_COMPLETED Obbligatorio.Required. Per visualizzare il centro notifiche dopo il riavvio del dispositivoTo show up the notifications center after device reboot
WAKE_LOCKWAKE_LOCK Consigliato.Recommended. Abilita la raccolta dei dati quando si usa il WiFi o quando lo schermo è spentoEnables collecting data when using WiFi or when screen is off
VIBRATEVIBRATE Facoltativo.Optional. Abilita la vibrazione alla ricezione delle notificheEnables vibration when notifications are received
DOWNLOAD_WITHOUT_NOTIFICATIONDOWNLOAD_WITHOUT_NOTIFICATION Facoltativo.Optional. Abilita la notifica generale di AndroidEnables Android Big Picture Notification
WRITE_EXTERNAL_STORAGEWRITE_EXTERNAL_STORAGE Facoltativo.Optional. Abilita la notifica generale di AndroidEnables Android Big Picture Notification
ACCESS_COARSE_LOCATIONACCESS_COARSE_LOCATION Facoltativo.Optional. Abilita la segnalazione della posizione in tempo realeEnables Real-time location reporting
ACCESS_FINE_LOCATIONACCESS_FINE_LOCATION Facoltativo.Optional. Abilita la segnalazione della posizione basata su GPSEnables GPS-based location reporting

A partire da Android M, alcune autorizzazioni vengono gestite in fase di esecuzione.Starting with Android M, some permissions are managed at run time.

Se si usa già ACCESS_FINE_LOCATION non è necessario usare anche ACCESS_COARSE_LOCATION.If you are already using ACCESS_FINE_LOCATION, then you don't need to also use ACCESS_COARSE_LOCATION.

Opzioni di configurazione del file manifesto AndroidAndroid Manifest configuration options

Segnalazione di arresto anomalo Crash report

Per disabilitare la segnalazione di arresti anomali del sistema, aggiungere questo codice tra i tag <application> e </application>:To disable crash reports, add this code between the <application> and </application> tags:

<meta-data android:name="engagement:reportCrash" android:value="false"/>

Soglia del burstBurst threshold

Per impostazione predefinita, il servizio Engagement segnala i log in tempo reale.By default, the Engagement service reports logs in real time. Se l'applicazione segnala i log molto spesso, è preferibile memorizzare i log nel buffer e segnalarli tutti insieme con cadenza regolare, la cosiddetta "modalità burst".If your application report logs vary frequently, it is better to buffer the logs and to report them all at once on a regular time base (called "burst mode"). A tale scopo, aggiungere questo codice tra i tag <application> e </application>:To do so, add this code between the <application> and </application> tags:

<meta-data android:name="engagement:burstThreshold" android:value="{interval between too bursts (in milliseconds)}"/>

La modalità burst aumenta lievemente la durata della batteria ma ha un impatto su Monitor di Engagement: la durata di tutte le sessioni e di tutti i processi viene arrotondata alla soglia di burst e, di conseguenza, le sessioni e i processi inferiori alla soglia di burst potrebbero non essere visibili.Burst mode slightly increases the battery life but has an impact on the Engagement Monitor: all sessions and jobs duration are rounded to the burst threshold (thus, sessions and jobs shorter than the burst threshold may not be visible). La soglia di burst non dovrebbe essere maggiore di 30000 (30 secondi).Your burst threshold should be no longer than 30000 (30s).

Timeout della sessioneSession timeout

È possibile terminare un'attività premendo Home o Indietro, impostando l'inattività del telefono o passando a un'altra applicazione.You can end an activity by pressing the Home or Back key, by setting the phone idle or by jumping into another application. Per impostazione predefinita, una sessione viene terminata 10 secondi dopo la fine dell'ultima attività.By default, a session is ended ten seconds after the end of its last activity. Ciò avviene per evitare una divisione di sessione ogni volta che l'utente esce e rientra nell'applicazione rapidamente, come può accadere quando preleva un'immagine, controlla una notifica e così via. Questo parametro può essere modificato.This avoids a session split each time the user exits and returns to the application quickly, which can happen when the user picks up an image, checks a notification, etc. You may want to modify this parameter. A tale scopo, aggiungere questo codice tra i tag <application> e </application>:To do so, add this code between the <application> and </application> tags:

<meta-data android:name="engagement:sessionTimeout" android:value="{session timeout (in milliseconds)}"/>

Disabilitare la segnalazione di logDisable log reporting

Uso di una chiamata del metodoUsing a method call

Se si vuole che Engagement non invii più log, è possibile chiamare:If you want Engagement to stop sending logs, you can call:

EngagementAgent.getInstance(context).setEnabled(false);

Questa chiamata è persistente: usa un file di preferenze condivise.This call is persistent: it uses a shared preferences file.

Se Engagement è attivo quando si chiama questa funzione, l'arresto del servizio può richiedere 1 minuto.If Engagement is active when you call this function, it may take one minute for the service to stop. Al successivo avvio dell'applicazione, tuttavia, il servizio non verrà avviato.However it won't launch the service at all the next time you launch the application.

È possibile abilitare di nuovo la segnalazione di log chiamando la stessa funzione con true.You can enable log reporting again by calling the same function with true.

Integrazione nella propria classe PreferenceActivityIntegration in your own PreferenceActivity

Invece di chiamare questa funzione, è anche possibile integrare questa impostazione direttamente nella classe PreferenceActivity esistente.Instead of calling this function, you can also integrate this setting directly in your existing PreferenceActivity.

È possibile configurare Engagement in modo da usare il file di preferenze (con la modalità desiderata) nel file AndroidManifest.xml con application meta-data:You can configure Engagement to use your preferences file (with the desired mode) in the AndroidManifest.xml file with application meta-data:

  • La chiave engagement:agent:settings:name viene usata per definire il nome del file di preferenze condivise.The engagement:agent:settings:name key is used to define the name of the shared preferences file.
  • La chiave engagement:agent:settings:mode viene usata per definire la modalità del file di preferenze condivise.The engagement:agent:settings:mode key is used to define the mode of the shared preferences file. Usare la stessa modalità usata per PreferenceActivity.Use the same mode as in your PreferenceActivity. La modalità deve essere passata come numero: se si usa una combinazione di flag di costanti nel codice, controllare il valore totale.The mode must be passed as a number: if you are using a combination of constant flags in your code, check the total value.

Engagement usa sempre la chiave booleana engagement:key all'interno del file di preferenze per la gestione di questa impostazione.Engagement always uses the engagement:key boolean key within the preferences file for managing this setting.

L'esempio seguente di AndroidManifest.xml mostra i valori predefiniti:The following example of AndroidManifest.xml shows the default values:

<application>
    [...]
    <meta-data
      android:name="engagement:agent:settings:name"
      android:value="engagement.agent" />
    <meta-data
      android:name="engagement:agent:settings:mode"
      android:value="0" />

Sarà quindi possibile aggiungere un elemento CheckBoxPreference nel layout delle preferenze simile a quello riportato di seguito:Then you can add a CheckBoxPreference in your preference layout like the following one:

<CheckBoxPreference
  android:key="engagement:enabled"
  android:defaultValue="true"
  android:title="Use Engagement"
  android:summaryOn="Engagement is enabled."
  android:summaryOff="Engagement is disabled." />