Configurare l'app per le notifiche push mirate

  • Articolo

È possibile usare la pagina Notifiche push del Centro per i partner per interagire direttamente con i clienti inviato notifiche push ai dispositivi in cui è installata l'app UWP (Universal Windows Platform). Ad esempio, è possibile usare notifiche push mirate per invitare i clienti a eseguire un'azione, ad esempio valutare l'app o provare una nuova funzionalità. È possibile inviare diversi tipi di notifiche push, tra cui notifiche di tipo avviso popup, notifiche di tipo riquadro e notifiche in codice XML non elaborato. È anche possibile tenere traccia della frequenza con cui l'app viene avviata in seguito alle notifiche push. Per ulteriori informazioni su questa funzionalità, vedere Inviare notifiche push ai clienti dell'app.

Per poter inviare notifiche push mirate ai clienti dal Centro per i partner, è necessario usare un metodo della classe StoreServicesEngagementManager in Microsoft Store Services SDK per registrare l'app per la ricezione di notifiche. È possibile usare metodi aggiuntivi di questa classe per notificare al Centro per i partner che l'app è stata avviata in risposta a una notifica push mirata (se si desidera tenere traccia della frequenza con cui l'app viene avviata in seguito alle notifiche) e per interrompere la ricezione di notifiche.

Configurare il progetto

Prima di scrivere il codice, eseguire questa procedura per aggiungere un riferimento a Microsoft Store Services SDK nel progetto:

  1. Se non lo si è ancora fatto, installare Microsoft Store Services SDK nel computer di sviluppo.
  2. Aprire il progetto in Visual Studio.
  3. In Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo Riferimenti del progetto e scegliere Aggiungi riferimento.
  4. In Gestione riferimenti espandere Universal Windows e fare clic su Estensioni.
  5. Nell'elenco degli SDK fare clic sulla casella di controllo accanto a Microsoft Engagement Framework e fare clic su OK.

Registrarsi per le notifiche push

Per registrare l'app per la ricezione di notifiche push mirate dal Centro per i partner:

  1. Nel progetto individuare una sezione del codice eseguita all'avvio in cui è possibile registrare l'app per la ricezione di notifiche.

  2. Aggiungere l'istruzione seguente all'inizio del file di codice.

    using Microsoft.Services.Store.Engagement;

  3. Ottenere un oggetto StoreServicesEngagementManager e chiamare uno degli overload RegisterNotificationChannelAsync nel codice di avvio identificato in precedenza. Questo metodo deve essere chiamato ogni volta che si avvia l'app.

  • Se si desidera che il Centro per i partner crei il proprio URI di canale per le notifiche, chiamare l'overload RegisterNotificationChannelAsync().

    StoreServicesEngagementManager engagementManager = StoreServicesEngagementManager.GetDefault();
await engagementManager.RegisterNotificationChannelAsync();

    Importante

    Se l'app chiama CreatePushNotificationChannelForApplicationAsync per creare un canale di notifica per WNS, assicurarsi che il codice non chiami contemporaneamente CreatePushNotificationChannelForApplicationAsync e l'overload RegisterNotificationChannelAsync(). Se è necessario chiamare entrambi questi metodi, assicurarsi di chiamarli in sequenza e attendere la restituzione di un metodo prima di chiamare l'altro.

  • Se si desidera specificare l'URI di canale da usare per le notifiche push mirate inviate dal Centro per i partner, chiamare l'overload RegisterNotificationChannelAsync(StoreServicesNotificationChannelParameters). Ad esempio, potrebbe essere opportuno eseguire questa operazione se l'app usa già Servizi notifica Push Windows (WNS) e si desidera usare lo stesso URI di canale. È necessario innanzitutto creare un oggetto StoreServicesNotificationChannelParameters e assegnare la proprietà CustomNotificationChannelUri all'URI di canale.

    StoreServicesNotificationChannelParameters parameters =
    new StoreServicesNotificationChannelParameters();
parameters.CustomNotificationChannelUri = "Assign your channel URI here";

StoreServicesEngagementManager engagementManager = StoreServicesEngagementManager.GetDefault();
await engagementManager.RegisterNotificationChannelAsync(parameters);

Nota

Quando si chiama il metodo RegisterNotificationChannelAsync, nell'archivio dei dati locali dell'app viene creato un file denominato MicrosoftStoreEngagementSDKId.txt per l'app (la cartella restituita dalla proprietà ApplicationData.LocalFolder). Questo file contiene un ID che viene usato dall'infrastruttura delle notifiche push mirate. Assicurarsi che l'app non modifichi o elimini questo file. In caso contrario, gli utenti potrebbero ricevere più istanze di notifiche o le notifiche potrebbero presentare altri comportamenti non corretti.

Indirizzamento delle notifiche push mirate ai clienti

Quando l'app chiama RegisterNotificationChannelAsync, questo metodo raccoglie l'account Microsoft del cliente attualmente connesso al dispositivo. Successivamente, quando si invia una notifica push mirata a un segmento che include questo cliente, il Centro per i partner invia la notifica ai dispositivi associati all'account Microsoft di questo cliente.

Se il cliente che ha avviato l'app dà il dispositivo a un altro utente mentre è ancora connesso al dispositivo con il proprio account Microsoft, il nuovo utente potrebbe visualizzare la notifica destinata al cliente originale. Ciò può avere conseguenze impreviste, in particolare per le app che offrono servizi che richiedono l'accesso dei clienti. Per impedire che altri utenti vedano le notifiche mirate in questo scenario, chiamare il metodo UnregisterNotificationChannelAsync quando l'utente si disconnette dall'app. Per ulteriori informazioni, vedere Annullare la registrazione per le notifiche push più avanti in questo articolo.

Risposta dell'app quando l'utente l'avvia

Dopo che l'app è registrata per ricevere le notifiche, quando si invia una notifica push ai clienti dell'app dal Centro per i partner, nell'app viene chiamato uno dei seguenti punti di ingresso nel momento in cui l'utente avvia l'app in risposta alla notifica push. Se si desidera eseguire del codice specifico quando l'utente avvia l'app, è possibile aggiungere il codice a uno di questi punti di ingresso nell'app.

  • Se la notifica push ha un tipo di attivazione in primo piano, eseguire l'override del metodo OnActivated della classe App nel progetto e aggiungere il codice a questo metodo.

  • Se la notifica push ha un tipo di attivazione in background, aggiungere il codice al metodo Run per l'attività in background.

Ad esempio, si potrebbe voler ricompensare gli utenti dell'app che hanno acquistato componenti aggiuntivi a pagamento concedendo loro un componente aggiuntivo gratuito. In questo caso, è possibile inviare una notifica push a un segmento di clienti che include questi utenti. Quindi, è possibile aggiungere il codice per concedere loro un acquisto in-app gratuito in uno dei punti di ingresso elencati in precedenza.

Notificare l'avvio dell'app al Centro per i partner

Se si seleziona l'opzione Tieni traccia della frequenza di avvio dell'app per la notifica push mirata nel Centro per i partner, chiamare il metodo ParseArgumentsAndTrackAppLaunch dal punto di ingresso appropriato nell'app per notificare al Centro per i partner che l'app è stata avviata in risposta alla notifica push.

Questo metodo restituisce anche gli argomenti di avvio originali per l'app. Quando si sceglie di tenere traccia della frequenza di avvio dell'app in seguito alla notifica push, viene aggiunto un ID di traccia opaco agli argomenti di avvio per tenere traccia dell'avvio dell'app nel Centro per i partner. È necessario passare gli argomenti di avvio per l'app al metodo ParseArgumentsAndTrackAppLaunch e questo metodo invia l'ID di traccia al Centro per i partner, rimuovo l'ID di traccia dagli argomenti di avvio e restituisce gli argomenti di avvio originali al codice.

Il modo in cui si chiama questo metodo dipende dal tipo di attivazione della notifica push:

  • Se la notifica push ha un tipo di attivazione in primo piano, chiamare questo metodo dall'override del metodo OnActivated nell'app e passare gli argomenti disponibili nell'oggetto ToastNotificationActivatedEventArgs passato a questo metodo. L'esempio di codice seguente presuppone che il file del codice abbia istruzioni using per gli spazi dei nomi Microsoft.Services.Store.Engagement e Windows.ApplicationModel.Activation.

    protected override void OnActivated(IActivatedEventArgs args)
{
    base.OnActivated(args);

    if (args is ToastNotificationActivatedEventArgs)
    {
        var toastActivationArgs = args as ToastNotificationActivatedEventArgs;

        StoreServicesEngagementManager engagementManager = StoreServicesEngagementManager.GetDefault();
        string originalArgs = engagementManager.ParseArgumentsAndTrackAppLaunch(
            toastActivationArgs.Argument);

        // Use the originalArgs variable to access the original arguments
        // that were passed to the app.
    }
}

  • Se la notifica push ha un tipo di attivazione in background, chiamare questo metodo dal metodo Run per l'attività in background e passare gli argomenti disponibili nell'oggetto ToastNotificationActionTriggerDetail passato a questo metodo. L'esempio di codice seguente presuppone che il file di codice abbia istruzioni using per gli spazi dei nomi Microsoft.Services.Store.Engagement, Windows.ApplicationModel.Background e Windows.UI.Notifications.

    public void Run(IBackgroundTaskInstance taskInstance)
{
    var details = taskInstance.TriggerDetails as ToastNotificationActionTriggerDetail;

    if (details != null)
    {
        StoreServicesEngagementManager engagementManager = StoreServicesEngagementManager.GetDefault();
        string originalArgs = engagementManager.ParseArgumentsAndTrackAppLaunch(details.Argument);

        // Use the originalArgs variable to access the original arguments
        // that were passed to the app.
    }
}

Annullare la registrazione per le notifiche push

Se si desidera che l'app smetta di ricevere le notifiche push mirate dal Centro per i partner, chiamare il metodo UnregisterNotificationChannelAsync.

StoreServicesEngagementManager engagementManager = StoreServicesEngagementManager.GetDefault();
await engagementManager.UnregisterNotificationChannelAsync();

Notare che questo metodo invalida il canale usato per le notifiche, pertanto l'app non riceverà più le notifiche push da alcun servizio. Dopo la chiusura, il canale non potrà più essere usato per alcun servizio, tra cui le notifiche push mirate inviate dal Centro per i partner e altre notifiche tramite WNS. Per ripristinare l'invio di notifiche push a questa app, è necessario che l'app richieda un nuovo canale.