Registratiebeheer

In dit onderwerp wordt uitgelegd hoe u apparaten registreert bij Notification Hubs om pushmeldingen te ontvangen. Het onderwerp beschrijft registraties op hoog niveau en introduceert vervolgens de twee belangrijkste patronen voor het registreren van apparaten: registratie vanaf het apparaat rechtstreeks bij de Notification Hub en registratie via een toepassingsback-up.

Wat is apparaatregistratie?

Apparaatregistratie met een Notification Hub wordt bereikt met behulp van een registratie of installatie.

Registraties

Een registratie koppelt de PNS-handle (Platform Notification Service) voor een apparaat aan tags en mogelijk een sjabloon. De PNS-handle kan een ChannelURI, apparaat-token of FCM-registratie-id zijn. Tags worden gebruikt om meldingen naar de juiste set apparaating handles te sturen. Zie Routering en tagexpressie voor meer informatie. Sjablonen worden gebruikt om transformatie per registratie te implementeren. Zie Sjablonen voor meer informatie.

Installaties

Een installatie is een verbeterde registratie die een zak push-gerelateerde eigenschappen bevat. Dit is de nieuwste en beste methode voor het registreren van uw apparaten met behulp van de .NET SDK aan de serverzijde(Notification Hub SDK voor back-upbewerkingen). U kunt ook de Notification Hubs REST API gebruiken om installaties op het clientapparaat zelf te registreren. Als u een back-upservice gebruikt, kunt u de Notification Hub SDK gebruiken voor back-upbewerkingen.

Hier volgen enkele belangrijke voordelen van het gebruik van installaties:

• Het maken of bijwerken van een installatie is volledig idempotent. U kunt het dus opnieuw proberen zonder dat u zich zorgen maakt over dubbele registraties.
• Het installatiemodel ondersteunt een speciale tagindeling ( ) waarmee een melding rechtstreeks naar $InstallationId:{INSTALLATION_ID} het specifieke apparaat kan worden verzonden. Als met de code van de app bijvoorbeeld een installatie-id van wordt bepaald voor dit specifieke apparaat, kan een ontwikkelaar dit apparaat als doel nemen bij het verzenden van een melding joe93developer naar de $InstallationId:{joe93developer} tag. Hiermee kunt u zich richten op een specifiek apparaat zonder dat u extra code hoeft te schrijven.
• Met installaties kunt u ook gedeeltelijke registratie-updates doen. De gedeeltelijke update van een installatie wordt aangevraagd met een PATCH-methode met behulp van de JSON-Patch-standaard. Dit is handig als u tags voor de registratie wilt bijwerken. U hoeft niet de hele registratie op te halen en vervolgens alle vorige tags opnieuw te importeren.

Een installatie kan de volgende eigenschappen bevatten. Zie Een installatie maken of overschrijven met een REST API of Installatie-eigenschappen voor een volledige lijst van de installatie-eigenschappen.

// Example installation format to show some supported properties
{
    installationId: "",
    expirationTime: "",
    tags: [],
    platform: "",
    pushChannel: "",
    ………
    templates: {
        "templateName1" : {
            body: "",
            tags: [] },
        "templateName2" : {
            body: "",
            // Headers are for Windows Store only
            headers: {
                "X-WNS-Type": "wns/tile" }
            tags: [] }
    },
    secondaryTiles: {
        "tileId1": {
            pushChannel: "",
            tags: [],
            templates: {
                "otherTemplate": {
                    bodyTemplate: "",
                    headers: {
                        ... }
                    tags: [] }
            }
        }
    }
}

Registraties en installaties moeten een geldige PNS-handle bevatten voor elk apparaat/kanaal. Omdat PNS-grepen alleen kunnen worden verkregen in een client-app op het apparaat, is een patroon om zich rechtstreeks op dat apparaat te registreren met de client-app. Aan de andere kant is het mogelijk dat u voor beveiligingsoverwegingen en bedrijfslogica met betrekking tot tags apparaatregistratie in de back-end van de app moet beheren.

Sjablonen

Als u Sjablonen wilt gebruiken,bevat de installatie van het apparaat ook alle sjablonen die aan dat apparaat zijn gekoppeld in een JSON-indeling (zie het bovenstaande voorbeeld). Met de sjabloonnamen kunt u zich richten op verschillende sjablonen voor hetzelfde apparaat.

Elke sjabloonnaam wordt toe te voegen aan een sjabloon-body en een optionele set tags. Bovendien kan elk platform aanvullende sjablooneigenschappen hebben. Voor Windows Store (met WNS) en Windows Phone 8 (met MPNS) kan een extra set headers deel uitmaken van de sjabloon. In het geval van APNs kunt u een verloop-eigenschap instellen op een constante of op een sjabloonexpressie. Zie het onderwerp Een installatie met REST maken of overschrijven voor een volledig overzicht van de installatie-eigenschappen.

Secundaire tegels voor Windows Store-apps

Voor Windows Store-clienttoepassingen is het verzenden van meldingen naar secundaire tegels hetzelfde als het verzenden ervan naar de primaire. Dit wordt ook ondersteund in installaties. Secundaire tegels hebben een andere ChannelUri, die transparant wordt verwerkt door de SDK in uw client-app.

De woordenlijst SecondaryTiles maakt gebruik van dezelfde TileId die wordt gebruikt voor het maken van het object SecondaryTiles in uw Windows Store-app. Net als bij de primaire ChannelUri kunnen ChannelUri's van secundaire tegels op elk moment worden gewijzigd. Om de installaties in de Notification Hub bijgewerkt te houden, moet het apparaat ze vernieuwen met de huidige ChannelUris van de secundaire tegels.

Registratiebeheer vanaf het apparaat

Bij het beheren van apparaatregistratie vanuit client-apps is de back-end alleen verantwoordelijk voor het verzenden van meldingen. Client-apps houden PNS up-to-date en registreren tags. In de volgende afbeelding ziet u dit patroon.

Het apparaat haalt eerst de PNS-handle van de PNS op en registreert deze vervolgens rechtstreeks bij de Notification Hub. Nadat de registratie is geslaagd, kan de back-up van de app een melding verzenden die gericht is op die registratie. Zie Routering en tagexpressie voor meer informatie over het verzenden van meldingen.

In dit geval gebruikt u alleen listen-rechten voor toegang tot uw Notification Hubs vanaf het apparaat. Zie Beveiliging voor meer informatie.

Registreren vanaf het apparaat is de eenvoudigste methode, maar het heeft enkele nadelen:

• Een client-app kan de tags alleen bijwerken wanneer de app actief is. Als een gebruiker bijvoorbeeld twee apparaten heeft die tags registreren die betrekking hebben op sportteams, ontvangt het tweede apparaat pas meldingen over de Seatags wanneer het eerste apparaat wordt geregistreerd voor een extra tag (bijvoorbeeld Seatags). Het tweede apparaat ontvangt pas meldingen over de Seatags als de app op het tweede apparaat een tweede keer wordt uitgevoerd. Wanneer tags worden beïnvloed door meerdere apparaten, is het beheren van tags vanaf de back-end over het algemeen een wenselijke optie.
• Omdat apps kunnen worden gehackt, is voor het beveiligen van de registratie bij specifieke tags extra aandacht vereist,zoals wordt uitgelegd in het artikel Beveiliging .

Voorbeeldcode voor registratie bij een Notification Hub vanaf een apparaat met behulp van een installatie

Op dit moment wordt dit alleen ondersteund met behulp van de Notification Hubs REST API.

U kunt ook de PATCH-methode gebruiken met behulp van de JSON-Patch-standaard voor het bijwerken van de installatie.

class DeviceInstallation
{
    public string installationId { get; set; }
    public string platform { get; set; }
    public string pushChannel { get; set; }
    public string[] tags { get; set; }

    private async Task<HttpStatusCode> CreateOrUpdateInstallationAsync(DeviceInstallation deviceInstallation,
        string hubName, string listenConnectionString)
    {
        if (deviceInstallation.installationId == null)
            return HttpStatusCode.BadRequest;

        // Parse connection string (https://msdn.microsoft.com/library/azure/dn495627.aspx)
        ConnectionStringUtility connectionSaSUtil = new ConnectionStringUtility(listenConnectionString);
        string hubResource = "installations/" + deviceInstallation.installationId + "?";
        string apiVersion = "api-version=2015-04";

        // Determine the targetUri that we will sign
        string uri = connectionSaSUtil.Endpoint + hubName + "/" + hubResource + apiVersion;

        //=== Generate SaS Security Token for Authorization header ===
        // See https://msdn.microsoft.com/library/azure/dn495627.aspx
        string SasToken = connectionSaSUtil.getSaSToken(uri, 60);

        using (var httpClient = new HttpClient())
        {
            string json = JsonConvert.SerializeObject(deviceInstallation);

            httpClient.DefaultRequestHeaders.Add("Authorization", SasToken);

            var response = await httpClient.PutAsync(uri, new StringContent(json, System.Text.Encoding.UTF8, "application/json"));
            return response.StatusCode;
        }
    }

    var channel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();

    string installationId = null;
    var settings = ApplicationData.Current.LocalSettings.Values;

    // If we have not stored an installation ID in application data, create and store as application data.
    if (!settings.ContainsKey("__NHInstallationId"))
    {
        installationId = Guid.NewGuid().ToString();
        settings.Add("__NHInstallationId", installationId);
    }

    installationId = (string)settings["__NHInstallationId"];

    var deviceInstallation = new DeviceInstallation
    {
        installationId = installationId,
        platform = "wns",
        pushChannel = channel.Uri,
        //tags = tags.ToArray<string>()
    };

    var statusCode = await CreateOrUpdateInstallationAsync(deviceInstallation, 
                    "<HUBNAME>", "<SHARED LISTEN CONNECTION STRING>");

    if (statusCode != HttpStatusCode.Accepted)
    {
        var dialog = new MessageDialog(statusCode.ToString(), "Registration failed. Installation Id : " + installationId);
        dialog.Commands.Add(new UICommand("OK"));
        await dialog.ShowAsync();
    }
    else
    {
        var dialog = new MessageDialog("Registration successful using installation Id : " + installationId);
        dialog.Commands.Add(new UICommand("OK"));
        await dialog.ShowAsync();
    }
}

Voorbeeldcode voor registratie bij een Notification Hub vanaf een apparaat met behulp van een registratie

Met deze methoden kunt u een registratie maken of bijwerken voor het apparaat waarop ze worden aangeroepen. Dit betekent dat u de volledige registratie moet overschrijven om de handle of de tags bij te werken. Houd er wel voor dat registraties tijdelijk zijn, dus u moet altijd een betrouwbare opslag hebben met de huidige tags die een specifiek apparaat nodig heeft.

// Initialize the Notification Hub
NotificationHubClient hub = NotificationHubClient.CreateClientFromConnectionString(listenConnString, hubName);

// The Device ID from the PNS
var pushChannel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();

// If you are registering from the client itself, then store this registration ID in device
// storage. Then when the app starts, you can check if a registration ID already exists or not before
// creating.
var settings = ApplicationData.Current.LocalSettings.Values;

// If we have not stored a registration ID in application data, store in application data.
if (!settings.ContainsKey("__NHRegistrationId"))
{
    // make sure there are no existing registrations for this push handle (used for iOS and Android)    
    string newRegistrationId = null;
    var registrations = await hub.GetRegistrationsByChannelAsync(pushChannel.Uri, 100);
    foreach (RegistrationDescription registration in registrations)
    {
        if (newRegistrationId == null)
        {
            newRegistrationId = registration.RegistrationId;
        }
        else
        {
            await hub.DeleteRegistrationAsync(registration);
        }
    }

    newRegistrationId = await hub.CreateRegistrationIdAsync();

    settings.Add("__NHRegistrationId", newRegistrationId);
}

string regId = (string)settings["__NHRegistrationId"];

RegistrationDescription registration = new WindowsRegistrationDescription(pushChannel.Uri);
registration.RegistrationId = regId;
registration.Tags = new HashSet<string>(YourTags);

try
{
    await hub.CreateOrUpdateRegistrationAsync(registration);
}
catch (Microsoft.WindowsAzure.Messaging.RegistrationGoneException e)
{
    settings.Remove("__NHRegistrationId");
}

Registratiebeheer vanuit een back-end

Voor het beheren van registraties vanuit de back-end is extra code vereist. De app van het apparaat moet telkens wanneer de app wordt gestart (samen met tags en sjablonen) de bijgewerkte PNS-handle aan de back-up leveren. De back-up moet deze handle bijwerken op de Notification Hub. In de volgende afbeelding ziet u dit ontwerp.

De voordelen van het beheren van registraties vanuit de back-end zijn de mogelijkheid om tags aan registraties te wijzigen, zelfs wanneer de bijbehorende app op het apparaat inactief is, en om de client-app te verifiëren voordat een tag aan de registratie wordt toegevoegd.

Voorbeeldcode voor registratie bij een Notification Hub vanaf een back-end met behulp van een installatie

Het clientapparaat krijgt nog steeds de PNS-handle en relevante installatie-eigenschappen zoals voorheen en roept een aangepaste API aan op de back-end die de registratie kan uitvoeren en tags kan autoreren, enzovoort. De back-up kan gebruikmaken van de Notification Hub SDK voor back-upbewerkingen.

U kunt ook de PATCH-methode gebruiken met behulp van de JSON-Patch-standaard voor het bijwerken van de installatie.

// Initialize the Notification Hub
NotificationHubClient hub = NotificationHubClient.CreateClientFromConnectionString(listenConnString, hubName);

// Custom API on the backend
public async Task<HttpResponseMessage> Put(DeviceInstallation deviceUpdate)
{

    Installation installation = new Installation();
    installation.InstallationId = deviceUpdate.InstallationId;
    installation.PushChannel = deviceUpdate.Handle;
    installation.Tags = deviceUpdate.Tags;

    switch (deviceUpdate.Platform)
    {
        case "mpns":
            installation.Platform = NotificationPlatform.Mpns;
            break;
        case "wns":
            installation.Platform = NotificationPlatform.Wns;
            break;
        case "apns":
            installation.Platform = NotificationPlatform.Apns;
            break;
        case "fcm":
            installation.Platform = NotificationPlatform.Fcm;
            break;
        default:
            throw new HttpResponseException(HttpStatusCode.BadRequest);
    }


    // In the backend we can control if a user is allowed to add tags
    //installation.Tags = new List<string>(deviceUpdate.Tags);
    //installation.Tags.Add("username:" + username);

    await hub.CreateOrUpdateInstallationAsync(installation);

    return Request.CreateResponse(HttpStatusCode.OK);
}

Voorbeeldcode voor registratie bij een Notification Hub vanaf een apparaat met behulp van een registratie-id

Vanuit uw app-back-end kunt u eenvoudige CRUDS-bewerkingen uitvoeren op registraties. Bijvoorbeeld:

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);

De back-end moet gelijktijdigheid tussen registratie-updates verwerken. Service Bus biedt optimistisch gelijktijdigheidsbeheer voor registratiebeheer. Op HTTP-niveau wordt dit geïmplementeerd met het gebruik van ETag voor registratiebeheerbewerkingen. Deze functie wordt transparant gebruikt door Microsoft SDK's, die een uitzondering vormen als een update wordt geweigerd om gelijktijdigheidsredenen. De app-back-en is verantwoordelijk voor het afhandelen van deze uitzonderingen en het indien nodig opnieuw proberen van de update.