Správa registrací

Toto téma vysvětluje, jak registrovat zařízení v centrech oznámení, aby bylo možné přijímat nabízená oznámení. Toto téma popisuje registrace na vysoké úrovni a pak zavádí dva hlavní vzory registrace 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í ke značkám a případně k šabloně. Popisovač PNS může být ID registrace ChannelURI, tokenu zařízení nebo FCM. Značky se používají 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 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 vylepšená registrace, která zahrnuje tašku s vlastnostmi souvisejícími s nabízení. Jedná se o nejnovější a nejlepší přístup k registraci zařízení pomocí sady .NET SDK na straně serveru (sada SDK centra oznámení pro back-endové operace). Můžete také použít přístup rozhraní REST API služby Notification Hubs k registraci instalací na samotném klientském zařízení. 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žití instalací:

  • Vytvoření nebo aktualizace instalace je plně idempotentní. Můžete to proto opakovat bez jakýchkoli obav o duplicitní registrace.
  • Instalační model podporuje speciální formát značek ($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ář toto zařízení cílit při odesílání oznámení na $InstallationId:{joe93developer} značku. 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 požadována metodou PATCH pomocí standardu JSON-Patch. To je užitečné, když chcete aktualizovat značky při registraci. Nemusíte stahovat celou registraci a pak znovu odeslat všechny předchozí značky.

Instalace může obsahovat následující vlastnosti. Úplný výpis vlastností instalace naleznete 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í nevyprší platnost registrací a instalací.

Registrace a instalace musí obsahovat platný popisovač PNS pro každé zařízení nebo kanál. Protože obslužné rutiny PNS lze získat pouze v klientské aplikaci na zařízení, je jedním vzorem registrace přímo na zařízení s klientskou aplikací. Na druhou stranu můžou aspekty zabezpečení a obchodní logika související se značkami vyžadovat správu registrace zařízení v back-endu aplikace.

Poznámka

Rozhraní API pro instalace nepodporuje službu Baidu (i když rozhraní API pro registraci).

Š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 ho 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ě apNs můžete vlastnost vypršení platnosti nastavit na konstantu nebo na výraz šablony. Úplný seznam vlastností instalace najdete v tématu Vytvoření nebo přepsání instalace pomocí tématu REST .

Sekundární dlaždice pro aplikace Windows Store

U klientských aplikací Windows Store je odesílání oznámení na sekundární dlaždice stejné jako odesílání do primární dlaždice. 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í secondarytiles objektu v aplikaci Windows Store. Stejně jako u primárního identifikátoru ChannelUri se identifikátory ChannelUri sekundárních dlaždic můžou kdykoli změnit. Aby se instalace v centru oznámení aktualizovaly, musí je zařízení aktualizovat pomocí aktuálních identifikátorů ChannelUri 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í PNS aktuální a registrují značky. Tento vzor znázorňuje následující obrázek.

Registration from device

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

V takovém případě použijete pouze práva naslouchání pro přístup k vašim centrem oznámení ze zařízení. Další informace naleznete 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 pouze v době, 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ž se první zařízení zaregistruje na 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ě platí, že pokud jsou značky ovlivněny více zařízeními, správa značek z back-endu je žádoucí možností.
  • Vzhledem k tomu, že aplikace mohou být hacknuty, zabezpečení registrace na konkrétní značky vyžaduje zvláštní péči, jak je vysvětleno v článku Zabezpečení.

Ukázkový kód 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 použít také 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();
    }
}

Ukázkový kód pro registraci v centru oznámení ze zařízení pomocí registrace

Tyto metody vytvářejí 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. Mějte na paměti, že registrace jsou přechodné, takže byste měli vždy 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 zápis dalšího kódu. Aplikace ze zařízení musí poskytnout aktualizovaný popisovač PNS back-endu 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.

Registration management

Mezi výhody správy registrací z back-endu patří možnost upravovat 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.

Ukázkový kód pro registraci v centru oznámení z back-endu pomocí instalace

Klientské zařízení stále získává 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 využít sadu SDK centra oznámení k back-endovým operacím.

K aktualizaci instalace můžete použít také 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);
}

Ukázkový kód pro registraci v centru oznámení ze zařízení pomocí ID registrace

Z back-endu aplikace můžete provádět základní operace CRUDS při registraci. 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í optimistickou kontrolu souběžnosti pro správu registrace. Na úrovni HTTP se to implementuje s použitím značky ETag při operacích správy registrace. Tato funkce je transparentně používána sadami MICROSOFT SDK, která vyvolá 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 zkusí aktualizaci zopakovat.