Manajemen pendaftaran

Artikel ini menjelaskan cara mendaftarkan perangkat dengan Azure Notification Hubs untuk menerima pemberitahuan push. Artikel ini menjelaskan pendaftaran pada tingkat tinggi, lalu memperkenalkan dua pola utama untuk mendaftarkan perangkat: mendaftar dari perangkat langsung ke hub pemberitahuan, dan mendaftar melalui back end aplikasi.

Apa itu pendaftaran perangkat?

Pendaftaran perangkat dengan Notification Hub dilakukan menggunakan Pendaftaran atau Penginstalan.

Pendaftaran

Pendaftaran mengaitkan penanganan Platform Notification Service (PNS) untuk perangkat dengan tag dan kemungkinan templat. Handle PNS dapat berupa ChannelURI, atau ID pendaftaran token perangkat. Tag digunakan untuk merutekan pemberitahuan ke set handel perangkat yang benar. Untuk informasi selengkapnya, lihat Perutean dan ekspresi tag. Templat digunakan untuk menerapkan transformasi per pendaftaran. Untuk informasi selengkapnya, lihat Templat.

Nota

Azure Notification Hubs mendukung maksimal 60 tag per perangkat.

Instalasi

Penginstalan adalah pendaftaran yang lebih lengkap yang mencakup serangkaian properti terkait push. Ini adalah pendekatan terbaru dan terbaik untuk mendaftarkan perangkat Anda menggunakan .NET SDK sisi server (Notification Hub SDK untuk operasi backend). Anda juga dapat menggunakan pendekatan NOTIFICATION Hubs REST API untuk mendaftarkan penginstalan pada perangkat klien itu sendiri. Jika Anda menggunakan layanan backend, Anda harus dapat menggunakan Notification Hubs SDK untuk operasi backend.

Berikut ini adalah beberapa keuntungan utama untuk menggunakan penginstalan:

• Membuat atau memperbarui penginstalan sepenuhnya bersifat idempoten. Anda dapat mencobanya kembali tanpa kekhawatiran tentang pendaftaran duplikat.
• Model penginstalan mendukung format tag khusus ($InstallationId:{INSTALLATION_ID}) yang memungkinkan pengiriman pemberitahuan langsung ke perangkat tertentu. Misalnya, jika kode aplikasi menetapkan ID joe93developer penginstalan untuk perangkat tertentu ini, pengembang dapat menargetkan perangkat ini saat mengirim pemberitahuan ke $InstallationId:{joe93developer} tag. Ini memungkinkan Anda untuk menargetkan perangkat tertentu tanpa harus melakukan pengkodan tambahan.
• Menggunakan penginstalan juga memungkinkan Anda melakukan pembaruan pendaftaran parsial. Pembaruan parsial penginstalan diminta dengan metode PATCH menggunakan standarJSON-Patch. Metode ini berguna ketika Anda ingin memperbarui tag pada pendaftaran. Anda tidak perlu menarik seluruh pendaftaran dan kemudian mengirim ulang semua tag sebelumnya.

Penginstalan dapat berisi properti berikut. Untuk daftar lengkap properti penginstalan, lihat Membuat atau menimpa penginstalan dengan REST API atau Properti penginstalan.

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

Nota

Secara default, pendaftaran dan penginstalan tidak kedaluwarsa.

Pendaftaran dan penginstalan harus berisi handel PNS yang valid untuk setiap perangkat/saluran. Karena handle PNS hanya dapat diperoleh di aplikasi klien pada perangkat, salah satu caranya adalah dengan mendaftar langsung di perangkat tersebut menggunakan aplikasi klien. Di sisi lain, pertimbangan keamanan dan logika bisnis yang terkait dengan tag mungkin mengharuskan Anda mengelola pendaftaran perangkat di back-end aplikasi.

Ketika pengiriman dilakukan ke ID yang telah kedaluwarsa menurut catatan PNS, Azure Notification Hubs secara otomatis menghapus catatan penginstalan/pendaftaran terkait berdasarkan respons yang diterima dari server PNS. Untuk membersihkan rekaman yang kedaluwarsa dari hub pemberitahuan sekunder, tambahkan logika kustom yang memproses umpan balik dari setiap pengiriman. Kemudian, batalkan penginstalan/pendaftaran di hub pemberitahuan sekunder.

Nota

API penginstalan tidak mendukung layanan Baidu (meskipun API pendaftaran mendukung).

Templat

Jika Anda ingin menggunakan templat, penginstalan perangkat juga menyimpan semua templat yang terkait dengan perangkat tersebut dalam format JSON (lihat sampel di bagian sebelumnya). Nama templat membantu menargetkan templat yang berbeda untuk perangkat yang sama.

Setiap nama templat dipetakan ke isi templat dan sekumpulan tag opsional. Setiap platform dapat memiliki properti templat tambahan. Dalam kasus APN, Anda dapat mengatur properti kedaluwarsa ke konstanta atau ke ekspresi templat. Untuk daftar lengkap properti penginstalan, lihat topik Membuat atau menimpa penginstalan dengan REST.

Petak sekunder untuk aplikasi Windows Store

Untuk aplikasi klien Windows Store, mengirim pemberitahuan ke petak sekunder sama dengan mengirimnya ke yang utama. Ini juga didukung dalam penginstalan. Petak sekunder memiliki ChannelUri yang berbeda, yang ditangani SDK pada aplikasi klien Anda secara transparan.

Kamus SecondaryTiles menggunakan TileId yang sama yang digunakan untuk membuat objek SecondaryTiles di aplikasi Windows Store Anda. Seperti halnya URI Kanal utama, URI Kanal dari ubin sekunder dapat berubah kapan saja. Untuk menjaga instalasi di hub pemberitahuan tetap diperbarui, perangkat harus memperbaruinya dengan ChannelUris ubin sekunder saat ini.

Manajemen pendaftaran dari perangkat

Saat mengelola pendaftaran perangkat dari aplikasi klien, backend hanya bertanggung jawab untuk mengirim pemberitahuan. Aplikasi klien menjaga PNS tetap menangani up-to-date, dan mendaftarkan tag. Gambar berikut mengilustrasikan pola ini.

Perangkat pertama-tama mengambil handle PNS dari PNS, kemudian secara langsung mendaftar dengan hub pemberitahuan. Setelah pendaftaran berhasil, back end aplikasi dapat mengirim pemberitahuan yang menargetkan pendaftaran tersebut. Untuk informasi selengkapnya tentang cara mengirim pemberitahuan, lihat Perutean dan Ekspresi Tag.

Dalam hal ini, Anda hanya menggunakan hak Dengar untuk mengakses hub pemberitahuan Anda dari perangkat. Untuk informasi selengkapnya, lihat Keamanan .

Mendaftar dari perangkat adalah metode paling sederhana, tetapi memiliki beberapa kelemahan:

• Aplikasi klien hanya dapat memperbarui tagnya saat aplikasi aktif. Misalnya, jika pengguna memiliki dua perangkat yang mendaftarkan tag yang terkait dengan tim olahraga, ketika perangkat pertama mendaftar untuk tag tambahan (misalnya, Seahawks), perangkat kedua tidak menerima pemberitahuan tentang Seahawks sampai aplikasi pada perangkat kedua dijalankan untuk kedua kalinya. Lebih umum lagi, ketika tag dipengaruhi oleh beberapa perangkat, mengelola tag dari backend adalah opsi yang diinginkan.
• Karena aplikasi dapat diretas, mengamankan pendaftaran ke tag tertentu memerlukan perawatan ekstra, seperti yang dijelaskan dalam artikel Keamanan.

Contoh kode untuk mendaftar ke hub pemberitahuan dari perangkat menggunakan penginstalan

Saat ini, ini hanya didukung menggunakan Notification Hubs REST API.

Anda juga dapat menggunakan metode PATCH menggunakan standarJSON-Patch untuk memperbarui penginstalan.

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
        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 ===
        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 didn't store 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();
    }
}

Contoh kode untuk mendaftar dengan hub pemberitahuan dari perangkat menggunakan pendaftaran

Metode ini membuat atau memperbarui pendaftaran untuk perangkat di mana metode tersebut dijalankan. Ini berarti bahwa untuk memperbarui handle atau tag, Anda harus mengganti seluruh pendaftaran. Ingatlah bahwa pendaftaran bersifat sementara, jadi Anda harus selalu memiliki penyimpanan yang andal dengan tag saat ini yang dibutuhkan oleh perangkat tertentu.

// 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 didn't store 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");
}

Manajemen pendaftaran dari backend

Mengelola pendaftaran dari backend memerlukan penulisan kode tambahan. Aplikasi dari perangkat harus menyediakan handle PNS yang diperbarui ke backend setiap kali aplikasi dijalankan (beserta tag dan templat), dan backend harus memperbarui handle ini di pusat notifikasi. Gambar berikut mengilustrasikan desain ini.

Keuntungan mengelola pendaftaran dari backend termasuk kemampuan untuk memodifikasi tag ke pendaftaran bahkan ketika aplikasi yang sesuai pada perangkat tidak aktif, dan untuk mengautentikasi aplikasi klien sebelum menambahkan tag ke pendaftarannya.

Contoh kode untuk mendaftar dengan hub pemberitahuan dari server backend menggunakan instalasi

Perangkat klien masih mendapatkan handle PNS dan properti penginstalan yang relevan seperti sebelumnya dan memanggil API kustom di backend yang dapat melakukan pendaftaran dan mengotorisasi tag dan lain-lain. Backend dapat memanfaatkan Notification Hub SDK untuk operasi backend.

Anda juga dapat menggunakan metode PATCH menggunakan standarJSON-Patch untuk memperbarui penginstalan.

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

Kode contoh untuk mendaftarkan diri pada hub pemberitahuan dari backend menggunakan ID pendaftaran

Dari backend aplikasi, Anda dapat melakukan operasi CRUDS dasar pada pendaftaran. Contohnya:

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 harus menangani keserentakan dari pembaruan pendaftaran. Notification Hubs menawarkan kontrol konkurensi optimis untuk manajemen pendaftaran. Pada tingkat HTTP, ini diimplementasikan dengan penggunaan ETag pada operasi manajemen pendaftaran. Fitur ini secara transparan digunakan oleh Microsoft SDK, yang melemparkan pengecualian jika pembaruan ditolak karena alasan konkurensi. Backend aplikasi bertanggung jawab untuk menangani pengecualian ini dan mencoba kembali pembaruan jika perlu.