Come usare l'API di Engagement in un'app di Windows universaleHow to Use the Engagement API on Windows Universal

Questo documento è complementare all'articolo Come integrare Engagement in un'app di Windows universalee fornisce informazioni approfondite su come usare l'API di Engagement per segnalare le statistiche dell'applicazione.This document is an add-on to the document How to Integrate Engagement on Windows Universal: 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 Page ereditino dalla classe EngagementPage.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 Page 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 universale.The following parts refine the common Mobile Engagement Concepts for the Windows Universal 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'uso della pagina (ad esempio per conoscere la frequenza e la durata dell'uso delle finestre di dialogo all'interno della pagina).This allows you to split a given page in several sub parts to get more details about the usage of this page (for example to know 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 calls 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 changes, 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()

Vengono terminate l'attività e la sessione.This ends the activity and the session. Chiamare questo metodo solo se si è perfettamente consapevoli delle conseguenze.You should not call this method unless you really know what you're doing.

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 errore:There are 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(Exception e)

Engagement fornisce anche un metodo per inviare le eccezioni non gestite, se è stata DISABILITATA la segnalazione automatica degli arresti anomali in Engagement.Engagement also provides a method to send unhandled exceptions if you have DISABLED Engagement automatic crash reporting. Questa possibilità è particolarmente utile se utilizzata all'interno del gestore eventi UnhandledException.This is especially useful when used inside the application 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

Consente di implementare un proprio gestore UnhandledExceptionEventArgs.You can use it to implement your own UnhandledExceptionEventArgs handler. Ad esempio, aggiungere il metodo Current_UnhandledException del file App.xaml.cs:For example, add the Current_UnhandledException method of the App.xaml.cs file :

        // In your App.xaml.cs file

        // Code to execute on Unhandled Exceptions
        void Current_UnhandledException(object sender, UnhandledExceptionEventArgs e)
        {
           EngagementAgent.Instance.SendCrash(e.Exception,false);
        }

In App.xaml.cs in "Public App(){}" aggiungere:In App.xaml.cs in "Public App(){}" add:

        Application.Current.UnhandledException += Current_UnhandledException;

Id dispositivoDevice Id

        String EngagementAgent.Instance.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 Microsoft.Azure.Engagement
        {
          [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.

Questi dati possono essere inviati in modo incrementale: viene mantenuto solo l'ultimo valore per una determinata chiave per ogni dispositivo specifico.Note that this data can be sent incrementally: only the latest value for a given key will be kept for a given device. Come per le informazioni aggiuntive degli eventi, usare Dictionary<object, object> per allegare dati.Like event extras, use a Dictionary<object, object> to attach data.

EsempioExample

        Dictionary<object, object> appInfo = new Dictionary<object, object>()
          {
            {"birthdate", "1983-12-07"},
            {"gender", "female"}
          };

        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 is 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:

        {"birthdate":"1983-12-07","gender":"female"}

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();