Registreringshantering

Det här avsnittet beskriver hur du registrerar enheter med meddelandehubbbar för att kunna ta emot push-meddelanden. Avsnittet beskriver registreringar på hög nivå och introducerar sedan de två huvudsakliga mönstren för att registrera enheter: registrering från enheten direkt till meddelandehubben och registrering via en program-backend.

Vad är enhetsregistrering?

Enhetsregistrering med en Notification Hub görs med hjälp av en registrering eller installation.

Registreringar

En registrering associerar PNS-referensen (Platform Notification Service) för en enhet med taggar och eventuellt en mall. PNS-referensen kan vara en ChannelURI, enhetstoken eller ett registrerings-ID för FCM. Taggar används för att dirigera meddelanden till rätt uppsättning enhetsreferenser. Mer information finns i Routning och tagguttryck. Mallar används för att implementera omvandling per registrering. Mer information finns i Mallar.

Installationer

En installation är en förbättrad registrering som innehåller en påse med push-relaterade egenskaper. Det är den senaste och bästa metoden för att registrera dina enheter med .NET SDK påserversidan (Notification Hub SDK för serveråtgärder). Du kan också använda Notification Hubs REST API för att registrera installationer på själva klientenhet. Om du använder en backend-tjänst bör du kunna använda Notification Hub SDK för backend-åtgärder.

Följande är några viktiga fördelar med att använda installationer:

• Det är helt idempotent att skapa eller uppdatera en installation. Du kan därför försöka igen utan att behöva bekymra dig om dubblettregistreringar.
• Installationsmodellen stöder ett särskilt taggformat ( $InstallationId:{INSTALLATION_ID} ) som gör det möjligt att skicka ett meddelande direkt till den specifika enheten. Om appens kod till exempel anger ett installations-ID för för den här specifika enheten kan en utvecklare rikta in sig på den här enheten när den skickar ett joe93developer meddelande till $InstallationId:{joe93developer} taggen. På så sätt kan du rikta in dig på en specifik enhet utan att behöva göra någon ytterligare kodning.
• Med hjälp av installationer kan du även göra partiella registreringsuppdateringar. Den partiella uppdateringen av en installation begärs med en PATCH-metod med hjälp av JSON-Patch-standarden. Detta är användbart när du vill uppdatera taggar för registreringen. Du behöver inte hämta hela registreringen och sedan skicka alla tidigare taggar igen.

En installation kan innehålla följande egenskaper. En fullständig lista över installationsegenskaperna finns i Skapa eller skriva över en installation med REST API eller Installationsegenskaper.

// 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: [] }
            }
        }
    }
}

Registreringar och installationer måste innehålla en giltig PNS-referens för varje enhet/kanal. Eftersom PNS-referenser endast kan hämtas i en klientapp på enheten är ett mönster att registrera direkt på enheten med klientappen. Å andra sidan kan säkerhetsöverväganden och affärslogik som rör taggar kräva att du hanterar enhetsregistrering i appens backend-enhet.

Mallar

Om du vill använda Mallar innehållerenhetsinstallationen även alla mallar som är associerade med enheten i JSON-format (se exemplet ovan). Mallnamnen hjälper dig att rikta in dig på olika mallar för samma enhet.

Varje mallnamn mappar till en malltext och en valfri uppsättning taggar. Dessutom kan varje plattform ha ytterligare mallegenskaper. För Windows Store (med WNS) och Windows Phone 8 (med MPNS) kan en ytterligare uppsättning huvuden ingå i mallen. När det gäller APNs kan du ange en förfalloegenskap till antingen en konstant eller till ett malluttryck. En fullständig lista över installationsegenskaperna finns i avsnittet Create or Overwrite an Installation with REST (Skapa eller skriva över en installation med REST).

Sekundära paneler för Windows Store-appar

För Windows Store-klientprogram är det samma sak att skicka meddelanden till sekundära paneler som att skicka dem till den primära. Detta stöds också i installationer. Sekundära paneler har en annan ChannelUri, som SDK:n i klientappen hanterar transparent.

Ordlistan SecondaryTiles använder samma TileId som används för att skapa SecondaryTiles-objektet i Windows Store-appen. Precis som med den primära ChannelUri kan ChannelUris för sekundära paneler ändras när som helst. För att hålla installationerna i meddelandehubben uppdaterade måste enheten uppdatera dem med aktuella ChannelUris för de sekundära panelerna.

Registreringshantering från enheten

När du hanterar enhetsregistrering från klientappar ansvarar endast backend för att skicka meddelanden. Klientappar håller PNS-hanterarna uppdaterade och registrerar taggar. Följande bild illustrerar det här mönstret.

Enheten hämtar först PNS-referensen från PNS och registrerar sedan direkt med meddelandehubben. När registreringen har lyckats kan app-backend skicka ett meddelande som riktar sig mot registreringen. Mer information om hur du skickar meddelanden finns i Routning och tagguttryck.

I det här fallet använder du bara lyssna-behörighet för att komma åt dina meddelandehubar från enheten. Mer information finns i Säkerhet.

Registrering från enheten är den enklaste metoden, men den har vissa nackdelar:

• En klientapp kan bara uppdatera sina taggar när appen är aktiv. Om en användare till exempel har två enheter som registrerar taggar relaterade till sportteam, och den första enheten registreras för ytterligare en tagg (till exempel Sea havens), får den andra enheten inte meddelanden om Seahaven förrän appen på den andra enheten körs en andra gång. När taggar påverkas av flera enheter är det mer allmänt önskvärt att hantera taggar från backend-enheten.
• Eftersom appar kan hackas kräver skydd av registreringen för specifika taggar extra försiktighet, enligt förklaringen i artikeln Säkerhet.

Exempelkod för registrering med en meddelandehubb från en enhet med hjälp av en installation

För närvarande stöds detta endast med hjälp av Notification Hubs REST API.

Du kan också använda PATCH-metoden med JSON-Patch-standarden för att uppdatera installationen.

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

Exempelkod för registrering med en meddelandehubb från en enhet med hjälp av en registrering

Dessa metoder skapar eller uppdaterar en registrering för den enhet som de anropas på. Det innebär att du måste skriva över hela registreringen för att kunna uppdatera referensen eller taggarna. Kom ihåg att registreringar är tillfälliga, så du bör alltid ha ett tillförlitligt arkiv med de aktuella taggar som en specifik enhet behöver.

// 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");
}

Registreringshantering från en backend

Hantering av registreringar från backend kräver att du skriver ytterligare kod. Appen från enheten måste tillhandahålla den uppdaterade PNS-referensen till backend varje gång appen startar (tillsammans med taggar och mallar), och backend-enheten måste uppdatera den här referensen på meddelandehubben. Följande bild illustrerar den här designen.

Fördelarna med att hantera registreringar från backend-servern är möjligheten att ändra taggar till registreringar även när motsvarande app på enheten är inaktiv och att autentisera klientappen innan du lägger till en tagg i registreringen.

Exempelkod för registrering med en meddelandehubb från en backend med hjälp av en installation

Klientenhet får fortfarande sin PNS-referens och relevanta installationsegenskaper som tidigare och anropar ett anpassat API på backend som kan utföra registreringen och auktorisera taggar osv. Backend kan använda Notification Hub SDK för backend-åtgärder.

Du kan också använda PATCH-metoden med JSON-Patch-standarden för att uppdatera installationen.

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

Exempelkod för registrering med en meddelandehubb från en enhet med ett registrerings-ID

Från din app-backend kan du utföra grundläggande CRUDS-åtgärder på registreringar. Exempel:

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

Backend måste hantera samtidighet mellan registreringsuppdateringar. Service Bus erbjuder optimistisk samtidighetskontroll för registreringshantering. På HTTP-nivå implementeras detta med hjälp av ETag för registreringshanteringsåtgärder. Den här funktionen används transparent av MicrosoftSDK:er, vilket visar ett undantag om en uppdatering avvisas av samtidighetsskäl. App-backend ansvarar för att hantera dessa undantag och försöka uppdatera igen om det behövs.