Come usare l'API di Engagement in Windows Phone SilverlightHow to Use the Engagement API on Windows Phone Silverlight

Questo documento è complementare all'articolo Come integrare Mobile Engagement in un'app per Windows Phone Silverlight.This document is an add-on to the document How to integrate Mobile Engagement in your Windows Phone Silverlight app. 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.

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 PhoneApplicationPage ereditino dalla classe EngagementPage.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 PhoneApplicationPage sub-classes inherit from the EngagementPage 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 EngagementPage, è 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 EngagementPage 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. È possibile accedere a questi metodi tramite EngagementAgent.Instance.You can access to those methods through EngagementAgent.Instance.

Anche se il modulo dell'agente non è stato inizializzato, ogni chiamata all'API viene posticipata e verrà eseguita nuovamente quando l'agente è disponibile.Even if the agent module has not been initialized, each call to the API is deferred, and will be executed again when the agent is available.

Concetti relativi a Mobile EngagementEngagement concepts

Le parti seguenti approfondiscono le informazioni contenute nell'articolo "Concetti relativi ad Azure Mobile Engagement" per la piattaforma Windows Phone.The following parts refine the Mobile Engagement Concepts for the Windows Phone platform.

Session e ActivitySession and Activity

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

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. Ciò consente di dividere una determinata pagina in più sottoparti per ottenere maggiori dettagli sull'utilizzo della pagina (ad esempio per conoscere la frequenza e la durata dell'uso delle finestre di dialogo all'interno della pagina).This allows to split a given page in several sub parts to get more details about the usage of this page (for example to known how often and how long dialogs are used inside this page).

Segnalazione di attivitàReporting Activities

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

riferimentoReference

        void StartActivity(string name, Dictionary<object, object> extras = null)

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

Importante

L'SDK chiama automaticamente il metodo EndActivity quando viene chiusa l'applicazione.The SDK automatically call the EndActivity method when the application is closed. Di conseguenza, è ALTAMENTE consigliato chiamare il metodo StartActivity ogni volta che l'attività dell'utente cambia e non chiamare MAI il metodo EndActivity poiché la chiamata di questo metodo forza la chiusura della sessione corrente.Thus, it is HIGHLY recommended to call the StartActivity method whenever the activity of the user change, and to NEVER call the EndActivity method, since calling this method forces the current session to be ended.

EsempioExample

        EngagementAgent.Instance.StartActivity("main", new Dictionary<object, object>() {{"example", "data"}});

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

riferimentoReference

        void 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 rimane semplicemente attiva.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 continued).

EsempioExample

        EngagementAgent.Instance.EndActivity();

Segnalazione di processiReporting Jobs

Avviare un processoStart a job

riferimentoReference

        void StartJob(string name, Dictionary<object, object> extras = null)

È possibile utilizzare il processo per tenere traccia delle attività in un determinato periodo di tempo.You can use the job to track certains tasks over a period of time.

EsempioExample

        // An upload begins...

        // Set the extras
        var extras = new Dictionary<object, object>();
        extras.Add("title", "avatar");
        extras.Add("type", "image");

        EngagementAgent.Instance.StartJob("uploadData", extras);

Terminare un processoEnd a job

riferimentoReference

        void EndJob(string name)

Appena terminata un'attività di cui un processo tiene traccia, è necessario chiamare il metodo EndJob per questo processo, fornendo il nome del processo.As soon as a task tracked by a job has been terminated, you should call the EndJob method for this job, by supplying the job name.

EsempioExample

        // In the previous section, we started an upload tracking with a job
        // Then, the upload ends

        EngagementAgent.Instance.EndJob("uploadData");

Segnalazione di eventiReporting Events

Esistono tre tipi di eventi:There is three types of events :

  • Eventi autonomiStandalone events
  • Eventi di sessioneSession events
  • Eventi di processoJob events

Eventi autonomiStandalone Events

riferimentoReference

        void SendEvent(string name, Dictionary<object, object> extras = null)

Gli eventi autonomi possono verificarsi all'esterno del contesto di una sessione.Standalone events can occur outside of the context of a session.

EsempioExample

        EngagementAgent.Instance.SendEvent("event", extra);

Eventi di sessioneSession events

riferimentoReference

        void SendSessionEvent(string name, Dictionary<object, object> extras = null)

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.

EsempioExample

Senza dati:Without data :

        EngagementAgent.Instance.SendSessionEvent("sessionEvent");

        // or

        EngagementAgent.Instance.SendSessionEvent("sessionEvent", null);

Con dati:With data :

        Dictionary<object, object> extras = new Dictionary<object,object>();
        extras.Add("name", "data");
        EngagementAgent.Instance.SendSessionEvent("sessionEvent", extras);

Eventi di processoJob Events

riferimentoReference

        void SendJobEvent(string eventName, string jobName, Dictionary<object, object> extras = null)

Gli eventi di processo in genere vengono utilizzati per segnalare le azioni eseguite da un utente durante un processo.Job events are usually used to report the actions performed by a user during a Job.

EsempioExample

        EngagementAgent.Instance.SendJobEvent("eventName", "jobName", extras);

Segnalazione di erroriReporting Errors

Esistono tre tipi di errori:There is three types of errors :

  • Errori autonomiStandalone errors
  • Errori di sessioneSession errors
  • Errori di processoJob errors

Errori autonomiStandalone errors

riferimentoReference

        void SendError(string name, Dictionary<object, object> extras = null)

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.

EsempioExample

        EngagementAgent.Instance.SendError("errorName", extras);

Errori di sessioneSession errors

riferimentoReference

        void SendSessionError(string name, Dictionary<object, object> extras = null)

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.

EsempioExample

        EngagementAgent.Instance.SendSessionError("errorName", extra);

Errori di processoJob Errors

riferimentoReference

        void SendJobError(string errorName, string jobName, Dictionary<object, object> extras = null)

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.

EsempioExample

        EngagementAgent.Instance.SendJobError("errorName", "jobname", extra);

Segnalazione di arresti anomaliReporting Crashes

L'agente fornisce due metodi per gestire gli arresti anomali.The agent provides two methods to deal with crashes.

Inviare un'eccezioneSend an exception

riferimentoReference

        void SendCrash(Exception e, bool terminateSession = false)

EsempioExample

È possibile inviare un'eccezione in qualsiasi momento chiamando:You can send an exception at any time by calling :

        EngagementAgent.Instance.SendCrash(aCatchedException);

È inoltre possibile utilizzare un parametro facoltativo per terminare la sessione di Engagement contemporaneamente all'invio dell'arresto anomalo.You can also use an optional parameter to terminate the engagement session at the same time than sending the crash. A tale scopo, chiamare:To do so, call :

        EngagementAgent.Instance.SendCrash(new Exception("example"), terminateSession: true);

In questo caso la sessione e i processi verranno chiusi solo dopo l'invio dell'arresto anomalo.If you do that, the session and jobs will be closed just after sending the crash.

Inviare un'eccezione non gestitaSend an unhandled exception

riferimentoReference

        void SendCrash(ApplicationUnhandledExceptionEventArgs e)

Engagement fornisce inoltre un metodo per inviare le eccezioni non gestite.Engagement also provides a method to send unhandled exceptions. Questa possibilità è particolarmente utile se utilizzata all'interno del gestore eventi UnhandledException Silverlight.This is especially useful when used inside the silverlight UnhandledException event handler.

Questo metodo terminerà SEMPRE la sessione di Engagement e i processi dopo essere stato chiamato.This method will ALWAYS terminate the engagement session and jobs after being called.

EsempioExample

È possibile utilizzarlo per implementare il proprio gestore UnhandledException (specialmente se è stata disattivata la funzione di segnalazione automatica degli arresti anomali di Engagement).You can use it to implement your own UnhandledException handler (especially if you have disabled the automatic crash reporting feature of Engagement). Ad esempio, nel metodo Application_UnhandledException del file App.xaml.cs:For example, in the Application_UnhandledException method of the App.xaml.cs file :

        // In your App.xaml.cs file

        // Code to execute on Unhandled Exceptions
        private void Application_UnhandledException(object sender, ApplicationUnhandledExceptionEventArgs e)
        {
          // your own code

          EngagementAgent.Instance.SendCrash(e);
        }

OnActivatedOnActivated

riferimentoReference

        void OnActivated(ActivatedEventArgs e)

Quando l'utente procede con la navigazione, lontano da un'applicazione, una volta generato l'evento di disattivazione il sistema operativo tenterà di mettere l'applicazione in stato di inattività.When the user navigates forward, away from an application, after the Deactivated event is raised, the operating system will attempt to put the application into a dormant state. Quindi, l'applicazione viene rimossa definitivamente.Then, the application is Tombstoning. In questo processo viene terminata un'applicazione, ma alcuni dati relativi allo stato dell'applicazione e alle singole pagine all'interno dell'applicazione vengono mantenute.In this process an application is terminated but some data about the state of the application and the individual pages within the application is preserved.

È necessario inserire EngagementAgent.Instance.OnActivated(e) nel metodo Application_Activated dal file App.xaml.cs per reimpostare l'agente di Engagement quando l'applicazione è stata rimossa definitivamente.You have to insert EngagementAgent.Instance.OnActivated(e) in the Application_Activated method from the App.xaml.cs file to reset the Engagement Agent when the application has been Tombstoned.

EsempioExample

        // Inside your App.xaml.cs file

        // Code to execute when the application is activated (brought to foreground)
        // This code will not execute when the application is first launched
        private void Application_Activated(object sender, ActivatedEventArgs e)
        {
          EngagementAgent.Instance.OnActivated(e);
        }

Id dispositivoDevice Id

        String GetDeviceId()

È possibile ottenere l'id del dispositivo Engagement chiamando questo metodo.You can get the engagement device id by calling this method.

Parametri aggiuntiviExtras parameters

Dati arbitrari possono essere collegati a un evento, un errore, un'attività o un processo.Arbitrary data can be attached to an event, an error, an activity or a job. Tali dati possono essere strutturati utilizzando un dizionario.These data can be structured using a dictionary. Chiavi e valori possono essere di qualsiasi tipo.Keys and values can be of any type.

I dati aggiuntivi vengono serializzati, per cui se si desidera inserirvi il proprio tipo è necessario aggiungere un contratto dati per questo tipo.Extras data are serialized so if you want to insert your own type in extras you have to add a data contract for this type.

EsempioExample

Si crea una nuova classe "Person".We create a new class "Person".

        using System.Runtime.Serialization;

        namespace Engagement.Agent
        {
          [DataContract]
          public class Person
          {
            public Person(string name, int age)
            {
              Age = age;
              Name = name;
            }

            // Properties

            [DataMember]
            public int Age
            {
              get;
              set;
            }

            [DataMember]
            public string Name
            {
              get;
              set; 
            }
          }
        }

Quindi, si include un'istanza di Person per un dato aggiuntivo.Then, we will add a Person instance to an extra.

        Person person = new Person("Engagement Haddock", 51);
        var extras = new Dictionary<object, object>();
        extras.Add("people", person);

        EngagementAgent.Instance.SendEvent("Event", extras);

Avviso

Se si inseriscono altri tipi di oggetti, assicurarsi che il relativo metodo ToString() venga implementato per restituire una stringa leggibile.If you put other types of objects, make sure their ToString() method is implemented to return a human readable string.

LimitiLimits

ChiaviKeys

Ogni chiave dell'oggetto deve corrispondere all'espressione regolare seguente:Each key in the object 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, numeri 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.Extras are limited to 1024 characters per call.

Segnalazione di informazioni sull'applicazioneReporting Application Information

riferimentoReference

        void SendAppInfo(Dictionary<object, object> appInfos)

È 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, usare Dictionary<object, object> per allegare informazioni.Like event extras, use a Dictionary<object, object> to attach informations.

EsempioExample

        Dictionary<object, object> appInfo = new Dictionary<object, object>()
        {
           {"subscription", "2013-12-07"},
           {"premium", "true"}
        };

        EngagementAgent.Instance.SendAppInfo(appInfo);

LimitiLimits

ChiaviKeys

Ogni chiave dell'oggetto deve corrispondere all'espressione regolare seguente:Each key in the object 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, numeri 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.Application information are limited to 1024 characters per call.

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:

        {"subscription":"2013-12-07","premium":"true"}

RegistrazioneLogging

Abilitare la registrazioneEnable Logging

È possibile configurare SDK per generare log di test nella console IDE.The SDK can be configured to produce test logs in the IDE console. Questi log non sono abilitati per impostazione predefinita.These logs are not activated by default. Per eseguire una personalizzazione, aggiornare la proprietà EngagementAgent.Instance.TestLogEnabled scegliendo uno dei valori disponibili nell'enumerazione EngagementTestLogLevel, ad esempio:To customize this, update the property EngagementAgent.Instance.TestLogEnabled to one of the value available from the EngagementTestLogLevel enumeration, for instance:

        EngagementAgent.Instance.TestLogLevel = EngagementTestLogLevel.Verbose;
        EngagementAgent.Instance.Init();