Správa registrací

Toto téma vysvětluje, jak zaregistrovat zařízení v centru oznámení, aby bylo možné přijímat nabízená oznámení. Toto téma popisuje registrace na vysoké úrovni a pak představuje dva hlavní vzory pro registraci zařízení: registraci ze zařízení přímo do centra oznámení a registraci prostřednictvím back-endu aplikace.

Co je registrace zařízení

Registrace zařízení v centru oznámení se provádí pomocí registrace nebo instalace.

Registrace

Registrace přidruží popisovač PNS (Platform Notification Service) pro zařízení se značkami a případně i šablonou. Popisovač PNS může být Identifikátor ChannelURI, token zařízení nebo ID registrace FCM. Značky slouží ke směrování oznámení do správné sady popisovačů zařízení. Další informace najdete v tématu Směrování a výrazy značek. Šablony se používají k implementaci transformace podle registrace. Další informace najdete v tématu Šablony.

Poznámka

Azure Notification Hubs podporuje maximálně 60 značek na zařízení.

Instalace

Instalace je rozšířená registrace, která obsahuje pytel vlastností souvisejících s push. Jedná se o nejnovější a nejlepší přístup k registraci zařízení pomocí sady .NET SDK na straně serveru (notification hub SDK pro back-endové operace). K registraci instalací na samotném klientském zařízení můžete použít také přístup k rozhraní REST API služby Notification Hubs . Pokud používáte back-endovou službu, měli byste být schopni používat sadu SDK centra oznámení pro back-endové operace.

Tady jsou některé klíčové výhody používání instalací:

• Vytvoření nebo aktualizace instalace je plně idempotentní. Takže to můžete zkusit znovu bez obav z duplicitních registrací.
• Model instalace podporuje speciální formát značky ($InstallationId:{INSTALLATION_ID}), který umožňuje odesílat oznámení přímo do konkrétního zařízení. Pokud například kód aplikace nastaví ID joe93developer instalace pro toto konkrétní zařízení, může vývojář při odesílání oznámení do značky $InstallationId:{joe93developer} na toto zařízení cílit. Díky tomu můžete cílit na konkrétní zařízení, aniž byste museli provádět další kódování.
• Použití instalací také umožňuje provádět částečné aktualizace registrace. Částečná aktualizace instalace je vyžadována metodou PATCH pomocí standardu JSON-Patch. To je užitečné, když chcete aktualizovat značky při registraci. Nemusíte stahovat dolů celou registraci a pak znovu odeslat všechny předchozí značky.

Instalace může obsahovat následující vlastnosti. Úplný seznam vlastností instalace najdete v tématu Vytvoření nebo přepsání instalace pomocí rozhraní REST API nebo Vlastnosti instalace.

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

Poznámka

Ve výchozím nastavení platnost registrací a instalací nevyprší.

Registrace a instalace musí obsahovat platný popisovač PNS pro každé zařízení nebo kanál. Vzhledem k tomu, že popisovače PNS je možné získat jenom v klientské aplikaci na zařízení, jedním ze vzorů je registrace přímo na daném zařízení v klientské aplikaci. Na druhou stranu bezpečnostní aspekty a obchodní logika související se značkami můžou vyžadovat správu registrace zařízení v back-endu aplikace.

Poznámka

Rozhraní API pro instalaci nepodporuje službu Baidu (i když rozhraní API pro registrace ano).

Šablony

Poznámka

Služba MPNS (Microsoft Push Notification Service) je zastaralá a už se nepodporuje.

Pokud chcete použít šablony, instalace zařízení obsahuje také všechny šablony přidružené k danému zařízení ve formátu JSON (viz ukázka výše). Názvy šablon pomáhají cílit na různé šablony pro stejné zařízení.

Každý název šablony se mapuje na tělo šablony a volitelnou sadu značek. Každá platforma navíc může mít další vlastnosti šablony. Pro Windows Store (pomocí WNS) a Windows Phone 8 (pomocí MPNS) může být součástí šablony další sada hlaviček. V případě služby APNs můžete nastavit vlastnost vypršení platnosti na konstantu nebo na výraz šablony. Úplný seznam vlastností instalace najdete v tématu Vytvoření nebo přepsání instalace pomocí REST .

Sekundární dlaždice pro aplikace pro Windows Store

U klientských aplikací pro Windows Store je odesílání oznámení na sekundární dlaždice stejné jako jejich odesílání na primární dlaždici. To je také podporováno v instalacích. Sekundární dlaždice mají jiný identifikátor ChannelUri, který sada SDK ve vaší klientské aplikaci transparentně zpracovává.

Slovník SecondaryTiles používá stejné TileId, které se používá k vytvoření objektu SecondaryTiles v aplikaci pro Windows Store. Stejně jako u primárního Identifikátoru ChannelUri se můžou identifikátory ChannelUri sekundárních dlaždic kdykoli změnit. Aby bylo možné udržovat instalace v centru oznámení aktualizované, musí je zařízení aktualizovat pomocí aktuálních identifikátorů ChannelUris sekundárních dlaždic.

Správa registrace ze zařízení

Při správě registrace zařízení z klientských aplikací zodpovídá back-end pouze za odesílání oznámení. Klientské aplikace udržují obslužné rutiny PNS aktuální a registrují značky. Tento vzor znázorňuje následující obrázek.

Zařízení nejprve načte popisovač PNS z PNS a pak se zaregistruje přímo v centru oznámení. Po úspěšné registraci může back-end aplikace odeslat oznámení, které cílí na danou registraci. Další informace o tom, jak odesílat oznámení, najdete v tématu Směrování a výrazy značek.

V takovém případě pro přístup k centru oznámení ze zařízení použijete jenom práva na naslouchání. Další informace najdete v tématu Zabezpečení.

Registrace ze zařízení je nejjednodušší metoda, ale má některé nevýhody:

• Klientská aplikace může aktualizovat své značky, jenom když je aplikace aktivní. Pokud má například uživatel dvě zařízení, která registrují značky související se sportovními týmy, když první zařízení zaregistruje další značku (například Seahawks), druhé zařízení nebude dostávat oznámení o Seahawks, dokud se aplikace na druhém zařízení nespustí podruhé. Obecněji platí, že pokud jsou značky ovlivněné více zařízeními, je správa značek z back-endu žádoucí možností.
• Vzhledem k tomu, že aplikace mohou být hacknuty, vyžaduje zabezpečení registrace pro konkrétní značky zvláštní péči, jak je vysvětleno v článku Zabezpečení.

Příklad kódu pro registraci v centru oznámení ze zařízení pomocí instalace

V tuto chvíli se to podporuje jenom pomocí rozhraní REST API služby Notification Hubs.

K aktualizaci instalace můžete také použít metodu PATCH pomocí standardu JSON-Patch .

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

Příklad kódu pro registraci v centru oznámení ze zařízení pomocí registrace

Tyto metody vytvoří nebo aktualizují registraci zařízení, na kterém jsou volána. To znamená, že pokud chcete aktualizovat popisovač nebo značky, musíte přepsat celou registraci. Nezapomeňte, že registrace jsou přechodné, takže byste vždy měli mít spolehlivé úložiště s aktuálními značkami, které konkrétní zařízení potřebuje.

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

Správa registrace z back-endu

Správa registrací z back-endu vyžaduje napsání dalšího kódu. Aplikace ze zařízení musí back-endu poskytnout aktualizovaný popisovač PNS při každém spuštění aplikace (spolu se značkami a šablonami) a back-end musí tento popisovač aktualizovat v centru oznámení. Tento návrh znázorňuje následující obrázek.

Mezi výhody správy registrací z back-endu patří možnost upravit značky na registrace, i když je odpovídající aplikace na zařízení neaktivní, a ověřit klientskou aplikaci před přidáním značky do registrace.

Příklad kódu pro registraci centra oznámení z back-endu pomocí instalace

Klientské zařízení stále získá popisovač PNS a relevantní vlastnosti instalace jako předtím a volá vlastní rozhraní API na back-endu, které může provádět registraci a autorizaci značek atd. Back-end může pro back-endové operace využívat sadu SDK centra oznámení.

K aktualizaci instalace můžete také použít metodu PATCH pomocí standardu JSON-Patch .

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

Příklad kódu pro registraci v centru oznámení z back-endu pomocí ID registrace

Z back-endu aplikace můžete s registracemi provádět základní operace CRUDS. Příklad:

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

Back-end musí zpracovávat souběžnost mezi aktualizacemi registrace. Service Bus nabízí optimistické řízení souběžnosti pro správu registrací. Na úrovni HTTP se to implementuje s použitím značky ETag v operacích správy registrace. Tuto funkci transparentně používají sady Microsoft SDK, které vyvolají výjimku, pokud je aktualizace odmítnuta z důvodů souběžnosti. Back-end aplikace zodpovídá za zpracování těchto výjimek a v případě potřeby opakování aktualizace.