Configurar seu aplicativo para notificações por push direcionadas

  • Artigo

Você pode usar a página Notificações por push no Partner Center para interagir diretamente com os clientes enviando notificações por push direcionadas para os dispositivos nos quais seu aplicativo Plataforma Universal do Windows (UWP) está instalado. 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. 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. Você também pode controlar a taxa de inicializações do aplicativo resultantes de suas notificações por push. Para obter mais informações sobre esse recurso, consulte Enviar notificações por push para clientes do seu aplicativo.

Antes de enviar notificações por push direcionadas para seus clientes do Partner Center, você deve usar um método da classe StoreServicesEngagementManager no Microsoft Store Services SDK para registrar seu aplicativo para receber notificações. Você pode usar métodos adicionais dessa classe para notificar o Partner Center de que seu aplicativo foi iniciado em resposta a uma notificação por push direcionada (se você quiser acompanhar a taxa de inicializações de aplicativos resultantes de suas notificações) e parar de receber notificações.

Configurar seu projeto

Antes de gravar qualquer código, siga estas etapas para adicionar uma referência ao Microsoft Store Services SDK no seu projeto:

  1. Se você ainda não fez isso, instale o Microsoft Store Services SDK no computador de desenvolvimento.
  2. Abra o projeto no 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.
  4. No Gerenciador de Referências, expanda Universal do Windows e clique em Extensões.
  5. Na lista de SDKs, clique na caixa de seleção ao lado de Microsoft Engagement Framework e clique em OK.

Registrar notificações por push

Para registrar seu aplicativo para receber notificações por push direcionadas do 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.

  2. Adicione a instrução a seguir na parte superior do arquivo de código.

    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. Esse método deve ser chamado sempre que seu aplicativo é iniciado.

  • Se você quiser que o Partner Center crie seu próprio URI de canal para as notificações, chame a sobrecarga RegisterNotificationChannelAsync( ).

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

    Importante

    Se o seu aplicativo também chama o CreatePushNotificationChannelForApplicationAsync para criar um canal de notificações para WNS, certifique-se de que o seu código não chama as sobrecargas CreatePushNotificationChannelForApplicationAsync e RegisterNotificationChannelAsync() simultaneamente. Se você precisar chamar esses dois métodos, chame-os sequencialmente e espere o retorno de um método antes de chamar o outro.

  • Se você quiser especificar o URI do canal a ser usado para notificações por push direcionadas do Partner Center, chame a sobrecarga RegisterNotificationChannelAsync(StoreServicesNotificationChannelParameters). Por exemplo, talvez queira fazer isso se seu aplicativo já usa o Serviço de Notificação por Push do Windows (WNS) e você quer usar o mesmo URI do canal. Você deve primeiro criar um objeto StoreServicesNotificationChannelParameters e atribuir a propriedade CustomNotificationChannelUri ao URI de canal.

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

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

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). Este arquivo contém uma ID usada pela infraestrutura de notificações por push direcionadas. Certifique-se de que seu aplicativo não modifique ou exclua esse arquivo. 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.

Como as notificações por push direcionadas são roteadas para os clientes

Quando o app chama RegisterNotificationChannelAsync, esse método coleta a conta da Microsoft do cliente que está atualmente conectado ao dispositivo. Posteriormente, quando você envia uma notificação por push direcionada para um segmento que inclui esse cliente, o Partner Center envia a notificação para dispositivos associados à conta Microsoft desse cliente.

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. Isso pode ter consequências indesejadas, especialmente para os apps que oferecem serviços aos quais os clientes podem se conectar para usar. 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. Para saber mais, veja Cancelar registro para notificações por push posteriormente neste artigo.

Como seu app responde quando o usuário inicia seu app

Depois que seu aplicativo for registrado para receber notificações e você enviar uma notificação por push aos 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 à notificação por push. 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.

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

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

Por exemplo, convém recompensar os usuários do seu aplicativo que adquiriram os complementos pagos em seu aplicativo com um complemento gratuito. Nesse caso, você pode enviar uma notificação por push para um segmento do cliente direcionado para esses usuários. Em seguida, você pode adicionar código para conceder uma compra no aplicativo gratuita em um dos pontos de entrada listados acima.

Notificar o Partner Center sobre a inicialização do aplicativo

Se você selecionar a opção Controlar 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 Partner Center de que seu aplicativo foi iniciado em resposta a uma notificação por push.

Além disso, esse método retorna os argumentos de inicialização originais para o seu app. Quando você opta por acompanhar a taxa de inicialização do aplicativo para sua notificação por push, uma ID de acompanhamento opaca é adicionada aos argumentos de inicialização para ajudar a acompanhar a inicialização do aplicativo no Partner Center. Você deve passar os argumentos de inicialização do 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 o código.

A maneira como você chama esse método depende do tipo de ativação da notificação por push:

  • 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. O exemplo de código a seguir pressupõe que o arquivo de código tenha instruções using para os namespaces 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 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. 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.

    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 push

Se você quiser que seu aplicativo pare de receber notificações por push direcionadas do Partner Center, chame o método UnregisterNotificationChannelAsync .

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. Depois de 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. Para retomar o envio de notificações por push para esse app, o app deverá solicitar um novo canal.