Segnalazione avanzata con Engagement SDK per le app di Windows universaliAdvanced Reporting with the Windows Universal Apps Engagement SDK

Questo argomento descrive scenari di segnalazione aggiuntivi nell'applicazione di Windows universale.This topic describes additional reporting scenarios in your Windows Universal application. Questi scenari includono le opzioni che è possibile scegliere di applicare all'app creata nell'esercitazione introduttiva .These scenarios include options that you can choose to apply to the app created in the Getting Started tutorial.

PrerequisitiPrerequisites

Per completare questa esercitazione, è necessario disporre di:This tutorial requires the following:

Nota

Per completare l'esercitazione, è necessario disporre di un account Azure attivo.To complete this tutorial, you must have an active Azure account. Se non si dispone di un account, è possibile creare un account di valutazione gratuita in pochi minuti.If you don't have an account, you can create a free trial account in just a couple of minutes. Per informazioni dettagliate, vedere la pagina relativa alla versione di valutazione gratuita di Azure.For details, see Azure Free Trial.

Prima di iniziare questa esercitazione, è necessario completare l'esercitazione introduttiva che è intenzionalmente diretta e semplice .Before starting this tutorial, you must first complete the Getting Started tutorial, which is deliberately direct and simple. Questa esercitazione illustra le opzioni aggiuntive disponibili.This tutorial covers additional options you can choose from.

Specifica della configurazione di Engagement in fase di esecuzioneSpecifying engagement configuration at runtime

La configurazione di Engagement è centralizzata nel file Resources\EngagementConfiguration.xml del progetto, ovvero quello in cui è stata specificata nell'argomento introduttivo .The Engagement configuration is centralized in the Resources\EngagementConfiguration.xml file of your project, which is where it was specified in the Getting Started topic.

Se si vuole specificarlo in fase di esecuzione, è possibile chiamare il metodo seguente prima dell'inizializzazione dell'agente di Engagement:But you can also specify it at runtime: you can call the following method before the Engagement agent initialization:

      /* Engagement configuration. */
      EngagementConfiguration engagementConfiguration = new EngagementConfiguration();

      /* Set the Engagement connection string. */
      engagementConfiguration.Agent.ConnectionString = "Endpoint={appCollection}.{domain};AppId={appId};SdkKey={sdkKey}";

      /* Initialize Engagement angent with above configuration. */
      EngagementAgent.Instance.Init(e, engagementConfiguration);

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

Di seguito è riportato un esempio per una pagina dell'applicazione.Here is an example 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 Page con EngagementPage:Replace Page with EngagementPage:

Senza Engagement:Without Engagement:

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

Con Engagement:With Engagement:

    using Microsoft.Azure.Engagement;

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

Importante

Se la pagina esegue l'override del metodo OnNavigatedTo, accertarsi di chiamare base.OnNavigatedTo(e). In caso contrario, l'attività non verrà segnalata, ovvero EngagementPage chiama StartActivity all'interno del relativo metodo OnNavigatedTo.

File XAMLXAML file

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

  • Aggiungere le dichiarazioni di spazi dei nomi:Add to your namespaces declarations:

    xmlns:engagement="using:Microsoft.Azure.Engagement"
    
  • Sostituire Page con engagement:EngagementPage:Replace Page with engagement:EngagementPage:

Senza Engagement:Without Engagement:

    <Page>
        <!-- layout -->
        ...
    </Page>

Con Engagement:With Engagement:

    <engagement:EngagementPage
        xmlns:engagement="using:Microsoft.Azure.Engagement">
        <!-- layout -->
        ...
    </engagement:EngagementPage >

Eseguire l'override del comportamento predefinitoOverride the default behaviour

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à questo elemento.If the class uses the "Page" suffix, Engagement removes it.

Per sostituire il comportamento predefinito per il nome, aggiungere il codice seguente:To override the default behavior for the name, add this code:

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

Per segnalare informazioni aggiuntive con l'attività, aggiungere il codice seguente:To report extra information with your activity, add this 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 Page, in alternativa è possibile avviare le attività chiamando direttamente i metodi EngagementAgent.If you cannot or do not want to overload your Page classes, you can instead start your activities by calling EngagementAgent methods directly.

È consigliabile chiamare StartActivity all'interno del metodo OnNavigatedTo della pagina.We recommend calling StartActivity inside your OnNavigatedTo method of your Page.

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

Importante

Assicurarsi che la sessione venga terminata correttamente.

Windows Universal SDK chiama automaticamente il metodo EndActivity quando l'applicazione viene chiusa. È quindi ALTAMENTE consigliabile chiamare il metodo StartActivity ogni volta che l'attività dell'utente cambia e non chiamare MAI il metodo EndActivity. Questo metodo notifica al server di Engagement 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 use of all Engagement's advanced capabilities.

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