Gerenciamento de registros

Este tópico explica como registrar dispositivos em hubs de notificação para receber notificações por push. O tópico descreve os registros em alto nível e, em seguida, apresenta os dois padrões principais para registrar dispositivos: registrar-se do dispositivo diretamente no hub de notificação e registrar-se por meio do back-end do aplicativo.

O que é um registro de dispositivo

Um registro é uma sub-entidade de um hub de notificação e associa um identificador PNS do dispositivo (um identificador do Serviço de Notificação de Plataforma, por exemplo, ChannelURI, token de dispositivo, GCM registrationId) com marcas e possivelmente um modelo. As marcas são usadas para direcionar notificações para o conjunto correto de identificadores de dispositivos. Para saber mais, veja Expressões de marca e de roteamento. Os modelos são usados para implementar transformações por registro. Para saber mais, veja Modelos.

É importante observar que os registros são transitórios. Semelhante aos identificadores PNS que eles contêm, os registros expiram. Você pode definir o tempo de vida útil para um registro no Hub de Notificação, até um máximo de 90 dias. Esse limite significa que eles devem ser atualizados periodicamente e também que não devem ser o único repositório para informações importantes. Essa expiração automática também simplifica a limpeza quando seu aplicativo móvel é desinstalado.

Os registros devem conter o identificador PNS mais recente para cada dispositivo/canal. Como os identificadores PNS só podem ser obtidos no aplicativo cliente no dispositivo, uma maneira de gerenciar registros é diretamente nesse aplicativo cliente. Por outro lado, considerações de segurança e lógica de negócios relacionadas a marcas podem exigir que você gerencie o registro no back-end do aplicativo. A seção a seguir descreve essas duas abordagens.

Gerenciamento de registro do dispositivo

Ao gerenciar registros de aplicativos cliente, o back-end só é responsável pelo envio de notificações. Os aplicativos cliente mantêm os identificadores PNS atualizados e registram-se em marcas. A figura a seguir ilustra esse padrão.

Primeiro, o dispositivo recupera o identificador PNS do PNS e registra diretamente com o hub de notificação. Após a conclusão do registro, o back-end do aplicativo pode enviar uma notificação visando esse registro. Para saber mais sobre como enviar notificações, veja Expressões de marca e de roteamento.

Observe que, nesse caso, você usará apenas direitos de Escuta para acessar os hubs de notificação do dispositivo. Para saber mais, consulte Segurança.

O código a seguir registra seu dispositivo usando referências de API dos Hubs de Notificação:

await hub.RegisterNativeAsync(channelUri, tags);

[hub registerNativeWithDeviceToken:deviceToken tags:nil completion:^(NSError* error) {
    if (error != nil) {
        NSLog(@"Error registering for notifications: %@", error);
    }
}];

hub.register(regid, tags);

Esses métodos criam ou atualizam um registro para o dispositivo no qual são chamados. Isso significa que, para atualizar o indicador ou as marcas, você deve substituir todo o registro. Lembre-se de que os registros são transitórios, portanto, você deve sempre ter um repositório confiável (armazenamento local no dispositivo ou no back-end do aplicativo) com as marcas atuais de que um dispositivo específico precisa. Consulte o tutorial últimas notícias para obter exemplos mais detalhados de como atualizar registros.

Você também pode usar as APIs REST para se registrar no dispositivo. Para obter mais informações, consulte Como usar a interface REST dos Hubs de Notificação.

Os tutoriais de cenário a seguir fornecem diretrizes passo a passo sobre o registro do cliente:

• Introdução com Hubs de Notificação

• Notícia em primeira mão

Modelos

Se você quiser usar Modelos, cada registro representa um modelo individual. Isso significa que, se o dispositivo usa dois modelos, você deve registrar cada modelo de forma independente com seu próprio identificador PNS e conjunto de marcas.

Para registros nativos (ou seja, sem um modelo), os métodos de registro para modelos criam ou atualizam registros existentes. Para direcionar modelos diferentes, você fornece um nome de modelo ao se registrar. Você fornecerá nomes diferentes se quiser manter vários modelos para o mesmo dispositivo.

Importante

Ao usar modelos, você não precisa registrar seu dispositivo, conforme mostrado na seção anterior. Esse registro só será usado se você enviar notificações nativas (notificações enviadas em um formato específico da plataforma).

O código a seguir registra seu dispositivo usando referências de API dos Hubs de Notificação:

await hub.RegisterTemplateAsync(channelUri, template, templateName, tags);

[hub registerTemplateWithDeviceToken:deviceToken name:templateName jsonBodyTemplate: template expiryTemplate:nil tags:nil completion:^(NSError* error) {
    if (error != nil) {
        NSLog(@"Error registering for notifications: %@", error);
    }
}];

hub.registerTemplate(regId, templateName, template, tags);

Observe que cada chamada de registro fornece, além do identificador PNS e do conjunto opcional de marcas, um modelo para o corpo da notificação e um nome para o modelo. Além disso, cada plataforma pode ter propriedades adicionais que fazem parte do modelo. No caso de Windows Store (usando WNS) e Windows Phone 8 (usando MPNS), um conjunto adicional de cabeçalhos pode fazer parte do modelo. No caso dos APNs, você pode definir uma propriedade de expiração para uma constante ou para uma expressão de modelo.

Para obter instruções sobre como modificar esses campos de modelo, consulte AS APIs REST de Referências de API ou Hubs de Notificação.

Blocos secundários para aplicativos da Windows Store

Para aplicativos cliente da Windows Store, o envio de notificações para blocos secundários é igual ao envio delas ao bloco primário. Há suporte para registros nativos e de modelo. A única diferença é que os blocos secundários têm um ChannelUri diferente, que o SDK em seu aplicativo cliente manipula de forma transparente.

Em um alto nível, todas as informações fornecidas nas seções anteriores funcionam com blocos secundários chamando os métodos correspondentes nos objetos expostos na propriedade de dicionário Microsoft.WindowsAzure.Messaging.NotificationHub.SecondaryTiles. Por exemplo:

await hub.SecondaryTiles["myTileId"].RegisterNativeAsync(new string[] {"Yankees"});
await hub.SecondaryTiles["myTileId"].RegisterTemplateAsync(buildToastTemplate(), "toastTemplate", new string[] {"RedSox"});

O dicionário SecondaryTiles usa a mesma TileId usada para criar o objeto SecondaryTiles em seu aplicativo Windows Store.

Assim como acontece com o ChannelUri primário, os ChannelUris de blocos secundários podem ser alterados a qualquer momento. Para manter os registros do aplicativo cliente no hub de notificação atualizados, o dispositivo deve atualizá-los com os ChannelUris atuais dos blocos secundários.

Observação

Você pode excluir blocos secundários quando o aplicativo estiver inativo. Os registros correspondentes não resultarão em notificações e serão excluídos automaticamente pelos hubs de notificação.

Desvantagens de registro do dispositivo

O registro do dispositivo é o método mais simples, mas tem algumas desvantagens.

A primeira desvantagem é que um aplicativo cliente só pode atualizar suas marcas quando está ativo. Por exemplo, se um usuário tiver dois dispositivos que registram marcas relacionadas a equipes esportivas, quando o primeiro dispositivo registrar uma marca adicional (por exemplo, Seahawks), o segundo dispositivo não receberá as notificações sobre o Seahawks até que o aplicativo no segundo dispositivo seja executado uma segunda vez. Normalmente, quando as marcas são afetadas por vários dispositivos, o gerenciamento das marcas do back-end é uma opção desejável.

A segunda desvantagem do gerenciamento de registro do aplicativo cliente é que, como os aplicativos podem ser violados, a proteção do registro para marcas específicas exige um cuidado extra, conforme explicado na seção "Segurança no nível da marca".

Gerenciamento de Registro do Back-end do Aplicativo

O gerenciamento de registros do back-end exige a produção adicional de código. O aplicativo do dispositivo deve fornecer o identificador PNS atualizado para o back-end sempre que o aplicativo for iniciado (juntamente com marcas e modelos), e o back-end deve atualizar esse identificador no Barramento de Serviço. A figura a seguir ilustra esse design.

As vantagens de gerenciar registros do back-end são a capacidade de modificar marcas para registros mesmo quando o aplicativo correspondente no dispositivo estiver inativo e autenticar o aplicativo cliente antes de adicionar uma marca ao seu registro.

No back-end do aplicativo, você pode executar operações básicas de CRUDS nos registros. Por exemplo:

var hub = NotificationHubClient.CreateClientFromConnectionString("{connectionString}", "hubName");
            
// create a registration description object of the correct type, e.g.
var reg = new WindowsRegistrationDescription(channelUri, tags);

// Create
await hub.CreateRegistrationAsync(reg);

// Get by id
var r = await hub.GetRegistrationAsync<RegistrationDescription>("id");

// update
r.Tags.Add("myTag");

// update on hub
await hub.UpdateRegistrationAsync(r);

// delete
await hub.DeleteRegistrationAsync(r);

Você também pode usar o Nó ou as APIs REST.

Importante

O back-end deve manipular a simultaneidade entre as atualizações do registro. O Barramento de Serviço oferece um controle de simultaneidade otimista para gerenciamento de registro. No nível HTTP, isso é implementado com o uso da ETag em operações de gerenciamento de registro. Esse recurso é usado de forma transparente pelos SDKs da Microsoft, que lançam uma exceção se uma atualização for rejeitada por motivos de simultaneidade. O back-end é responsável por manipular essas exceções e tentar atualizar novamente, se isso for necessário.

Recursos adicionais

Os tutoriais de cenário a seguir fornecem diretrizes passo a passo sobre como se registrar no back-end do aplicativo:

• Usar marcas para enviar notificações para usuários autenticados

• Usar modelos para enviar notificações multiplataforma para usuários autenticados