Integrazione di Mobile Engagement SDK per Windows Phone SilverlightWindows Phone Silverlight Engagement SDK Integration

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

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 activate 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 Mobile Engagement in Windows Phone Silverlight ) 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 Windows Phone Silverlight app below) since these statistics are application-dependent.

Versioni supportateSupported versions

Mobile Engagement SDK per Windows Silverlight può essere integrato solo nelle applicazioni per:The Mobile Engagement SDK for Windows Silverlight can only be integrated into applications targeting :

  • Windows Phone 8.0Windows Phone 8.0
  • Windows Phone 8.1 SilverlightWindows Phone 8.1 Silverlight

Nota

Se si usa Windows Phone 8.1 (non Silverlight) come piattaforma di destinazione, fare riferimento alla procedura per l'integrazione nelle app universali di Windows.

Installare Mobile Engagement SDK per Windows SilverlightInstall the Mobile Engagement Silverlight SDK

Mobile Engagement SDK per Windows Silverlight è disponibile come pacchetto NuGet denominato MicrosoftAzure.MobileEngagement.The Mobile Engagement SDK for Windows Silverlight is available as a Nuget package called MicrosoftAzure.MobileEngagement. È possibile installarlo da Gestione pacchetti NuGet di Visual Studio.You can install it from the Visual Studio Nuget Package Manager.

Aggiungere le funzionalitàAdd the capabilities

Engagement SDK richiede alcune funzionalità di Windows SDK per funzionare correttamente. richiede alcune funzionalità di Windows Phone Silverlight SDK per funzionare correttamente.The Engagement SDK needs some capabilities of the Windows Phone Silverlight SDK in order to work properly.

Aprire il file WMAppManifest.xml e assicurarsi che le funzionalità seguenti siano dichiarate nel pannello Capabilities:Open your WMAppManifest.xml file and be sure that the following capabilities are declared in the Capabilities panel:

  • ID_CAP_NETWORKING
  • ID_CAP_IDENTITY_DEVICE

Inizializzare Engagement SDKInitialize the Engagement SDK

Configurazione di EngagementEngagement configuration

La configurazione di Engagement è centralizzata nel file Resources\EngagementConfiguration.xml del progetto.The Engagement configuration is centralized in the Resources\EngagementConfiguration.xml file of your project.

Modificare questo file per specificare:Edit this file to specify :

  • La stringa di connessione dell'applicazione tra i tag <connectionString> and <\connectionString>.Your application connection string between tags <connectionString> and <\connectionString>.

Se si desidera specificarla in fase di esecuzione, è possibile chiamare il metodo seguente prima dell'inizializzazione dell'agente di Engagement:If you want to specify it at runtime instead, you can call the following method before the Engagement agent initialization:

/* Engagement configuration. */
EngagementConfiguration engagementConfiguration = new EngagementConfiguration();
engagementConfiguration.Agent.ConnectionString = "Endpoint={appCollection}.{domain};AppId={appId};SdkKey={sdkKey}";

/* Initialize Engagement agent with above configuration. */
EngagementAgent.Instance.Init(engagementConfiguration);

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

Inizializzazione di EngagementEngagement initialization

Quando si crea un nuovo progetto, viene generato un file App.xaml.cs .When you create a new project, a App.xaml.cs file is generated. Questa classe eredita da Application e contiene molti metodi importanti.This class inherits from Application and contains many important methods. Verrà inoltre usata per inizializzare Engagement SDK.It will also be used to initialize the Engagement SDK.

Modificare il file App.xaml.cs:Modify the App.xaml.cs:

  • Aggiungere quanto segue alle istruzioni using:Add to your using statements :

    using Microsoft.Azure.Engagement;
    
  • Inserire EngagementAgent.Instance.Init nel metodo Application_Launching:Insert EngagementAgent.Instance.Init in the Application_Launching method :

    private void Application_Launching(object sender, LaunchingEventArgs e)
    {
      EngagementAgent.Instance.Init();
    }
    
  • Inserire EngagementAgent.Instance.OnActivated nel metodo Application_Activated:Insert EngagementAgent.Instance.OnActivated in the Application_Activated method :

    private void Application_Activated(object sender, ActivatedEventArgs e)
    {
       EngagementAgent.Instance.OnActivated(e);
    }
    

Avviso

È altamente sconsigliata l'aggiunta dell'inizializzazione di Engagement in un altro punto dell'applicazione. Tenere tuttavia presente che il metodo EngagementAgent.Instance.Init viene eseguito in un thread dedicato e non nel thread dell'interfaccia utente.

Segnalazione di baseBasic reporting

Per attivare la segnalazione di tutti i log richiesti da Engagement per calcolare utenti, sessioni, attività, arresti anomali e statistiche tecniche, è possibile fare in modo che tutte le sottoclassi PhoneApplicationPage ereditino dalle classi EngagementPage.In order to activate the report of all the logs required by Engagement to compute Users, Sessions, Activities, Crashes and Technical statistics, you can simply make all your PhoneApplicationPage sub-classes inherit from the EngagementPage classes.

Di seguito è riportato un esempio di come ottenere questo risultato per una pagina dell'applicazione.Here is an example of how to do this for a page of your application. È possibile procedere allo stesso modo per tutte le pagine dell'applicazione.You can do the same thing for all pages of your application.

File di origine C#C# Source file

Modificare il file .xaml.cs della pagina:Modify your page .xaml.cs file :

  • Aggiungere quanto segue alle istruzioni using:Add to your using statements :

    using Microsoft.Azure.Engagement;
    
  • Sostituire PhoneApplicationPage con EngagementPage:Replace PhoneApplicationPage with EngagementPage :

Senza Engagement:Without Engagement:

    namespace Example
    {
      public partial class ExamplePage : PhoneApplicationPage
      {
        [...]
      }
    }

Con Engagement:With Engagement:

    using Microsoft.Azure.Engagement;

    namespace Example
    {
      public partial class ExamplePage : EngagementPage 
      {
        [...]
      }
    }

Avviso

Se la pagina eredita dal metodo OnNavigatedTo, fare attenzione a consentire la chiamata base.OnNavigatedTo(e). In caso contrario, l'attività non verrà segnalata. In effetti, EngagementPage chiama StartActivity all'interno del metodo OnNavigatedTo.

File XAMLXAML file

Modificare il file .xaml della pagina:Modify your page .xaml file :

  • Aggiungere quanto segue alle dichiarazioni di spazi dei nomi:Add to your namespaces declarations :

    xmlns:engagement="clr-namespace:Microsoft.Azure.Engagement;assembly=Microsoft.Azure.Engagement.EngagementAgent.WP"
    
  • Sostituire phone:PhoneApplicationPage con engagement:EngagementPage:Replace phone:PhoneApplicationPage with engagement:EngagementPage :

Senza Engagement:Without Engagement:

    <phone:PhoneApplicationPage>
        <!-- layout -->
    </phone:PhoneApplicationPage>

Con Engagement:With Engagement:

    <engagement:EngagementPage 
        xmlns:engagement="clr-namespace:Microsoft.Azure.Engagement;assembly=Microsoft.Azure.Engagement.EngagementAgent.WP">

        <!-- layout -->
    </engagement:EngagementPage >

Sostituire il comportamento predefinitoOverride the default behavior

Per impostazione predefinita, il nome della classe della pagina viene indicato come nome dell'attività, senza elementi aggiuntivi.By default, the class name of the page is reported as the activity name, with no extra. Se la classe usa il suffisso "Page", Engagement rimuoverà anche questo elemento.If the class uses the "Page" suffix, Engagement will also remove it.

Se si desidera eseguire l'override del comportamento predefinito per il nome, aggiungere quanto segue al codice:If you want to override the default behavior for the name, simply add this to your code:

    // in the .xaml.cs file
    protected override string GetEngagementPageName()
    {
       /* your code */
       return "new name";
    }

Se si desidera segnalare alcune informazioni aggiuntive con l'attività, è possibile aggiungere quanto segue al codice:If you want to report some extra information with your activity, you can add this to your code:

    // in the .xaml.cs file
    protected override Dictionary<object,object> GetEngagementPageExtra()
    {
       /* your code */
       return extra;
    }

Questi metodi vengono chiamati dall'interno del metodo OnNavigatedTo della pagina.These methods are called from within the OnNavigatedTo method of your page.

Metodo alternativo: chiamare StartActivity() manualmenteAlternate method: call StartActivity() manually

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

È consigliabile chiamare StartActivity all'interno del metodo OnNavigatedTo di PhoneApplicationPage.We recommend calling StartActivity inside your OnNavigatedTo method of your PhoneApplicationPage.

    protected override void OnNavigatedTo(NavigationEventArgs e)
    {
       base.OnNavigatedTo(e);
       EngagementAgent.Instance.StartActivity("MyPage");
    }

Importante

Assicurarsi che la sessione venga terminata correttamente.

L'SDK chiama automaticamente il metodo EndActivity quando viene chiusa l'applicazione. È quindi ALTAMENTE consigliabile chiamare il metodo StartActivity ogni volta che l'attività dell'utente cambia e non chiamare MAI il metodo EndActivity. Questo metodo invia un messaggio al server di Engagement che segnala che l'utente ha chiuso l'applicazione e ciò influirà su tutti i log delle applicazioni.

Segnalazione avanzataAdvanced reporting

Facoltativamente, è possibile segnalare eventi specifici dell'applicazione, errori e processi. A tale scopo, usare gli altri metodi disponibili nella classe EngagementAgent.Optionally, you may want to report application specific events, errors and jobs, to do so, use the others methods found in the EngagementAgent class. L'API di Engagement consente di usare tutte le funzionalità avanzate di Engagement.The Engagement API allows to use all of Engagement's advanced capabilities.

Per altre informazioni, vedere Come usare l'API di Engagement in Windows Phone Silverlight.For further information, see How to use the advanced Mobile Engagement tagging API in your Windows Phone Silverlight app.

Configurazione avanzataAdvanced configuration

Disabilitare la segnalazione automatica degli arresti anomaliDisable automatic crash reporting

È possibile disabilitare la funzionalità di segnalazione automatica degli arresti anomali di Engagement.You can disable the automatic crash reporting feature of Engagement. Quindi, quando si verifica un'eccezione non gestita, Engagement non effettuerà alcuna azione.Then, when an unhandled exception will occur, Engagement won't do anything.

Avviso

Se si prevede di disabilitare questa funzionalità, tenere presente che in caso di arresto anomalo non gestito nell'app, Engagement non lo invierà E non chiuderà la sessione e i processi.

Per disabilitare la segnalazione automatica degli arresti anomali, personalizzare la configurazione a seconda del modo in cui è stata dichiarata:To disable automatic crash reporting, just customize your configuration depending on the way you declared it :

Dal file EngagementConfiguration.xmlFrom EngagementConfiguration.xml file

Impostare la segnalazione degli arresti anomali su false tra i tag <reportCrash> e </reportCrash>.Set report crash to false between <reportCrash> and </reportCrash> tags.

Dall'oggetto EngagementConfiguration in fase di esecuzioneFrom EngagementConfiguration object at run time

Impostare la segnalazione degli arresti anomali su false usando l'oggetto EngagementConfiguration.Set report crash to false using your EngagementConfiguration object.

    /* Engagement configuration. */

    EngagementConfiguration engagementConfiguration = new EngagementConfiguration(); engagementConfiguration.Agent.ConnectionString = "Endpoint={appCollection}.{domain};AppId={appId};SdkKey={sdkKey}";
    /\* Disable Engagement crash reporting. \*/ engagementConfiguration.Agent.ReportCrash = false;

Modalità burstBurst mode

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, è consigliabile memorizzarli nel buffer e segnalarli tutti insieme a intervalli regolari (in "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, chiamare il metodo:To do so, call the method:

    EngagementAgent.Instance.SetBurstThreshold(int everyMs);

L'argomento è un valore in millisecondi.The argument is a value in milliseconds. In qualsiasi momento, se si desidera riattivare la registrazione in tempo reale, chiamare il metodo senza alcun parametro o con il valore 0.At any time, if you want to reactivate the real-time logging, just call the method without any parameter, or with the 0 value.

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). Occorre notare che per i log salvati è previsto un limite di 300 elementi.You have to be aware that saved logs are limited to 300 items. Se l'invio richiede troppo tempo, è possibile che alcuni log vadano persi.If sending is too long you can lose some logs.

Avviso

La soglia di burst non può essere configurata per un periodo inferiore a un secondo. Se si tenta di impostare un valore minore, l'SDK mostrerà una traccia con l'errore e verrà ripristinato automaticamente il valore predefinito, ovvero zero secondi. In questo modo verrà attivato l'SDK per la segnalazione dei log in tempo reale.