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

Prima di usare questa guida, è necessario eseguire la procedura di integrazione descritta nel documento Integrazione di Mobile Engagement SDK per app di Windows universali .You must follow the integration procedure described in the Windows Universal Engagement SDK Integration before following this guide.

Incorporare Engagement Reach SDK nel progetto di app universali di WindowsEmbed the Engagement Reach SDK into your Windows Universal project

Nessun elemento da aggiungere.You do not have anything to add. EngagementReach sono già presenti nel progetto.EngagementReach references and resources are already in your project.

Suggerimento

È possibile personalizzare le immagini incluse nella cartella Resources del progetto, soprattutto l'icona del marchio, che per impostazione predefinita è l'icona di Engagement.You can customize images located in the Resources folder of your project, especially the brand icon (that default to the Engagement icon). Nelle app universali è inoltre possibile spostare la cartella Resources del progetto condiviso per condividere il contenuto tra app, ma è necessario mantenere il file Resources\EngagementConfiguration.xml nel percorso predefinito poiché è dipendente dalla piattaforma.On Universal Apps you can also move the Resources folder on your shared project to share its content between apps, but you will have to keep the Resources\EngagementConfiguration.xml file on its default location as it is platform dependent.

Abilitare Servizi notifica Push WindowsEnable the Windows Notification Service

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

Per usare Servizi notifica Push Windows (indicati come WNS) nel file Package.appxmanifest su Application UI fare clic su All Image Assets nella casella a sinistra.In order to use the Windows Notification Service (referred as WNS) in your Package.appxmanifest file on Application UI click on All Image Assets in the left bot box. A destra della casella in Notifications, modificare il valore di toast capable da (not set) a (Yes).At the right of the box in Notifications, change toast capable from (not set) to (Yes).

Tutte le piattaformeAll platforms

È necessario sincronizzare l'app con il proprio account Microsoft e con la piattaforma di Engagement.You need to synchronize your app to your Microsoft account and to the engagement platform. A questo scopo, è necessario creare un account o accedere al Windows Dev Center.For this you need to create an account or log on windows dev center. Creare quindi una nuova applicazione e individuare il SID e la chiave privata.After that create a new application and find the SID and secret key. Nel front-end di Engagement passare all'impostazione dell'app in native push e incollare le credenziali.On the engagement frontend, go on your app setting in native push and paste your credentials. Dopo questa operazione, fare clic sul progetto, selezionare store e Associate App with the Store....After that, right click on your project, select store and Associate App with the Store.... Per sincronizzare l'applicazione creata in precedenza, è sufficiente selezionarla.You just need to select the application you have create before to synchronize it.

Inizializzare Engagement Reach SDKInitialize the Engagement Reach SDK

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

  • Inserire EngagementReach.Instance.Init subito dopo EngagementAgent.Instance.Init nel metodo InitEngagement:Insert EngagementReach.Instance.Init just after EngagementAgent.Instance.Init in your InitEngagement method:

    private void InitEngagement(IActivatedEventArgs e)
    {
      EngagementAgent.Instance.Init(e);
      EngagementReach.Instance.Init(e);
    }
    

    EngagementReach.Instance.Init viene eseguito in un thread dedicato.The EngagementReach.Instance.Init runs in a dedicated thread. Non è necessario eseguirlo manualmente.You do not have to do it yourself.

Nota

Se si usano notifiche push in altre sezioni dell'applicazione, è necessario condividere il canale di push con Engagement Reach.If you are using push notifications elsewhere in your application then you have to share your push channel with Engagement Reach.

IntegrazioneIntegration

Engagement offre due modi per aggiungere i banner in-app, le visualizzazioni intermedie di annunci e i sondaggi Reach all'applicazione: l'integrazione di una sovrimpressione e l'integrazione manuale di visualizzazioni Web.Engagement provides two ways to add the Reach in-app banners and interstitial views for announcements and polls in your application: the overlay integration and the web views manual integration. È consigliabile non combinare entrambe le soluzioni nella stessa pagina.You should not combine both approach on the same page.

La scelta tra uno dei due tipi d'integrazione può essere riassunta nel modo seguente:The choice between the two integration could be summarized this way:

  • Se le pagine ereditano già dall'agente EngagementPage, è consigliabile scegliere l'integrazione di una sovrimpressione. È sufficiente sostituire EngagementPage con EngagementPageOverlay e xmlns:engagement="using:Microsoft.Azure.Engagement" con xmlns:engagement="using:Microsoft.Azure.Engagement.Overlay" nelle pagine.You may choose the overlay integration if your pages already inherits from the Agent EngagementPage, it's just a matter of replacing EngagementPage by EngagementPageOverlay and xmlns:engagement="using:Microsoft.Azure.Engagement" by xmlns:engagement="using:Microsoft.Azure.Engagement.Overlay" in your pages.
  • È possibile scegliere l'integrazione manuale di visualizzazioni Web se si vuole inserire l'interfaccia utente di Reach in un punto preciso nelle pagine oppure se non si vuole aggiungere un altro livello di ereditarietà alle pagine.You may choose the web views manual integration if you want to precisely place the Reach UI within your pages or if you don't want to add another inheritance level to your pages.

Integrazione di una sovrimpressioneOverlay integration

La sovrimpressione di Engagement aggiunge in modo dinamico gli elementi dell'interfaccia utente utilizzati per visualizzare le campagne Reach nella pagina.The Engagement overlay dynamically adds the UI elements used to display Reach campaigns in your page. Se la sovrimpressione non è adatta al layout, considerare invece l'integrazione manuale delle visualizzazioni Web.If the overlay doesn't suit your layout you should consider the web views manual integration instead.

Nel file con estensione xaml modificare il riferimento EngagementPage in EngagementPageOverlayIn your .xaml file change EngagementPage reference to EngagementPageOverlay

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

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

Con EngagementPage:With EngagementPage:

    <engagement:EngagementPage 
        xmlns:engagement="using:Microsoft.Azure.Engagement">

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

Con EngagementPageOverlay:With EngagementPageOverlay:

    <engagement:EngagementPageOverlay 
        xmlns:engagement="using:Microsoft.Azure.Engagement.Overlay">

        <!-- Your layout -->
    </engagement:EngagementPageOverlay>

Quindi, nel file con estensione cs contrassegnare la pagina in EngagementPageOverlay anziché EngagementPage e importare Microsoft.Azure.Engagement.Overlay.Then in your .cs file tag your page in EngagementPageOverlay instead of EngagementPage and import Microsoft.Azure.Engagement.Overlay.

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

Con EngagementPage:With EngagementPage:

        using Microsoft.Azure.Engagement;

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

Con EngagementPageOverlay:With EngagementPageOverlay:

        using Microsoft.Azure.Engagement.Overlay;

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

La sovrimpressione di Engagement aggiunge un elemento Grid in alto alla pagina che è costituita dal layout e dai due elementi WebView, uno per il banner e l'altro per la visualizzazione intermedia.The Engagement overlay adds a Grid element on top of your page composed of your layout and the two WebView elements one for the banner and the other one for the interstitial view.

È possibile personalizzare gli elementi della sovrimpressione direttamente nel file EngagementPageOverlay.cs.You can customize the overlay elements directly in the EngagementPageOverlay.cs file.

Integrazione manuale delle visualizzazioni WebWeb views manual integration

Reach cerca nelle pagine i due elementi WebView che determinano la visualizzazione del banner e della visualizzazione intermedia.Reach will be searching your pages for the two WebView elements responsible for displaying the banner and the interstitial view. L'unica cosa necessaria da fare è aggiungere quei due elementi WebView in un punto qualsiasi delle pagine. Ecco un esempio:The only thing you have to do is to add those two WebView elements somewhere in your pages, here is an example:

<Grid x:Name="engagementGrid">

  <!-- Your layout -->

  <WebView x:Name="engagement_notification_content" Visibility="Collapsed" Height="80" HorizontalAlignment="Stretch" VerticalAlignment="Top"/>
  <WebView x:Name="engagement_announcement_content" Visibility="Collapsed"  HorizontalAlignment="Stretch"  VerticalAlignment="Stretch"/>
</Grid>

In questo esempio gli elementi WebView vengono allungati per adattarsi al contenitore che automaticamente li ridimensiona nel caso in cui lo schermo viene ruotato o la dimensione della pagina cambia.In this example the WebView elements are stretched to fit their container which automatically re-sizes them in case of screen rotation or window size change.

Avviso

È importante che gli elementi WebView mantengano la stessa denominazione engagement_notification_content e engagement_announcement_content, poichéIt is important to keep the same naming engagement_notification_content and engagement_announcement_content for the WebView elements. Reach li identifica dal nome.Reach is identifying them by their name.

Gestire il push di dati (facoltativo)Handle datapush (optional)

Se si desidera che l'applicazione sia in grado di ricevere push di dati Reach, è necessario implementare due eventi della classe EngagementReach:If you want your application to be able to receive Reach data pushes, you have to implement two events of the EngagementReach class:

In App.xaml.cs nel costruttore App () aggiungere:In App.xaml.cs in the App() constructor add:

        EngagementReach.Instance.DataPushStringReceived += (body) =>
        {
          Debug.WriteLine("String data push message received: " + body);
          return true;
        };

        EngagementReach.Instance.DataPushBase64Received += (decodedBody, encodedBody) =>
        {
          Debug.WriteLine("Base64 data push message received: " + encodedBody);
          // Do something useful with decodedBody like updating an image view
          return true;
        };

È possibile notare che il callback di ogni metodo restituisce un valore booleano.You can see that the callback of each method returns a boolean. Engagement invia un feedback per il back-end dopo l'invio del push di dati.Engagement sends a feedback to its back-end after dispatching the data push. Se il callback restituisce false, verrà inviato il feedback exit .If the callback returns false, the exit feedback will be send. In caso contrario, il feedback sarà action.Otherwise, it will be action. Se non è impostato alcun callback per gli eventi, il feedback drop verrà restituito a Engagement.If no callback is set for the events, the drop feedback will be returned to Engagement.

Avviso

Engagement non è in grado di ricevere più feedback per un push di dati.Engagement is not able to receive multiples feedbacks for a data push. Se si prevede di impostare diversi gestori su un evento, tenere presente che il feedback corrisponderà all'ultimo inviato.If you plan to set several handlers on an event, be aware that the feedback will correspond to the last one sent. In questo caso, è consigliabile restituire sempre lo stesso valore per evitare confusione di feedback sul front-end.In this case, we recommend to always returns the same value to avoid having confusing feedback on the front-end.

Personalizzare l'interfaccia utente (facoltativo)Customize UI (optional)

Primo passaggioFirst step

È possibile personalizzare l'interfaccia utente di Reach.We allow you to customize the reach UI.

A tale scopo, è necessario creare una sottoclasse della classe EngagementReachHandler .To do so, you have to create a subclass of the EngagementReachHandler class.

Codice di esempio:Sample Code :

        using Microsoft.Azure.Engagement;

        namespace Example
        {
          internal class ExampleReachHandler : EngagementReachHandler
          {
           // Override EngagementReachHandler methods depending on your needs
          }
        }

Impostare quindi il contenuto del campo EngagementReach.Instance.Handler con l'oggetto personalizzato nella classe App.xaml.cs all'interno del metodo App().Then, set the content of the EngagementReach.Instance.Handler field with your custom object in your App.xaml.cs class within the App() method.

Codice di esempio:Sample Code :

        protected override void OnLaunched(LaunchActivatedEventArgs args)
        {
          // your app initialization 
          EngagementReach.Instance.Handler = new ExampleReachHandler();
          // Engagement Agent and Reach initialization
        }

Nota

Per impostazione predefinita, Engagement usa una specifica implementazione di EngagementReachHandler.By default, Engagement uses its own implementation of EngagementReachHandler. Non è necessario crearne di proprie e, se ne viene creata una, non è necessario eseguire l'override di ogni metodo.You don't have to create your own, and if you do so, you don't have to override every method. Il comportamento predefinito consiste nel selezionare l'oggetto di base di Engagement.The default behavior is to select the Engagement base object.

Visualizzazione WebWeb View

Per impostazione predefinita, Reach userà le risorse incorporate della DLL per visualizzare le pagine e le notifiche.By default, Reach will use the embedded resources of the DLL to display the notifications and pages.

Per fornire possibilità di personalizzazione completa è utilizzata solo la visualizzazione Web.To provide a full customization possibilities we only use web view. Se si vuole personalizzare i layout, eseguire direttamente l'override dei file di risorse EngagementAnnouncement.html e EngagementNotification.html.If you want to customize layouts, override directly the resources files EngagementAnnouncement.html and EngagementNotification.html. Engagement richiede tutto il codice in <body></body> per un'esecuzione corretta,Engagement needs all code in <body></body> to run correctly. ma è possibile aggiungere tag esterni a engagement_webview_area.But you can add tag outer engagement_webview_area.

È tuttavia possibile usare le proprie risorse.However, you can decide to use your own resources.

È possibile eseguire l'override dei metodi EngagementReachHandler in una sottoclasse per indicare a Engagement di usare i layout, ma fare attenzione al meccanismo di Engagement incorporato:You can override EngagementReachHandler methods in your subclass to tell Engagement to use your layouts, but take care to embedded the engagement mechanism:

Codice di esempio:Sample Code :

        // In your subclass of EngagementReachHandler

        public override string GetAnnouncementHTML()
        {
          return base.GetAnnouncementHTML();
        }
        public override string GetAnnouncementName()
        {
          return base.GetAnnouncementName();
        }
        public override string GetNotfificationHTML()
        {
          return base.GetNotfificationHTML();
        }
        public override string GetNotfificationName()
        {
          return base.GetNotfificationName();
        }

Per impostazione predefinita, AnnouncementHTML è ms-appx-web:///Resources/EngagementAnnouncement.html.By default, AnnouncementHTML is ms-appx-web:///Resources/EngagementAnnouncement.html. Rappresenta il file html per il progetto del contenuto di un messaggio push (annuncio di testo, annuncio Web e annuncio di sondaggio).It represents the html file that design the content of a push message (Text announcement, Web anoucement and Poll announcement). AnnouncementName è engagement_announcement_content.AnnouncementName is engagement_announcement_content. È il nome del progetto webview nella pagina xaml.It is the name of the webview design in your xaml page.

NotificationHTML è ms-appx-web:///Resources/EngagementNotification.html.NotfificationHTML is ms-appx-web:///Resources/EngagementNotification.html. Rappresenta il file html per il progetto la notifica di un messaggio di push.It represents the html file that design the notification of a push message. NotificationName è engagement_notification_content.NotfificationName is engagement_notification_content. È il nome del progetto webview nella pagina xaml.It is the name of the webview design in your xaml page.

PersonalizzazioneCustomization

È possibile personalizzare la visualizzazione Web di notifiche e annunci nel modo desiderato se si mantiene l'oggetto Engagement.You can customize notification and announcement web view has you want if you preserve Engagement object. Tenere presente che l'oggetto webview è descritto tre volte. La prima volta in xaml, la seconda nel file cs nel metodo "setwebview()" e la terza nel file html.Take care that webview object is described three times - the first time in your xaml, second time in your .cs file in the "setwebview()" method, and third time in the html file.

  • Nel file xaml si descrive il componente di webview del layout grafico corrente.In your xaml you describe the current graphical layout webview component.
  • Nel file cs è possibile definire "setwebview()" in cui è possibile impostare la dimensione delle due webview (notifica, annuncio).In your .cs file you can define "setwebview()" in which you set the dimension of the two webview (notification, announcement). Questa operazione è molto efficace per il ridimensionamento dell'applicazione.It is very effective when the application is resizing.
  • Nel file html di Engagement viene descritto il contenuto della visualizzazione Web, il progetto e le posizioni degli elementi.In the Engagement html file we describe the webview content, design and the elements positions between each other.

Messaggio di avvioLaunch message

Quando un utente fa clic su una notifica del sistema (avviso popup), Engagement avvia l'applicazione, carica il contenuto dei messaggi di push e visualizza la pagina per la campagna corrispondente.When a user clicks on a system notification (a toast), Engagement launches the application, load the content of the push messages, and display the page for the corresponding campaign.

Tra l'avvio dell'applicazione e la visualizzazione della pagina si verifica un ritardo (a seconda della velocità della rete).There is a delay between the launch of the application and the display of the page (depending on the speed of your network).

Per indicare all'utente che è in corso un caricamento, è necessario fornire un'indicazione visiva, ad esempio una barra o un indicatore di avanzamento.To indicate to the user that something is loading, you should provide a visual information, like a progress bar or a progress indicator. Engagement non è in grado di gestire questa situazione, ma fornisce alcuni gestori.Engagement cannot handle that itself, but provides a few handlers for you.

Per implementare il callback, in App.xaml.cs in "Public App(){}" aggiungere:To implement the callback, in App.xaml.cs in "Public App(){}" add:

        /* The application has launched and the content is loading.
         * You should display an indicator here.
         */
        EngagementReach.Instance.RetrieveLaunchMessageStarted += () => { [...] };

        /* The application has finished loading the content and the page
         * is about to be displayed.
         * You should hide the indicator here.
         */
        EngagementReach.Instance.RetrieveLaunchMessageCompleted += () => { [...] };

        /* The content has been loaded, but an error has occurred.
         * You can provide an information to the user.
         * You should hide the indicator here.
         */
        EngagementReach.Instance.RetrieveLaunchMessageFailed += () => { [...] };

È possibile impostare il callback nel metodo "Public App(){}" del file App.xaml.cs, preferibilmente prima della chiamata EngagementReach.Instance.Init().You can set the callback in your "Public App(){}" method of your App.xaml.cs file, preferably before the EngagementReach.Instance.Init() call.

Suggerimento

Ogni gestore viene chiamato dal thread dell'interfaccia utente.Each handler is called by the UI Thread. Non è necessario preoccuparsi quando si utilizza MessageBox o un elemento correlato all'interfaccia utente.You do not have to worry when using a MessageBox or something UI-related.

Condivisione del canale pushPush channel sharing

Se si usano notifiche push per altri scopi all'interno dell'applicazione, è necessario usare la funzione di condivisone del canale push di Engagement SDK,If you are using push notifications for another purpose in your application then you have to use the push channel sharing feature of the Engagement SDK. in modo da evitare la perdita di notifiche push.This is to avoid missed push.

  • È possibile specificare il canale push desiderato durante la procedura di inizializzazione di Engagement Reach.You can provide your own push channel to the Engagement Reach initialization. In questo modo, l'SDK userà il canale specificato anziché richiederne uno nuovo.The SDK will use it instead of requesting a new one.

Aggiornare l'inizializzazione di Engagement Reach con il canale push nel metodo InitEngagement ottenuto dal file App.xaml.cs:Update the Engagement Reach initialization with your push channel in the InitEngagement method from the App.xaml.cs file:

/* Your own push channel logic... */
var pushChannel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();

/*...Engagement initialization */
EngagementAgent.Instance.Init(e);
EngagementReach.Instance.Init(e,pushChannel);
  • In alternativa, se si decide di usare il canale push dopo l'inizializzazione di Reach, è possibile impostare un callback su Engagement Reach per ottenere il canale push creato dall'SDK.Alternatively, if you just want to consume the push channel after the Reach initialization then you can set a callback on Engagement Reach to get the push channel once it is created by the SDK.

Impostare il callback in un momento qualsiasi dopo l'inizializzazione di Reach:Set your callback at any place after the Reach initialization :

/* Set action on the SDK push channel. */
EngagementReach.Instance.SetActionOnPushChannel((PushNotificationChannel channel) => 
{
  /* The forwarded channel can be null if its creation fails for any reason. */
  if (channel != null)
  {
    /* Your own push channel logic... */
  });
}

Suggerimento per lo schemaCustom scheme tip

È possibile utilizzare uno schema personalizzato.We provide custom scheme use. È possibile inviare un tipo diverso di URI dal front-end di Engagement da utilizzare nell'applicazione Engagement.You can send different type of URI from engagement frontend to be used in your engagement application. Lo schema predefinito come http, ftp, ... è gestito da Windows. Una finestra chiederà se nel dispositivo sono installate applicazioni predefinite.Default scheme like http, ftp, ... are manage by Windows, a window will prompt if they are no default application installed on device. È possibile anche creare uno schema personalizzato per l'applicazione.You can also create your own custom scheme for your application.

Il metodo semplice per impostare uno schema personalizzato nell'applicazione consiste nell'aprire Package.appxmanifest e andare nel pannello Declarations.The simple way to set a custom scheme in your application is to open your Package.appxmanifest go in Declarations panel. Selezionare Protocol nella casella di scorrimento Dichiarazioni disponibili e aggiungerlo.Select Protocol in the Available Declarations scroll box and add it. Modificare il campo Name con il nuovo nome desiderato per il protocollo.Edit the Name field with your new protocol desired name.

Per usare questo protocollo modificare App.xaml.cs con il metodo OnActivated e non dimenticare di inizializzare Engagement anche qui:Now to use this protocol, edit your App.xaml.cs with the OnActivated method, and don't forget to initialize engagement here also:

        /// <summary>
        /// Enter point when app his called by another way than user click
        /// </summary>
        /// <param name="args">Activation args</param>
        protected override void OnActivated(IActivatedEventArgs args)
        {
          /* Init engagement like it was launch by a custom uri scheme */
          EngagementAgent.Instance.Init(args);
          EngagementReach.Instance.Init(args);

          //TODO design action to do when app is launch

          #region Custom scheme use
          if (args.Kind == ActivationKind.Protocol)
          {
            ProtocolActivatedEventArgs myProtocol = (ProtocolActivatedEventArgs)args;

            if (myProtocol.Uri.Scheme.Equals("protocolName"))
            {
              string path = myProtocol.Uri.AbsolutePath;
            }
          }
          #endregion