Integrazione dell'SDK di Reach per Windows Phone SilverlightWindows Phone Silverlight Reach SDK Integration

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

Incorporare l'SDK del servizio Reach di Engagement nel progetto Windows Phone SilverlightEmbed the Engagement Reach SDK into your Windows Phone Silverlight 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).

Aggiungere le funzionalitàAdd the capabilities

L'SDK del servizio Reach di Engagement richiede alcune funzionalità aggiuntive.The Engagement Reach SDK needs some additional capabilities.

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

  • ID_CAP_PUSH_NOTIFICATION
  • ID_CAP_WEBBROWSERCOMPONENT

La prima viene usata dal servizio MPNS per consentire la visualizzazione di notifiche popup.The first one is used by the MPNS service to allow the display of toast notification. La seconda viene usata per incorporare un'attività del browser nell'SDK.The second one is used to embed a browser task into the SDK.

Modificare il file WMAppManifest.xml e aggiungere il tag <Capabilities /> all'interno:Edit the WMAppManifest.xml file and add inside the <Capabilities /> tag :

<Capability Name="ID_CAP_PUSH_NOTIFICATION" />
<Capability Name="ID_CAP_WEBBROWSERCOMPONENT" />

Abilitare il Servizio notifica push MicrosoftEnable the Microsoft Push Notification Service

Per usare il Servizio notifica push Microsoft (indicato come MPNS), il file WMAppManifest.xml deve avere un tag <App /> con un attributo Publisher impostato sul nome del progetto.In order to use the Microsoft Push Notification Service (referred as MPNS) your WMAppManifest.xml file must have an <App /> tag with a Publisher attribute set to the name of your project.

Inizializzare Engagement Reach SDKInitialize the Engagement Reach 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 la configurazione di Reach:Edit this file to specify reach configuration :

  • Facoltativo: indicare se il push nativo (MPNS) è attivato tra i tag <enableNativePush> e </enableNativePush>. L'impostazione predefinita è true.Optional, indicate whether the native push (MPNS) is activated or not between <enableNativePush> and </enableNativePush> tags, (true by default).
  • Facoltativo: indicare il nome del canale di push tra i tag <channelName> e </channelName>. Fornire quello che potrebbe essere in uso nell'applicazione o lasciare vuoto il campo.Optional, indicate the name of the push channel between <channelName> and </channelName> tags, provide the same that your application may currently use or leave it empty.

Se si desidera specificarlo 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}";

engagementConfiguration.Reach.EnableNativePush = true;                  
/* [Optional] whether the native push (MPNS) is activated or not. */

engagementConfiguration.Reach.ChannelName = "YOUR_PUSH_CHANNEL_NAME";   
/* [Optional] Provide the same channel name that your application may currently use. */

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

Suggerimento

È possibile specificare il nome del canale di push MPNS dell'applicazione.You can specify the name of the MPNS push channel of your application. Per impostazione predefinita, Engagement crea un nome basato su appId.By default, Engagement creates a name based on the appId. Non è necessario specificare il nome manualmente, a meno che non si preveda di utilizzare il canale di push fuori da Engagement.You have no need to specify the name yourself, except if you plan to use the push channel outside of Engagement.

Inizializzazione di EngagementEngagement initialization

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 EngagementReach.Instance.Init subito dopo EngagementAgent.Instance.Init in Application_Launching:Insert EngagementReach.Instance.Init just after EngagementAgent.Instance.Init in Application_Launching :

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

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

Importante

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.

Considerazioni sull'invio di notifiche di App StoreApp store submission considerations

Microsoft impone alcune regole relative all'uso delle notifiche push.Microsoft imposes some rules when using the push notifications:

Come definito nella documentazione di Microsoft sui criteri relativi alle applicazioni , sezione 2.9:From the Microsoft [Application Policies] documentation, section 2.9:

1) È necessario chiedere all'utente di accettare la ricezione delle notifiche push.You must ask the user to accept to receive push notifications. Aggiungere quindi nelle impostazioni un modo per disattivare le notifiche push.Then, in your settings, add a way to disable the push notifications.

L'oggetto EngagementReach fornisce due metodi per gestire il consenso/rifiuto, EnableNativePush() e DisableNativePush().The EngagementReach object provides two methods to manage the opt-in/opt-out, EnableNativePush() and DisableNativePush(). È possibile, ad esempio, creare nelle impostazioni un'opzione che consente di disabilitare o abilitare MPNS.You could, for example, create an option in the settings with a toggle to disable or enable MPNS.

È possibile anche decidere di disattivare MPNS tramite la configurazione di Engagement <windows-phone-sdk-reach-configuration>.You can also decide to deactivate MPNS through the Engagement configuration<windows-phone-sdk-reach-configuration>.

2.9.1) L'applicazione deve descrivere prima le notifiche da fornire e ottenere l'autorizzazione esplicita dell'utente (consenso) e deve fornire un meccanismo attraverso il quale l'utente può rifiutare esplicitamente la ricezione di notifiche push.2.9.1) The application must first describe the notifications to be provided and obtain the user’s express permission (opt-in), and must provide a mechanism through which the user can opt out of receiving push notifications. Tutte le notifiche fornite tramite il Servizio notifica push Microsoft devono essere coerenti con la descrizione fornita all'utente e conformi a tutti i criteri applicazione e a tutti i requisiti aggiuntivi per tipi di applicazione specifici applicabili.All notifications provided using the Microsoft Push Notification Service must be consistent with the description provided to the user and must comply with all applicable Application Policies and [Additional Requirements for Specific Application Types].

2) Non fare un uso eccessivo delle notifiche push.You should not use too many push notifications. Engagement gestisce le notifiche in modo automatico.Engagement will handle notifications for you.

2.9.2) L'applicazione che usa il Servizio notifica push Microsoft non deve sfruttare in modo eccessivo la capacità di rete o la larghezza di banda del Servizio notifica push Microsoft o sovraccaricare inutilmente un dispositivo Windows Phone o altro dispositivo o servizio Microsoft con un numero eccessivo di notifiche push, come stabilito da Microsoft a sua ragionevole discrezione, e non deve danneggiare o interferire con le reti o i server Microsoft o i server e le reti di terze parti connesse al Servizio notifica push Microsoft.2.9.2) The application and its use of the Microsoft Push Notification Service must not excessively use network capacity or bandwidth of the Microsoft Push Notification Service, or otherwise unduly burden a Windows Phone or other Microsoft device or service with excessive push notifications, as determined by Microsoft in its reasonable discretion, and must not harm or interfere with any Microsoft networks or servers or any third party servers or networks connected to the Microsoft Push Notification Service.

3) Non fare affidamento su MPNS per inviare informazioni critiche.Do not rely on MPNS to send criticals information. Engagement usa MPNS, pertanto questa regola è valida anche per le campagne create all'interno del front-end di Engagement.Engagement uses MPNS, so this rule also applies for the campaigns created inside the Engagement front-end.

2.9.3) Il Servizio notifica push Microsoft non può essere usato per inviare notifiche di importanza cruciale o che possono influire su questioni di vita o di morte, incluse, senza alcuna limitazione, notifiche correlate a una condizione o a un dispositivo medico.2.9.3) The Microsoft Push Notification Service may not be used to send notifications that are mission critical or otherwise could affect matters of life or death, including without limitation critical notifications related to a medical device or condition. MICROSOFT RIFIUTA ESPRESSAMENTE QUALSIASI GARANZIA CHE L'UTILIZZO DEL SERVIZIO DI NOTIFICA PUSH DI MICROSOFT O CHE IL RECAPITO DELLE NOTIFICHE DEL SERVIZIO NOTIFICA PUSH MICROSOFT SARÀ ININTERROTTO, PRIVO DI ERRORI O CHE SARÀ ESEGUITO IN TEMPO REALE.MICROSOFT EXPRESSLY DISCLAIMS ANY WARRANTIES THAT THE USE OF THE MICROSOFT PUSH NOTIFICATION SERVICE OR DELIVERY OF MICROSOFT PUSH NOTIFICATION SERVICE NOTIFICATIONS WILL BE UNINTERRUPTED, ERROR FREE, OR OTHERWISE GUARANTEED TO OCCUR ON A REAL-TIME BASIS.

Non è possibile garantire che l'applicazione supererà il processo di convalida se non si rispettano queste indicazioni.We cannot guarantee that your application will pass the validation process if you do not respect these recommendations.

Gestire il push di dati (facoltativo)Handle data push (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:

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 Application_Launching.Then, set the content of the EngagementReach.Instance.Handler field with your custom object in your App.xaml.cs class within the Application_Launching method.

Codice di esempio:Sample Code :

private void Application_Launching(object sender, LaunchingEventArgs e)
{
   // 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.

LayoutLayouts

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.

Tuttavia, è possibile decidere di utilizzare le proprie risorse in modo da riflettere il marchio in questi componenti.However, you can decide to use your own resources to reflect your brand in these components.

È possibile eseguire l'override dei metodi EngagementReachHandler in una sottoclasse per indicare a Engagement di usare layout personalizzati:You can override EngagementReachHandler methods in your subclass to tell Engagement to use your layouts :

Codice di esempio:Sample Code :

// In your subclass of EngagementReachHandler

public override string GetTextViewAnnouncementUri()
{
   // return the path of your own xaml
}

public override string GetWebViewAnnouncementUri()
{
   // return the path of your own xaml
}

public override string GetPollUri()
{
   // return the path of your own xaml
}

public override EngagementNotificationView CreateNotification(EngagementNotificationViewModel viewModel)
{
   // return a new instance of your own notification
}

Suggerimento

Il metodo CreateNotification può restituire null.The CreateNotification method can return null. La notifica non verrà visualizzata e la campagna Reach verrà eliminata.The notification won't be displayed and the reach campaign will be dropped.

Per semplificare l'implementazione di layout, viene fornito anche un xaml che può essere utilizzato come base per il codice.To simplify your layout implementation, we also provide our own xaml which can serve as a basis for your code. Tale elemento si trova nell'archivio dell'SDK di Engagement (/src/reach/).They are located in the Engagement SDK archive (/src/reach/).

Avviso

Le origini fornite da Microsoft sono le stesse.The sources that we provide are the exact same ones that we use. Pertanto, se si desidera modificarle direttamente, non dimenticare di modificare lo spazio dei nomi e il nome.So if you want to modify them directly, don't forget to change the namespace and the name.

Posizione di notificaNotification position

Per impostazione predefinita, una notifica in-app viene visualizzata nella parte inferiore sinistra dell'applicazione.By default, an in-app notification is displayed at the bottom left side of the application. È possibile modificare questo comportamento eseguendo l'override del metodo GetNotificationPosition dell'oggetto EngagementReachHandler.You can change this behavior by overriding the GetNotificationPosition method of the EngagementReachHandler object.

// In your subclass of EngagementReachHandler

public override EngagementReachHandler.NotificationPosition GetNotificationPosition(EngagementNotificationViewModel viewModel)
{
   // return a value of the EngagementReachHandler.NotificationPosition enum (TOP or BOTTOM)
}

Attualmente, è possibile scegliere tra le posizioni BOTTOM (impostazione predefinita) e TOP.Currently, you can choose between the BOTTOM (default) and TOP positions.

Messaggio di avvioLaunch message

Quando un utente fa clic su una notifica del sistema (avviso popup), Engagement avvia l'app, 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 app, 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:To implement the callback, do:

/* 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 Application_Launching del file App.xaml.cs, preferibilmente prima della chiamata EngagementReach.Instance.Init().You can set the callback in your Application_Launching 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.