Come usare l'API di Engagement in AndroidHow to Use the Engagement API on Android

Questo documento è un'aggiunta al documento Opzioni di segnalazione avanzata per Android Mobile Engagement SDK.This document is an add-on to the document Advanced Reporting options for Android Mobile Engagement SDK. Fornisce informazioni approfondite su come usare l'API di Engagement per segnalare le statistiche dell'applicazione.It provides in depth details about how to use the Engagement API to report your application statistics.

Tenere presente che, se si vuole impostare Engagement in modo che segnali solo le sessioni, le attività, gli arresti anomali e i dati tecnici dell'applicazione, la soluzione più semplice consiste nel fare in modo che tutte le sottoclassi Activity ereditino dalla classe EngagementActivity corrispondente.Keep in mind that if you only want Engagement to report your application's sessions, activities, crashes and technical information, then the simplest way is to make all your Activity sub-classes inherit from the corresponding EngagementActivity class.

Se invece si hanno esigenze più complesse, ad esempio se è necessario segnalare eventi, errori e processi specifici dell'applicazione o presentare le attività dell'applicazione in modo diverso rispetto a quello implementato nelle classi EngagementActivity , è necessario usare l'API di Engagement.If you want to do more, for example if you need to report application specific events, errors and jobs, or if you have to report your application's activities in a different way than the one implemented in the EngagementActivity classes, then you need to use the Engagement API.

L'API di Engagement viene fornita dalla classe EngagementAgent .The Engagement API is provided by the EngagementAgent class. Un'istanza di questa classe può essere recuperata chiamando il metodo statico EngagementAgent.getInstance(Context) (tenere presente che l'oggetto EngagementAgent restituito è un singleton).An instance of this class can be retrieved by calling the EngagementAgent.getInstance(Context) static method (note that the EngagementAgent object returned is a singleton).

Concetti relativi a Mobile EngagementEngagement concepts

Le parti seguenti approfondiscono le informazioni contenute nell'articolo Concetti relativi ad Azure Mobile Engagementper la piattaforma Android.The following parts refine the common Mobile Engagement Concepts, for the Android platform.

Session e ActivitySession and Activity

Se l'utente resta inattivo per più di due secondi tra due attività, la sequenza di attività viene divisa in due sessioni distinte.If the user stays more than a few seconds idle between two activities, then his sequence of activities is split in two distinct sessions. Questi pochi secondi vengono chiamati "timeout della sessione".These few seconds are called the "session timeout".

Un'attività è in genere associata a una schermata dell'applicazione, ovvero l'attività inizia quando la schermata viene visualizzata e si arresta quando la schermata viene chiusa. Questo avviene quando Engagement SDK è integrato mediante le classi EngagementActivity.An activity is usually associated with one screen of the application, that is to say the activity starts when the screen is displayed and stops when the screen is closed: this is the case when the Engagement SDK is integrated by using the EngagementActivity classes.

Le attività possono tuttavia essere controllate anche manualmente usando l'API di Engagement.But activities can also be controlled manually by using the Engagement API. In questo modo, è possibile dividere una schermata specifica in diverse parti secondarie per ottenere maggiori dettagli sull'utilizzo della schermata, ad esempio per definire la frequenza e la durata in base alle quali le finestre di dialogo vengono usate all'interno della schermata.This allows to split a given screen in several sub parts to get more details about the usage of this screen (for example to known how often and how long dialogs are used inside this screen).

Segnalazione di attivitàReporting Activities

Importante

Non è necessario segnalare le attività nel modo indicato in questa sezione se si usa la classe EngagementActivity e le sue varianti in base alle istruzioni disponibili nell'articolo relativo all'integrazione di Engagement in Android.You don't need to report activities like described in this section if you are using the EngagementActivity class and its variants as explained in the How to Integrate Engagement on Android document.

L'utente inizia una nuova attivitàUser starts a new Activity

        EngagementAgent.getInstance(this).startActivity(this, "MyUserActivity", null);
        // Passing the current activity is required for Reach to display in-app notifications, passing null will postpone such announcements and polls.

È necessario chiamare startActivity() ogni volta che l'attività dell'utente cambia.You need to call startActivity() each time the user activity changes. La prima chiamata a questa funzione avvia una nuova sessione utente.The first call to this function starts a new user session.

Il punto migliore in cui chiamare questa funzione corrisponde a ogni callback onResume dell'attività.The best place to call this function is on each activity onResume callback.

L'utente termina l'attività correnteUser ends his current Activity

        EngagementAgent.getInstance(this).endActivity();

È necessario chiamare endActivity() almeno una volta quando l'utente termina la sua ultima attività.You need to call endActivity() at least once when the user finishes his last activity. In questo modo, si indica all'SDK di Engagement che l'utente è attualmente inattivo e che la sessione utente deve essere chiusa allo scadere del timeout. Se si chiama startActivity() prima dello scadere del timeout, la sessione viene semplicemente ripresa.This informs the Engagement SDK that the user is currently idle, and that the user session need to be closed once the session timeout will expire (if you call startActivity() before the session timeout expires, the session is simply resumed).

Il punto migliore in cui chiamare questa funzione corrisponde a ogni callback onPause dell'attività.The best place to call this function is on each activity onPause callback.

Segnalazione di eventiReporting Events

Eventi di sessioneSession events

Gli eventi di sessione vengono in genere usati per segnalare le azioni eseguite da un utente durante la sua sessione.Session events are usually used to report the actions performed by a user during his session.

Esempio senza dati aggiuntivi:Example without extra data:

        public MyActivity extends EngagementActivity {
           [...]
           @Override
           public boolean onPrepareOptionsMenu(Menu menu) {
              getEngagementAgent().sendSessionEvent("menu_shown", null);
           }
           [...]
        }

Esempio con dati aggiuntivi:Example with extra data:

        public MyActivity extends EngagementActivity {
          [...]
          @Override
          public boolean onMenuItemSelected(int featureId, MenuItem item) {
            Bundle extras = new Bundle();
            extras.putInt("id", item.getItemId());
            getEngagementAgent().sendSessionEvent("menu_selected", extras);
          }
          [...]
        }

Eventi autonomiStandalone Events

Diversamente dagli eventi di sessione, gli eventi autonomi possono verificarsi all'esterno del contesto di una sessione.Contrary to session events, standalone events can occur outside of the context of a session.

Esempio:Example:

Si supponga di voler segnalare eventi verificatisi all'attivazione di un ricevitore di trasmissione:Suppose you want to report events occurring when a broadcast receiver is triggered:

        /** Triggered by Intent.ACTION_BATTERY_LOW */
        public BatteryLowReceiver extends BroadcastReceiver {
          [...]
          @Override
          public void onReceive(Context context, Intent intent) {
            EngagementAgent.getInstance(context).sendEvent("battery_low", null);
          }
          [...]
        }

Segnalazione di erroriReporting Errors

Errori di sessioneSession errors

Gli errori di sessione vengono in genere usati per segnalare gli errori che hanno impatto sull'utente durante la sua sessione.Session errors are usually used to report the errors impacting the user during his session.

Esempio:Example:

        /** The user has entered invalid data in a form */
        public MyActivity extends EngagementActivity {
          [...]
          public void onMyFormSubmitted(MyForm form) {
            [...]
            /* The user has entered an invalid email address */
            getEngagementAgent().sendSessionError("sign_up_email", null);
            [...]
          }
          [...]
        }

Errori autonomiStandalone errors

Diversamente dagli errori di sessione, gli errori autonomi possono verificarsi all'esterno del contesto di una sessione.Contrary to session errors, standalone errors can occur outside of the context of a session.

Esempio:Example:

L'esempio seguente mostra come segnalare un errore ogni volta che la memoria nel telefono è insufficiente durante l'esecuzione del processo dell'applicazione.The following example shows how to report an error whenever the memory becomes low on the phone while your application process is running.

        public MyApplication extends EngagementApplication {

          @Override
          protected void onApplicationProcessLowMemory() {
            EngagementAgent.getInstance(this).sendError("low_memory", null);
          }
        }

Segnalazione di processiReporting Jobs

EsempioExample

Si supponga di voler segnalare la durata del processo di accesso:Suppose you want to report the duration of your login process:

        [...]
        public void signIn(Context context, ...) {

          /* We need an Android context to call the Engagement API, if you are extending Activity, Service, you can pass "this" */
          EngagementAgent engagementAgent = EngagementAgent.getInstance(context);

          /* Report sign in job has started */
          engagementAgent.startJob("sign_in", null);

          [... sign in ...]

          /* Report sign in job is now ended */
          engagementAgent.endJob("sign_in");
        }
        [...]

Segnalazione di errori durante un processoReport Errors during a Job

Gli errori possono essere correlati a un processo in esecuzione invece che alla sessione utente corrente.Errors can be related to a running job instead of being related to the current user session.

Esempio:Example:

Si supponga di voler segnalare un errore durante il processo di accesso:Suppose you want to report an error during you login process:

[...] public void signIn(Context context, ...) {[...] public void signIn(Context context, ...) {

          /* We need an Android context to call the Engagement API, if you are extending Activity, Service, you can pass "this" */
          EngagementAgent engagementAgent = EngagementAgent.getInstance(context);

          /* Report sign in job has been started */
          engagementAgent.startJob("sign_in", null);

          /* Try to sign in */
          while(true)
            try {
              trySignin();
              break;
            }
            catch(Exception e) {
              /* Report the error to Engagement */
              engagementAgent.sendJobError("sign_in_error", "sign_in", null);

              /* Retry after a moment */
              sleep(2000);
            }
          [...]
          /* Report sign in job is now ended */
          engagementAgent.endJob("sign_in");
        }
        [...]

Segnalazione di eventi durante un processoReporting Events during a job

Gli eventi possono essere correlati a un processo in esecuzione invece che alla sessione utente corrente.Events can be related to a running job instead of being related to the current user session.

Esempio:Example:

Si supponga di disporre di un social network e di usare un processo per segnalare il tempo totale durante il quale l'utente è connesso al server.Suppose we have a social network, and we use a job to report the total time during which the user is connected to the server. Poiché l'utente può restare connesso in background anche quando usa un'altra applicazione o quando il telefono è inattivo, potrebbe non esservi alcuna sessione.The user can stay connected in background even when he's using another application or when the phone is sleeping, so there is no session.

Se l'utente riceve messaggi dagli amici, si tratta di un evento di processo.The user can receive messages from his friends, this is a job event.

        [...]
        public void signin(Context context, ...) {
          [...Sign in code...]
          EngagementAgent.getInstance(context).startJob("connection", null);
        }
        [...]
        public void signout(Context context) {
          [...Sign out code...]
          EngagementAgent.getInstance(context).endJob("connection");
        }
        [...]
        public void onMessageReceived(Context context) {
          [...Notify in status bar...]
          EngagementAgent.getInstance(context).sendJobEvent("message_received", "connection", null);
        }
        [...]

Parametri aggiuntiviExtra parameters

È possibile collegare dati arbitrari a eventi, errori, attività e processi.Arbitrary data can be attached to events, errors, activities and jobs.

Questi dati possono essere strutturati, usando la classe Bundle di Android (in realtà, funziona come i parametri aggiuntivi negli intenti di Android).This data can be structured, it uses Android's Bundle class (actually, it works like extra parameters in Android Intents). Notare che una classe Bundle può contenere matrici o altre istanze Bundle.Note that a Bundle can contain arrays or another Bundle instances.

Importante

Se si inseriscono parametri parcellizzabili o serializzabili, assicurarsi che venga implementato il rispettivo metodo toString() per restituire una stringa leggibile.If you put in parcelable or serializable parameters, make sure their toString() method is implemented to return a human-readable string. Le classi serializzabili che contengono campi non temporanei non serializzabili provocano l'arresto anomalo di Android quando si chiama bundle.putSerializable("key",value);Serializable classes that contain non transient fields that are not serializable will make Android crash when you will call bundle.putSerializable("key",value);

Avviso

Le matrici di tipo sparse non sono supportate nei parametri aggiuntivi, ovvero non vengono serializzate come matrice.Sparse arrays in extra parameters are not supported, that is, it won't be serialized as an array. Prima di usarle nei parametri aggiuntivi, è consigliabile convertirle in matrici standard.You should convert them into standard arrays before using it in extra parameters.

EsempioExample

        Bundle extras = new Bundle();
        extras.putString("video_id", 123);
        extras.putString("ref_click", "http://foobar.com/blog");
        EngagementAgent.getInstance(context).sendEvent("video_clicked", extras);

LimitiLimits

ChiaviKeys

Ogni chiave in Bundle deve corrispondere all'espressione regolare seguente:Each key in the Bundle must match the following regular expression:

^[a-zA-Z][a-zA-Z_0-9]*

Questo significa che le chiavi devono iniziare con almeno una lettera, seguita da lettere, cifre o caratteri di sottolineatura (_).It means that keys must start with at least one letter, followed by letters, digits or underscores (_).

DimensioneSize

I dati aggiuntivi sono limitati a 1024 caratteri per chiamata, una volta codificati in JSON dal servizio Engagement.Extras are limited to 1024 characters per call (once encoded in JSON by the Engagement service).

Nell'esempio precedente il codice JSON inviato al server è lungo 58 caratteri:In the previous example, the JSON sent to the server is 58 characters long:

        {"ref_click":"http:\/\/foobar.com\/blog","video_id":"123"}

Segnalazione di informazioni sull'applicazioneReporting Application Information

È possibile segnalare manualmente le informazioni di traccia o qualsiasi altra informazione specifica dell'applicazione mediante la funzione sendAppInfo() .You can manually report tracking information (or any other application specific information) using the sendAppInfo() function.

Queste informazioni possono essere inviate in modo incrementale: viene mantenuto solo l'ultimo valore per una determinata chiave per ogni dispositivo specifico.Note that these information can be sent incrementally: only the latest value for a given key will be kept for a given device.

Come per i dati aggiuntivi degli eventi, la classe Bundle viene usata per astrarre le informazioni sull'applicazione. Tenere presente che le matrici o i bundle secondari vengono trattati come stringhe flat (usando la serializzazione JSON).Like event extras, the Bundle class is used to abstract application information, note that arrays or sub-bundles will be treated as flat strings (using JSON serialization).

EsempioExample

Ecco un esempio di codice per inviare il sesso e la data di nascita dell'utente:Here is a code sample to send user gender and birthdate:

        Bundle appInfo = new Bundle();
        appInfo.putString("status", "premium");
        appInfo.putString("expiration", "2016-12-07"); // December 7th 2016
        EngagementAgent.getInstance(context).sendAppInfo(appInfo);

LimitiLimits

ChiaviKeys

Ogni chiave in Bundle deve corrispondere all'espressione regolare seguente:Each key in the Bundle must match the following regular expression:

^[a-zA-Z][a-zA-Z_0-9]*

Questo significa che le chiavi devono iniziare con almeno una lettera, seguita da lettere, cifre o caratteri di sottolineatura (_).It means that keys must start with at least one letter, followed by letters, digits or underscores (_).

DimensioneSize

Le informazioni sull'applicazione sono limitate a 1024 caratteri per chiamata, una volta codificate in JSON dal servizio Engagement.Application information are limited to 1024 characters per call (once encoded in JSON by the Engagement service).

Nell'esempio precedente il codice JSON inviato al server è lungo 44 caratteri:In the previous example, the JSON sent to the server is 44 characters long:

        {"expiration":"2016-12-07","status":"premium"}