Configurar seu aplicativo para notificações por push direcionadasConfigure your app for targeted push notifications

Você pode usar a página notificações por push no Partner Center para se envolver diretamente com os clientes enviando notificações por push direcionadas aos dispositivos nos quais seu aplicativo plataforma universal do Windows (UWP) está instalado.You can use the Push notifications page in Partner Center to directly engage with customers by sending targeted push notifications to the devices on which your Universal Windows Platform (UWP) app is installed. Por exemplo, você pode usar notificações por push direcionadas para incentivar os clientes a executar uma ação, como a classificação do seu aplicativo ou o uso de um novo recurso.For example, you can use targeted push notifications to encourage your customers to take an action, such as rating your app or trying a new feature. Você pode enviar vários tipos diferentes de notificações por push, incluindo notificações do sistema, notificações de bloco e notificações XML brutas.You can send several different types of push notifications, including toast notifications, tile notifications, and raw XML notifications. Você também pode controlar a taxa de inicializações do aplicativo resultantes de suas notificações por push.You can also track the rate of app launches that resulted from your push notifications. Para obter mais informações sobre esse recurso, consulte Enviar notificações por push para clientes do seu aplicativo.For more information about this feature, see Send push notifications to your app's customers.

Antes de enviar notificações por push direcionadas para seus clientes do Partner Center, você deve usar um método da classe StoreServicesEngagementManager no SDK de serviços de Microsoft Store para registrar seu aplicativo para receber notificações.Before you can send targeted push notifications to your customers from Partner Center, you must use a method of the StoreServicesEngagementManager class in the Microsoft Store Services SDK to register your app to receive notifications. Você pode usar métodos adicionais dessa classe para notificar o centro de parceiros de que seu aplicativo foi iniciado em resposta a uma notificação por push direcionada (se você quiser acompanhar a taxa de lançamentos de aplicativo que resultaram de suas notificações) e para parar de receber notificações.You can use additional methods of this class to notify Partner Center that your app was launched in response to a targeted push notification (if you want to track the rate of app launches that resulted from your notifications) and to stop receiving notifications.

Configurar seu projetoConfigure your project

Antes de gravar qualquer código, siga estas etapas para adicionar uma referência ao Microsoft Store Services SDK no seu projeto:Before you write any code, follow these steps to add a reference to the Microsoft Store Services SDK in your project:

  1. Se você ainda não fez isso, instale o Microsoft Store Services SDK no computador de desenvolvimento.If you have not done so already, Install the Microsoft Store Services SDK on your development computer.
  2. Abra o projeto no Visual Studio.Open your project in Visual Studio.
  3. No Gerenciador de Soluções, clique com botão direito no nó Referências para seu projeto e clique em Adicionar Referência.In Solution Explorer, right-click the References node for your project and click Add Reference.
  4. No Gerenciador de Referências, expanda Universal do Windows e clique em Extensões.In Reference Manager, expand Universal Windows and click Extensions.
  5. Na lista de SDKs, clique na caixa de seleção ao lado de Microsoft Engagement Framework e clique em OK.In the list of SDKs, click the check box next to Microsoft Engagement Framework and click OK.

Registrar notificações por pushRegister for push notifications

Para registrar seu aplicativo para receber notificações por push direcionadas do Partner Center:To register your app to receive targeted push notifications from Partner Center:

  1. No seu projeto, localize uma seção de código que é executado durante a inicialização em que você pode registrar seu app para receber notificações.In your project, locate a section of code that runs during startup in which you can register your app to receive notifications.

  2. Adicione a instrução a seguir na parte superior do arquivo de código.Add the following statement to the top of the code file.

    using Microsoft.Services.Store.Engagement;
    
  3. Obtenha um objeto StoreServicesEngagementManager e chame uma das sobrecargas RegisterNotificationChannelAsync no código de inicialização que você identificou anteriormente.Get a StoreServicesEngagementManager object and call one of the RegisterNotificationChannelAsync overloads in the startup code you identified earlier. Esse método deve ser chamado sempre que seu aplicativo é iniciado.This method should be called each time that your app is launched.

Observação

Quando você chama o método RegisterNotificationChannelAsync, um arquivo chamado MicrosoftStoreEngagementSDKId.txt é criado no repositório de dados de aplicativo local para o seu aplicativo (a pasta retornada pela propriedade ApplicationData.LocalFolder).When you call the RegisterNotificationChannelAsync method, a file named MicrosoftStoreEngagementSDKId.txt is created in the local app data store for your app (the folder returned by the ApplicationData.LocalFolder property). Este arquivo contém uma ID usada pela infraestrutura de notificações por push direcionadas.This file contains an ID that is used by the targeted push notifications infrastructure. Certifique-se de que seu aplicativo não modifique ou exclua esse arquivo.Make sure that your app does not modify or delete this file. Caso contrário, os usuários poderão receber várias instâncias de notificações, ou as notificações podem se comportar de outras maneiras que não sejam adequadas.Otherwise, your users may receive multiple instances of notifications, or the notifications may not behave properly in other ways.

Como as notificações por push direcionadas são roteadas para os clientesHow targeted push notifications are routed to customers

Quando o app chama RegisterNotificationChannelAsync, esse método coleta a conta da Microsoft do cliente que está atualmente conectado ao dispositivo.When your app calls RegisterNotificationChannelAsync, this method collects the Microsoft account of the customer who is currently signed in to the device. Posteriormente, quando você enviar uma notificação por push direcionada a um segmento que inclui esse cliente, o Partner Center enviará a notificação aos dispositivos associados à conta Microsoft do cliente.Later, when you send a targeted push notification to a segment that includes this customer, Partner Center sends the notification to devices that are associated with this customer's Microsoft account.

Se o cliente que iniciou o app oferecer o dispositivo para outra pessoa usar enquanto ele ainda estiver conectado ao dispositivo com a conta da Microsoft, lembre-se de que a outra pessoa poderá ver a notificação direcionada para o cliente original.If the customer who started your app gives their device to someone else to use while they are still signed in to the device with their Microsoft account, be aware that the other person may see the notification that was targeted at the original customer. Isso pode ter consequências indesejadas, especialmente para os apps que oferecem serviços aos quais os clientes podem se conectar para usar.This can have unintended consequences, particularly for apps that offer services that customers can sign in to use. Para impedir que outros usuários vejam suas notificações direcionadas neste cenário, chame o método UnregisterNotificationChannelAsync quando os clientes saírem de seu aplicativo.To prevent other users from seeing your targeted notifications in this scenario, call the UnregisterNotificationChannelAsync method when customers sign out of your app. Para saber mais, veja Cancelar registro para notificações por push posteriormente neste artigo.For more information, see Unregister for push notifications later in this article.

Como seu app responde quando o usuário inicia seu appHow your app responds when the user launches your app

Depois que seu aplicativo estiver registrado para receber notificações e você Enviar uma notificação por push para os clientes do seu aplicativo do Partner Center, um dos seguintes pontos de entrada em seu aplicativo será chamado quando o usuário iniciar seu aplicativo em resposta à sua notificação por push.After your app is registered to receive notifications and you send a push notification to your app's customers from Partner Center, one of the following entry points in your app will be called when the user launches your app in response to your push notification. Se você tiver algum código que deseja executar quando o usuário inicia seu aplicativo, adicione o código a um desses pontos de entrada em seu aplicativo.If you have some code that you want to run when the user launches your app, you can add the code to one of these entry points in your app.

  • Se a notificação por push tiver um tipo de ativação em primeiro plano, substitua o método OnActivated da classe App em seu projeto e adicione o código a esse método.If the push notification has a foreground activation type, override the OnActivated method of the App class in your project and add your code to this method.

  • Se a notificação por push tiver um tipo de ativação em segundo plano, adicione código ao método Run da sua tarefa em segundo plano.If the push notification has a background activation type, add your code to the Run method for your background task.

Por exemplo, convém recompensar os usuários do seu aplicativo que adquiriram os complementos pagos em seu aplicativo com um complemento gratuito.For example, you might want to reward the users of your app that have purchased any paid add-ons in your app by granting them a free add-on. Nesse caso, você pode enviar uma notificação por push para um segmento do cliente direcionado para esses usuários.In this case, you can send a push notification to a customer segment that targets these users. Em seguida, você pode adicionar código para conceder uma compra no aplicativo gratuita em um dos pontos de entrada listados acima.Then, you can add code to grant them a free in-app purchase in one of the entry points listed above.

Notificar o centro de parceiros sobre a inicialização do aplicativoNotify Partner Center of your app launch

Se você selecionar a opção rastrear taxa de inicialização do aplicativo para a notificação por push direcionada no Partner Center, chame o método ParseArgumentsAndTrackAppLaunch do ponto de entrada apropriado em seu aplicativo para notificar o centro de parceiros de que seu aplicativo foi iniciado em resposta a uma notificação por push.If you select the Track app launch rate option for your targeted push notification in Partner Center, call the ParseArgumentsAndTrackAppLaunch method from the appropriate entry point in your app to notify Partner Center that your app was launched in response to a push notification.

Além disso, esse método retorna os argumentos de inicialização originais para o seu app.This method also returns the original launch arguments for your app. Quando você opta por acompanhar a taxa de inicialização do aplicativo para sua notificação por push, uma ID de rastreamento opaco é adicionada aos argumentos de inicialização para ajudar a acompanhar a inicialização do aplicativo no Partner Center.When you choose to track the app launch rate for your push notification, an opaque tracking ID is added to the launch arguments to help track the app launch in Partner Center. Você deve passar os argumentos de inicialização para seu aplicativo para o método ParseArgumentsAndTrackAppLaunch , e esse método envia a ID de rastreamento para o Partner Center, remove a ID de rastreamento dos argumentos de inicialização e retorna os argumentos de inicialização originais para seu código.You must pass the launch arguments for your app to the ParseArgumentsAndTrackAppLaunch method, and this method sends the tracking ID to Partner Center, removes the tracking ID from the launch arguments, and returns the original launch arguments to your code.

A maneira como você chama esse método depende do tipo de ativação da notificação por push:The way you call this method depends on the activation type of the push notification:

  • Se a notificação por push tiver um tipo de ativação em primeiro plano, chame esse método a partir da substituição do método OnActivated em seu aplicativo e transmita os argumentos que estão disponíveis no objeto ToastNotificationActivatedEventArgs que é transmitido para esse método.If the push notification has a foreground activation type, call this method from the OnActivated method override in your app and pass the arguments that are available in the ToastNotificationActivatedEventArgs object that is passed to this method. O exemplo de código a seguir supõe que o arquivo de código tem instruções using para os namespaces Microsoft.Services.Store.Engagement e Windows.ApplicationModel.Activation.The following code example assumes that your code file has using statements for the Microsoft.Services.Store.Engagement and Windows.ApplicationModel.Activation namespaces.

    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 a notificação por push tiver um tipo de ativação em segundo plano, chame esse método a partir do método Run para sua tarefa em segundo plano e transmita os argumentos que estão disponíveis no objeto ToastNotificationActionTriggerDetail que é transmitido para esse método.If the push notification has a background activation type, call this method from the Run method for your background task and pass the arguments that are available in the ToastNotificationActionTriggerDetail object that is passed to this method. O exemplo de código a seguir supõe que seu arquivo de código tem instruções using para os namespaces Microsoft.Services.Store.Engagement, Windows.ApplicationModel.Background e Windows.UI.Notifications.The following code example assumes that your code file has using statements for the Microsoft.Services.Store.Engagement, Windows.ApplicationModel.Background, and Windows.UI.Notifications namespaces.

    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.
        }
    }
    

Cancelar registro para notificações por pushUnregister for push notifications

Se você quiser que seu aplicativo pare de receber notificações por push direcionadas do Partner Center, chame o método UnregisterNotificationChannelAsync .If you want your app to stop receiving targeted push notifications from Partner Center, call the UnregisterNotificationChannelAsync method.

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

Observe que esse método invalida o canal que está sendo usado para notificações para que o app não receba mais notificações por push de nenhum serviço.Note that this method invalidates the channel that is being used for notifications so the app no longer receives push notifications from any services. Depois que ele for fechado, o canal não poderá ser usado novamente para nenhum serviço, incluindo notificações por push direcionadas do Partner Center e outras notificações usando o WNS.After it has been closed, the channel cannot be used again for any services, including targeted push notifications from Partner Center and other notifications using WNS. Para retomar o envio de notificações por push para esse app, o app deverá solicitar um novo canal.To resume sending push notifications to this app, the app must request a new channel.