Come integrare Engagement in AndroidHow to Integrate Engagement on Android

Questa procedura descrive il modo più semplice per attivare le funzioni di analisi e monitoraggio di Engagement in un'applicazione per Android.This procedure describes the simplest way to activate Engagement's Analytics and Monitoring functions in your Android application.

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).

I passaggi seguenti sono sufficienti per attivare la segnalazione dei log necessari per calcolare tutte le statistiche relative a utenti, sessioni, attività, arresti anomali del sistema e dati tecnici.The following steps are enough to activates the report of logs needed to compute all statistics regarding Users, Sessions, Activities, Crashes and Technicals. La segnalazione dei log necessari per calcolare altre statistiche quali eventi, errori e processi deve essere eseguita manualmente mediante l'API di Engagement (vedere Come usare l'API di Engagement in Android ) poiché queste statistiche dipendono dall'applicazione.The report of logs needed to compute other statistics like Events, Errors and Jobs must be done manually using the Engagement API (see How to use the advanced Mobile Engagement tagging API in your Android since these statistics are application dependent.

Incorporare il servizio ed Engagement SDK nel progetto AndroidEmbed the Engagement SDK and service into your Android project

Android SDK è disponibile quilibs per il download. Ottenere il file e inserirlo nella cartella mobile-engagement-VERSION.jar del progetto Android. Creare la cartella libs, se non esiste ancora.Download the Android SDK from here Get mobile-engagement-VERSION.jar and put them into the libs folder of your Android project (create the libs folder if it does not exist yet).

Importante

Se si compila il pacchetto dell'applicazione con ProGuard, è necessario mantenere alcune classi.If you build your application package with ProGuard, you need to keep some classes. È possibile usare il frammento di codice di configurazione seguente:You can use the following configuration snippet:

-keep public class * extends android.os.IInterface -keep class com.microsoft.azure.engagement.reach.activity.EngagementWebAnnouncementActivity$EngagementReachContentJS {-keep public class * extends android.os.IInterface -keep class com.microsoft.azure.engagement.reach.activity.EngagementWebAnnouncementActivity$EngagementReachContentJS {

; }; }

Specificare la stringa di connessione a Engagement chiamando il metodo seguente nell'attività dell'utilità di avvio:Specify your Engagement connection string by calling the following method in the launcher activity:

        EngagementConfiguration engagementConfiguration = new EngagementConfiguration();
        engagementConfiguration.setConnectionString("Endpoint={appCollection}.{domain};AppId={appId};SdkKey={sdkKey}");
        EngagementAgent.getInstance(this).init(engagementConfiguration);

La stringa di connessione per l'applicazione viene visualizzata nel portale di Azure.The connection string for your application is displayed on Azure Portal.

  • Aggiungere le autorizzazioni Android seguenti, se mancanti, prima del tag <application>:If missing, add the following Android permissions (before the <application> tag):

        <uses-permission android:name="android.permission.INTERNET"/>
        <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    
  • Aggiungere la sezione seguente tra i tag <application> e </application>:Add the following section (between the <application> and </application> tags):

        <service
          android:name="com.microsoft.azure.engagement.service.EngagementService"
          android:exported="false"
          android:label="<Your application name>Service"
          android:process=":Engagement"/>
    
  • Al posto di <Your application name> specificare il nome dell'applicazione.Change <Your application name> by the name of your application.

Suggerimento

La chiave android:label consente di scegliere il nome del servizio Engagement così come verrà presentato agli utenti finali nella schermata dei servizi in esecuzione sul telefono.The android:label attribute allows you to choose the name of the Engagement service as it will appear to the end-users in the "Running services" screen of their phone. È consigliabile impostare questo attributo su "<Your application name>Service", ad esempio "AcmeFunGameService".It is recommended to set this attribute to "<Your application name>Service" (e.g. "AcmeFunGameService").

Se si specifica l'attributo android:process , il servizio Engagement verrà eseguito nel relativo processo (l'esecuzione di Engagement nello stesso processo dell'applicazione può ridurre la reattività del thread principale o dell'interfaccia utente).Specifying the android:process attribute ensures that the Engagement service will run in its own process (running Engagement in the same process as your application will make your main/UI thread potentially less responsive).

Nota

Il codice inserito in Application.onCreate() e altri callback dell'applicazione verrà eseguito per tutti i processi dell'applicazione, incluso il servizio Engagement.Any code you place in Application.onCreate() and other application callbacks will be run for all your application's processes, including the Engagement service. È possibile che si verifichino effetti collaterali indesiderati, ad esempio allocazioni di memoria e thread superflui nel processo di Engagement oppure ricevitori o servizi di trasmissione duplicati.It may have unwanted side effects (like unneeded memory allocations and threads in the Engagement's process, duplicate broadcast receivers or services).

Se si esegue l'override di Application.onCreate(), è consigliabile aggiungere il frammento di codice seguente all'inizio della funzione Application.onCreate():If you override Application.onCreate(), it's recommended to add the following code snippet at the beginning of your Application.onCreate() function:

         public void onCreate()
         {
           if (EngagementAgentUtils.isInDedicatedEngagementProcess(this))
             return;

           ... Your code...
         }

È possibile eseguire la stessa operazione per Application.onTerminate(), Application.onLowMemory() e Application.onConfigurationChanged(...).You can do the same thing for Application.onTerminate(), Application.onLowMemory() and Application.onConfigurationChanged(...).

È anche possibile estendere EngagementApplication anziché Application: il callback esegue il controllo del processo Application.onCreate() e chiama Application.onApplicationProcessCreate() solo se il processo corrente non è quello che ospita il servizio Engagement. Per gli altri callback vengono applicate le stesse regole.You can also extend EngagementApplication instead of extending Application: the callback Application.onCreate() does the process check and calls Application.onApplicationProcessCreate() only if the current process is not the one hosting the Engagement service, the same rules apply for the other callbacks.

Segnalazione di baseBasic reporting

Per attivare la segnalazione di tutti i log richiesti da Engagement per il calcolo delle statistiche relative a utenti, sessioni, attività, arresti anomali del sistema e dati tecnici, è sufficiente fare in modo che tutte le sottoclassi *Activity ereditino dalle classi Engagement*Activity corrispondenti. Ad esempio, se l'attività legacy estende ListActivity, fare in modo che estenda EngagementListActivity.In order to activate the report of all the logs required by Engagement to compute Users, Sessions, Activities, Crashes and Technical statistics, you just have to make all your *Activity sub-classes inherit from the corresponding Engagement*Activity classes (e.g. if your legacy activity extends ListActivity, make it extends EngagementListActivity).

Senza Engagement:Without Engagement :

        package com.company.myapp;

        import android.app.Activity;
        import android.os.Bundle;

        public class MyApp extends Activity
        {
          @Override
          public void onCreate(Bundle savedInstanceState)
          {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.main);
          }
        }

Con Engagement:With Engagement :

        package com.company.myapp;

        import com.microsoft.azure.engagement.activity.EngagementActivity;
        import android.os.Bundle;

        public class MyApp extends EngagementActivity
        {
          @Override
          public void onCreate(Bundle savedInstanceState)
          {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.main);
          }
        }

Importante

Quando si usa EngagementListActivity o EngagementExpandableListActivity, assicurarsi che tutte le chiamate a requestWindowFeature(...); vengano eseguite prima della chiamata a super.onCreate(...);. In caso contrario, si verificherà un arresto anomalo del sistema.When using EngagementListActivity or EngagementExpandableListActivity, make sure any call to requestWindowFeature(...); is made before the call to super.onCreate(...);, otherwise a crash will occur.

Queste classi sono incluse nella cartella src e possono essere copiate nel progetto.You can find these classes in the src folder, and can copy them into your project. Sono reperibili anche in JavaDoc.The classes are also in the JavaDoc.

Metodo alternativo: chiamare manualmente startActivity() e endActivity()Alternate method: call startActivity() and endActivity() manually

Se non si può o non si vuole eseguire l'overload delle classi Activity, è possibile avviare e terminare le attività chiamando direttamente i metodi di EngagementAgent.If you cannot or do not want to overload your Activity classes, you can instead start and end your activities by calling EngagementAgent's methods directly.

Importante

Android SDK non chiama mai il metodo endActivity(), neanche alla chiusura dell'applicazione (in Android le applicazioni in realtà non vengono mai chiuse).The Android SDK never calls the endActivity() method, even when the application is closed (on Android, applications are actually never closed). Per questo motivo, è ALTAMENTE consigliabile chiamare il metodo startActivity() nel callback onResume di TUTTE le attività e il metodo endActivity() nel callback onPause() di TUTTE le attività.Thus, it is HIGHLY recommended to call the startActivity() method in the onResume callback of ALL your activities, and the endActivity() method in the onPause() callback of ALL your activities. È l'unico modo per evitare la perdita di sessioni.This is the only way to be sure that sessions will not be leaked. In caso di perdita di una sessione, il servizio Engagement non si disconnetterà mai dal back-end di Engagement, dato che il servizio rimane connesso fintanto che una sessione è in sospeso.If a session is leaked, the Engagement service will never disconnect from the Engagement backend (since the service stays connected as long as a session is pending).

Di seguito è fornito un esempio:Here is an example:

        public class MyActivity extends Some3rdPartyActivity
        {
          @Override
          protected void onResume()
          {
            super.onResume();
            String activityNameOnEngagement = EngagementAgentUtils.buildEngagementActivityName(getClass()); // Uses short class name and removes "Activity" at the end.
            EngagementAgent.getInstance(this).startActivity(this, activityNameOnEngagement, null);
          }

          @Override
          protected void onPause()
          {
            super.onPause();
            EngagementAgent.getInstance(this).endActivity();
          }
        }

Questo esempio è molto simile alla classe EngagementActivity e alle relative varianti, il cui codice di origine è disponibile nella cartella src.This example very similiar to the EngagementActivity class and its variants, whose source code is provided in the src folder.

TestTest

Verificare ora l'integrazione, eseguendo l'app per dispositivi mobili in un emulatore o in un dispositivo e verificando che registri una sessione nella scheda Monitoraggio.Now please verify your integration by running your mobile app in an emulator or device and verifying that it registers a session on the Monitor tab.

Le sezioni successive sono facoltative.The next sections are optional.

Segnalazione della posizioneLocation reporting

Per fare in modo che le posizioni vengano segnalate, è necessario aggiungere alcune righe di configurazione tra i tag <application> e </application>.If you want locations to be reported, you need to add a few lines of configuration (between the <application> and </application> tags).

Segnalazione differita della posizioneLazy area location reporting

La segnalazione differita della posizione consente di segnalare il paese, l'area geografica e la località associati ai dispositivi.Lazy area location reporting allows to report the country, region and locality associated to devices. Questo tipo di segnalazione della posizione usa solo le posizioni di rete, sulla base dell'ID di cella o della connessione Wi-Fi.This type of location reporting only uses network locations (based on Cell ID or WIFI). L'area del dispositivo viene segnalata al massimo una volta per sessione.The device area is reported at most once per session. Il GPS non viene mai usato, per cui l'impatto di questo tipo di segnalazione della posizione sulla batteria è minimo, se non addirittura nullo.The GPS is never used, and thus this type of location report has very few (not to say no) impact on the battery.

Le aree segnalate vengono usate per calcolare statistiche geografiche relative a utenti, sessioni, eventi ed errori.Reported areas are used to compute geographic statistics about users, sessions, events and errors. Possono essere usate anche come criteri nelle campagne Reach.They can also be used as criterion in Reach campaigns.

Per abilitare la segnalazione differita della posizione, è possibile utilizzare la configurazione descritta in precedenza in questa procedura:To enable lazy area location reporting, you can do it by using the configuration previously mentioned in this procedure :

EngagementConfiguration engagementConfiguration = new EngagementConfiguration();
engagementConfiguration.setConnectionString("Endpoint={appCollection}.{domain};AppId={appId};SdkKey={sdkKey}");
engagementConfiguration.setLazyAreaLocationReport(true);
EngagementAgent.getInstance(this).init(engagementConfiguration);

È necessario aggiungere anche le autorizzazioni seguenti, se mancanti:You also need to add the following permission if missing:

        <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>

Oppure è possibile continuare a utilizzare ACCESS_FINE_LOCATION se è già utilizzato nell'applicazione.Or you can keep using ACCESS_FINE_LOCATION if you already use it in your application.

Segnalazione della posizione in tempo realeReal time location reporting

La segnalazione della posizione in tempo reale consente di segnalare la latitudine e la longitudine associate ai dispositivi.Real time location reporting allows to report the latitude and longitude associated to devices. Per impostazione predefinita, la segnalazione differita della posizione usa solo posizioni di rete (in base all'ID di cella o alla connessione Wi-Fi) ed è attiva solo quando l'applicazione viene eseguita in primo piano, ad esempio durante una sessione.By default, this type of location reporting only uses network locations (based on Cell ID or WIFI), and the reporting is only active when the application runs in foreground (i.e. during a session).

Le posizioni in tempo reale NON sono usate per calcolare dati statistici.Real time locations are NOT used to compute statistics. L'unico scopo è consentire l'uso del criterio di definizione del recinto virtuale in tempo reale <Reach-Audience-geofencing> nelle campagne di copertura.Their only purpose is to allow the use of real time geo-fencing <Reach-Audience-geofencing> criterion in Reach campaigns.

Per abilitare la segnalazione della posizione in tempo reale, è possibile utilizzare la configurazione descritta in precedenza in questa procedura:To enable real time location reporting, you can do it by using the configuration previously mentioned in this procedure :

EngagementConfiguration engagementConfiguration = new EngagementConfiguration();
engagementConfiguration.setConnectionString("Endpoint={appCollection}.{domain};AppId={appId};SdkKey={sdkKey}");
engagementConfiguration.setRealtimeLocationReport(true);
EngagementAgent.getInstance(this).init(engagementConfiguration);

È necessario aggiungere anche le autorizzazioni seguenti, se mancanti:You also need to add the following permission if missing:

        <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>

Oppure è possibile continuare a utilizzare ACCESS_FINE_LOCATION se è già utilizzato nell'applicazione.Or you can keep using ACCESS_FINE_LOCATION if you already use it in your application.

Segnalazione basata su GPSGPS based reporting

Per impostazione predefinita, la segnalazione della posizione in tempo reale usa solo posizioni di rete.By default, real time location reporting only uses network based locations. Per abilitare l'uso di posizioni basate su GPS (che sono molto più precise), utilizzare l’oggetto di configurazione:To enable the use of GPS based locations (which are far more precise), use the configuration object:

EngagementConfiguration engagementConfiguration = new EngagementConfiguration();
engagementConfiguration.setConnectionString("Endpoint={appCollection}.{domain};AppId={appId};SdkKey={sdkKey}");
engagementConfiguration.setRealtimeLocationReport(true);
engagementConfiguration.setFineRealtimeLocationReport(true);
EngagementAgent.getInstance(this).init(engagementConfiguration);

È necessario aggiungere anche le autorizzazioni seguenti, se mancanti:You also need to add the following permission if missing:

        <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

Segnalazione in backgroundBackground reporting

Per impostazione predefinita, la segnalazione della posizione in tempo reale è attiva solo quando l'applicazione viene eseguita in primo piano, ad esempio durante una sessione.By default, real time location reporting is only active when the application runs in foreground (i.e. during a session). Per abilitare la segnalazione anche in background, utilizzare l’oggetto di configurazione:To enable the reporting also in background, use the configuration object:

EngagementConfiguration engagementConfiguration = new EngagementConfiguration();
engagementConfiguration.setConnectionString("Endpoint={appCollection}.{domain};AppId={appId};SdkKey={sdkKey}");
engagementConfiguration.setRealtimeLocationReport(true);
engagementConfiguration.setBackgroundRealtimeLocationReport(true);
EngagementAgent.getInstance(this).init(engagementConfiguration);

Nota

Quando l'applicazione viene eseguita in background, vengono segnalate solo le posizioni basate sulla rete, anche se è abilitato il GPS.When the application runs in background, only network based locations are reported, even if you enabled the GPS.

La segnalazione della posizione in background verrà arrestata se l'utente riavvia il dispositivo. Per fare in modo che venga riavviata automaticamente al riavvio, aggiungere quanto segue:The background location report will be stopped if the user reboots its device, you can add this to make it automatically restart at boot time:

        <receiver android:name="com.microsoft.azure.engagement.EngagementLocationBootReceiver"
           android:exported="false">
           <intent-filter>
              <action android:name="android.intent.action.BOOT_COMPLETED" />
           </intent-filter>
        </receiver>

È necessario aggiungere anche le autorizzazioni seguenti, se mancanti:You also need to add the following permission if missing:

        <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

Autorizzazioni Android MAndroid M permissions

A partire da Android M, alcune autorizzazioni vengono gestite in fase di esecuzione e richiedono l'approvazione dell'utente.Starting with Android M, some permissions are managed at runtime and needs user approval.

Le autorizzazioni di runtime verranno disattivate per impostazione predefinita per le installazioni di nuove app se la destinazione è il livello 23 dell’API Android.The runtime permissions will be turned off by default for new app installations if you target Android API level 23. In caso contrario verranno attivate per impostazione predefinita.Otherwise it will be turned on by default.

L'utente può abilitare o disabilitare le autorizzazioni dal menu delle impostazioni del dispositivo.The user can enable/disable those permissions from the device settings menu. La disattivazione delle autorizzazioni dal menu di sistema elimina i processi in background dell'applicazione; si tratta di un comportamento del sistema e non influisce sulla possibilità di ricevere push in background.Turning off permissions from system menu kills background processes of the application, this is a system behavior and has no impact on ability to receive push in background.

Nel contesto di Mobile Engagement, le autorizzazioni che richiedono l'approvazione al runtime sono:In the context of Mobile Engagement, the permissions that require approval at runtime are:

  • ACCESS_COARSE_LOCATION
  • ACCESS_FINE_LOCATION
  • WRITE_EXTERNAL_STORAGE (solo quando la destinazione è il livello 23 dell’API Android)WRITE_EXTERNAL_STORAGE (only when targeting Android API level 23 for this one)

L’archiviazione esterna viene utilizzata solo per la funzionalità della panoramica generale Reach.The external storage is used only for Reach big picture feature. Se si ritiene che richiedere agli utenti questa autorizzazione sia problematico, è possibile rimuoverla se è stata utilizzata solo per Mobile Engagement, ma comporta la disattivazione delle funzionalità della panoramica generale.If you find asking users this permission to be disruptive, you can remove it if you used it only for Mobile Engagement but at the cost of disabling big picture feature.

Per le funzionalità del percorso, è necessario richiedere le autorizzazioni all'utente tramite una finestra di dialogo di sistema standard.For the location features, you should request permissions to user using a standard system dialog. Se l'utente approva, è necessario specificare EngagementAgent per tenere in considerazione la modifica in tempo reale (in caso contrario la modifica verrà elaborata la volta successiva che l'utente avvia l'applicazione).If the user approves, you need to tell EngagementAgent to take that change into account in real time (otherwise the change will be processed the next time the user launches the application).

Ecco un esempio di codice da utilizzare in un'attività dell'applicazione per richiedere autorizzazioni e inoltrare il risultato, se positivo, a EngagementAgent:Here is a code sample to use in an activity of your application to request permissions and forward the result if positive to EngagementAgent:

@Override
public void onCreate(Bundle savedInstanceState)
{
  /* Other code... */

  /* Request permissions */
  requestPermissions();
}

@TargetApi(Build.VERSION_CODES.M)
private void requestPermissions()
{
  /* Avoid crashing if not on Android M */
  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M)
  {
    /*
     * Request location permission, but this won't explain why it is needed to the user.
     * The standard Android documentation explains with more details how to display a rationale activity to explain the user why the permission is needed in your application.
     * Putting COARSE vs FINE has no impact here, they are part of the same group for runtime permission management.
     */
    if (checkSelfPermission(android.Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED)
      requestPermissions(new String[] { android.Manifest.permission.ACCESS_FINE_LOCATION }, 0);

    /* Only if you want to keep features using external storage */
    if (checkSelfPermission(android.Manifest.permission.WRITE_EXTERNAL_STORAGE) != PackageManager.PERMISSION_GRANTED)
      requestPermissions(new String[] { android.Manifest.permission.WRITE_EXTERNAL_STORAGE }, 1);
  }
}

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults)
{
  /* Only a positive location permission update requires engagement agent refresh, hence the request code matching from above function */
  if (requestCode == 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED)
    getEngagementAgent().refreshPermissions();
}

Segnalazione avanzataAdvanced reporting

Facoltativamente, per segnalare eventi, errori e processi specifici dell'applicazione, è necessario usare l'API di Engagement mediante i metodi della classe EngagementAgent .Optionally, if you want to report application specific events, errors and jobs, you need to use the Engagement API through the methods of the EngagementAgent class. Un oggetto di questa classe può essere recuperato chiamando il metodo statico EngagementAgent.getInstance() .An object of this class can be retreived by calling the EngagementAgent.getInstance() static method.

L'API di Engagement consente di usare tutte le funzionalità avanzate di Engagement ed è descritta in dettaglio nell'argomento dedicato all'uso dell'API in Android, oltre che nella documentazione tecnica relativa alla classe EngagementAgent .The Engagement API allows to use all of Engagement's advanced capabilities and is detailed in the How to Use the Engagement API on Android (as well as in the technical documentation of the EngagementAgent class).

Configurazione avanzata (in AndroidManifest.xml)Advanced configuration (in AndroidManifest.xml)

WakelockingWake locks

Per assicurarsi che le statistiche vengano inviate in tempo reale quando si usa una connessione Wi-Fi o quando lo schermo è spento, aggiungere la seguente autorizzazione facoltativa:If you want to be sure that statistics are sent in real time when using Wifi or when the screen is off, add the following optional permission:

        <uses-permission android:name="android.permission.WAKE_LOCK"/>

Segnalazione di arresto anomalo Crash report

Per disabilitare la segnalazione di arresti anomali del sistema, aggiungere quanto segue tra i tag <application> e </application>:If you want to disable crash reports, add this (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 reports logs very frequently, it is better to buffer the logs and to report them all at once on a regular time base (this is called the "burst mode"). A tale scopo, aggiungere quanto segue tra i tag <application> e </application>:To do so, add this (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 verrà arrotondata alla soglia di burst (di conseguenza, le sessioni e i processi inferiori alla soglia di burst potrebbero non essere visibili).The burst mode slightly increase the battery life but has an impact on the Engagement Monitor: all sessions and jobs duration will be rounded to the burst threshold (thus, sessions and jobs shorter than the burst threshold may not be visible). Si consiglia di usare una soglia di burst non maggiore di 30000 (30 secondi).It is recommended to use a burst threshold no longer than 30000 (30s).

Timeout della sessioneSession timeout

Per impostazione predefinita, una sessione viene terminata 10 secondi dopo la fine dell'ultima attività, che in genere si verifica premendo Home o Indietro, impostando l'inattività del telefono o passando a un'altra applicazione.By default, a session is ended 10s after the end of its last activity (which usually occurs by pressing the Home or Back key, by setting the phone idle or by jumping into another application). Questo avviene per evitare una divisione di sessione ogni volta che l'utente esce e rientra nell'applicazione molto rapidamente, come può accadere quando preleva un'immagine, controlla una notifica e così via.This is to avoid a session split each time the user exit and return to the application very quickly (which can happen when he pick up a image, check a notification, etc.). Questo parametro può essere modificato.You may want to modify this parameter. A tale scopo, aggiungere quanto segue tra i tag <application> e </application>:To do so, add this (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 1 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. È consigliabile adottare la stessa modalità usata per PreferenceActivity.The engagement:agent:settings:mode key is used to define the mode of the shared preferences file, you should 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 use 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." />