Integrazione di Engagement SDK per app universali di WindowsWindows Universal Apps Engagement SDK Integration

Questa procedura descrive il modo più semplice per attivare le funzioni di analisi e monitoraggio di Engagement in un'applicazione universale di Windows.This procedure describes the simplest way to activate Engagement's Analytics and Monitoring functions in your Windows Universal 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 Engagement in un'app universale di Windows ) 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 Universal app since these statistics are application dependent.

Versioni supportateSupported versions

Mobile Engagement SDK per app universali di Windows può essere integrato solo nelle applicazioni Windows Runtime e UWP (Universal Windows Platform) per:The Mobile Engagement SDK for Windows Universal Apps can only be integrated into Windows Runtime and Universal Windows Platform applications targeting :

  • Windows 8Windows 8
  • Windows 8.1Windows 8.1
  • Windows Phone 8.1Windows Phone 8.1
  • Windows 10 (versioni per desktop e portatili)Windows 10 (desktop and mobile families)

Nota

Se si usa Windows Phone Silverlight come piattaforma di destinazione, fare riferimento alla procedura per l'integrazione di Windows Phone Silverlight.If you are targeting Windows Phone Silverlight then refer to the Windows Phone Silverlight integration procedure.

Installare Mobile Engagement SDK per app universaliInstall the Mobile Engagement Universal Apps SDK

Tutte le piattaformeAll platforms

Mobile Engagement SDK per app di Windows universali è disponibile come pacchetto NuGet denominato MicrosoftAzure.MobileEngagement.The Mobile Engagement SDK for Windows Universal App 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.

Windows 8.x e Windows Phone 8.1Windows 8.x and Windows Phone 8.1

NuGet distribuisce automaticamente le risorse SDK nella cartella Resources nella radice del progetto dell'applicazione.NuGet automatically deploys the SDK resources in the Resources folder at the root of your application project.

Applicazioni UWP di Windows 10Windows 10 Universal Windows Platform applications

NuGet non esegue ancora la distribuzione automatica di risorse SDK in applicazioni UWP.NuGet does not automatically deploy the SDK resources in your UWP application yet. Fino a quando la funzione di distribuzione delle risorse non verrà reintrodotta in NuGet, sarà necessario eseguire questa operazione manualmente:You have to do it manually until resources deployment is reintroduced in NuGet:

  1. Aprire Esplora file.Open your File Explorer.
  2. Passare al percorso seguente (x.x.x è la versione di Mobile Engagement che si sta installando): %USERPROFILE%\.nuget\packages\MicrosoftAzure.MobileEngagement\x.x.x\content\win81Navigate to the following location (x.x.x is the version of Engagement you are installing): %USERPROFILE%\.nuget\packages\MicrosoftAzure.MobileEngagement\x.x.x\content\win81
  3. Trascinare la cartella Risorse da Esplora file alla radice del progetto in Visual Studio.Drag and drop the Resources folder from the file explorer to the root of your project in Visual Studio.
  4. In Visual Studio selezionare il progetto e attivare l'icona Mostra tutti i file nella parte superiore di Esplora soluzioni.In Visual Studio select your project and activate the Show All files icon on top of the Solution Explorer.
  5. Alcuni file non sono inclusi nel progetto.Some files are not included in the project. Per importarli tutti contemporaneamente, fare clic con il pulsante destro del mouse su Risorse e scegliere Escludi dal progetto, quindi fare nuovamente clic con il pulsante destro del mouse su Risorse e scegliere Includi nel progetto per includere l'intera cartella.To import them at once right click on the Resources folder, Exclude from project then another right click on the Resources folder, Include in project to re-include the whole folder. Tutti i file della cartella Risorse sono ora inclusi nel progetto.All files from the Resources folder are now included in your project.

Aggiungere le funzionalitàAdd the capabilities

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

Aprire il file Package.appxmanifest e assicurarsi che le seguenti funzionalità siano dichiarate:Open your Package.appxmanifest file and be sure that the following capabilities are declared:

  • Internet (Client)

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

      /* 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);

La stringa di connessione per l'applicazione viene visualizzata nel portale di Azure classico.The connection string for your application is displayed on the Azure Classic 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;
    
  • Definire un metodo per condividere l'inizializzazione di Engagement una sola volta per tutte le chiamate:Define a method to share the Engagement initialization once for all calls:

    private void InitEngagement(IActivatedEventArgs e)
    {
      EngagementAgent.Instance.Init(e);
    
      // or
    
      EngagementAgent.Instance.Init(e, engagementConfiguration);
    }
    
  • Chiamare InitEngagement nel metodo OnLaunched:Call InitEngagement in the OnLaunched method:

    protected override void OnLaunched(LaunchActivatedEventArgs e)
    {
      InitEngagement(e);
    }
    
  • Quando l'applicazione viene avviata usando uno schema personalizzato, un'altra applicazione o la riga di comando, viene chiamato il metodo OnActivated.When your application is launched using a custom scheme, another application or the command line then the OnActivated method is called. È inoltre necessario avviare l'SDK di Engagement quando viene attivata l'applicazione.You also need to initiate the Engagement SDK when your app is activated. A tale scopo, eseguire l'override del metodo OnActivated :To do so, override OnActivated method:

    protected override void OnActivated(IActivatedEventArgs args)
    {
      InitEngagement(args);
    }
    

Importante

È altamente sconsigliata l'aggiunta dell'inizializzazione di Engagement in un altro punto dell'applicazione.We strongly discourage you to add the Engagement initialization in another place of your application.

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 Page 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 Page 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 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).If your page overrides the OnNavigatedTo method, be sure to call base.OnNavigatedTo(e). In caso contrario, l'attività non verrà segnalata (EngagementPage chiama StartActivity all'interno del relativo metodo OnNavigatedTo).Otherwise, the activity will not be reported (the EngagementPage calls StartActivity inside its OnNavigatedTo method).

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à 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 behaviour 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 informations 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 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 to call 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.Ensure you end your session correctly.

Windows Universal SDK chiama automaticamente il metodo EndActivity quando l'applicazione viene chiusa.The Windows Universal SDK automatically calls the EndActivity method when the application is closed. È quindi ALTAMENTE consigliabile chiamare il metodo StartActivity ogni volta che l'attività dell'utente subisce modifiche e non chiamare MAI il metodo EndActivity, che segnala al server di Engagement che l'utente ha chiuso l'applicazione e influisce così su tutti i log delle applicazioni.Thus, it is HIGHLY recommended to call the StartActivity method whenever the activity of the user change, and to NEVER call the EndActivity method, this method sends to Engagement server that current user has leave the application, this will impacts all application logs.

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 un'app di Windows universale.For further information, see How to use the advanced Mobile Engagement tagging API in your Windows Universal 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 quando si verifica un arresto anomalo non gestito nell'app, Engagement non lo invierà E non chiuderà la sessione e i processi.If you plan to disable this feature, be aware that when a unhandled crash will occur in your app, Engagement will not send the crash AND will not close the session and jobs.

Per disabilitare la segnalazione automatica degli arresti anomali, personalizzare la configurazione in base al modo in cui che è 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

Non è possibile configurare la soglia di burst per un periodo inferiore a 1s.The burst threshold cannot be configured to a period lesser than 1s. Se si tenta di impostare un valore minore, l'SDK mostrerà una traccia con l'errore e verrà reimpostato automaticamente sul valore predefinito, vale a dire, 0s.If you try to do so, the SDK will show a trace with the error and will automatically reset to the default value, i.e., 0s. In questo modo verrà attivato l'SDK per la segnalazione dei log in tempo reale.This will trigger the SDK to report the logs in real-time.