Manajemen pendaftaran

Topik ini menjelaskan cara mendaftarkan perangkat dengan hub pemberitahuan untuk menerima pemberitahuan push. Topik ini menjelaskan pendaftaran pada tingkat tinggi, kemudian memperkenalkan dua pola utama untuk mendaftarkan perangkat: mendaftar dari perangkat langsung ke pusat pemberitahuan, dan mendaftar melalui backend aplikasi.

Apa itu pendaftaran perangkat

Pendaftaran perangkat dengan Hub Pemberitahuan dilakukan menggunakan Pendaftaran atau Instalasi.

Pendaftaran

Pendaftaran mengaitkan handel Layanan Pemberitahuan Platform (PNS) untuk perangkat dengan tag-tag dan kemungkinan sebuah templat. Handel PNS bisa berupa ChannelURI, atau ID pendaftaran token perangkat. Tag digunakan untuk merutekan pemberitahuan ke kumpulan handel perangkat yang benar. Untuk informasi selengkapnya, lihat Perutean dan Ekspresi Tag. Templat digunakan untuk mengimplementasikan transformasi per pendaftaran. Untuk informasi selengkapnya, lihat Templat.

Catatan

Azure Notification Hubs mendukung maksimal 60 tag per perangkat.

Instalasi

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

Berikut ini adalah beberapa keuntungan utama dari menggunakan instalasi:

• Membuat atau memperbarui instalasi sepenuhnya idempoten. Jadi Anda dapat mencobanya lagi tanpa khawatir akan pendaftaran duplikat.
• Model instalasi mendukung format tag khusus ($InstallationId:{INSTALLATION_ID}) yang memungkinkan pengiriman pemberitahuan langsung ke perangkat tertentu. Misalnya, jika kode aplikasi menetapkan ID instalasi joe93developer untuk perangkat tertentu ini, pengembang dapat menargetkan perangkat ini saat mengirim notifikasi ke tag $InstallationId:{joe93developer}. Ini memungkinkan Anda untuk menargetkan perangkat tertentu tanpa harus melakukan pengodean tambahan.
• Menggunakan instalasi juga memungkinkan Anda untuk melakukan pembaruan pendaftaran parsial. Pembaruan parsial instalasi diminta dengan metode PATCH menggunakan JSON-Patch standar. Ini berguna ketika Anda ingin memperbarui tag pada pendaftaran. Anda tidak perlu menarik seluruh pendaftaran lalu mengirim ulang lagi semua tag sebelumnya.

Penginstalan bisa memuat properti berikut ini. Untuk daftar lengkap properti instalasi, lihat Membuat atau Menimpa Instalasi dengan REST API atau Properti Instalasi.

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

Catatan

Secara default, pendaftaran dan instalasi tidak kedaluwarsa.

Pendaftaran dan pemasangan harus berisi handel PNS yang valid untuk setiap perangkat/saluran. Karena handel PNS hanya dapat diperoleh di aplikasi klien di perangkat, satu polanya adalah mendaftar langsung di perangkat tersebut dengan 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 pendorongan dilakukan ke handel yang telah kedaluwarsa oleh PNS, Azure Notification Hubs secara otomatis membersihkan 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. Selanjutnya, hentikan masa berlaku penginstalan/pendaftaran pada hub pemberitahuan sekunder.

Catatan

API Instalasi tidak mendukung layanan Baidu (meskipun API Pendaftaran tidak).

Templat

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

Setiap nama templat memetakan ke isi templat dan sekumpulan tag opsional. Selain itu, setiap platform dapat memiliki properti templat tambahan. Untuk Windows Store (menggunakan WNS), sekumpulan header tambahan dapat menjadi bagian dari templat. Dalam kasus APN, Anda dapat mengatur properti kedaluwarsa ke konstanta atau ke ekspresi templat. Untuk daftar lengkap properti instalasi, lihat topik Membuat atau Menimpa Instalasi 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 instalasi. 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 ChannelUri utama, ChannelUri petak sekunder dapat berubah kapan saja. Agar instalasi di hub notifikasi tetap diperbarui, perangkat harus menyegarkannya dengan ChannelUri petak sekunder saat ini.

Manajemen pendaftaran dari perangkat

Saat mengelola pendaftaran perangkat dari aplikasi klien, backend hanya bertanggung jawab untuk mengirim pemberitahuan. Aplikasi klien selalu menjaga handel PNS tetap terbaru, dan mendaftarkan tag. Gambar berikut mengilustrasikan pola ini.

Perangkat tersebut terlebih dahulu mengambil handel PNS dari PNS, kemudian mendaftar ke pusat pemberitahuan secara langsung. Setelah pendaftaran berhasil, backend 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 dari perangkat. Untuk informasi selengkapnya, lihat Keamanan.

Mendaftar dari perangkat adalah metode yang 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 akan menerima pemberitahuan tentang Seahawks sampai aplikasi pada perangkat kedua dieksekusi untuk kedua kalinya. Lebih umum, ketika tag dipengaruhi oleh beberapa perangkat, Anda disarankan untuk mengelola tag dari backend.
• Karena aplikasi dapat diretas, mengamankan pendaftaran ke tag tertentu memerlukan perawatan ekstra, seperti yang dijelaskan dalam artikel Keamanan.

Contoh kode untuk mendaftar dengan hub pemberitahuan dari perangkat menggunakan instalasi

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

Anda juga dapat memakai metode PATCH menggunakan standar JSON-Patch untuk memperbarui instalasi.

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

Contoh kode untuk mendaftar dengan hub pemberitahuan dari perangkat menggunakan pendaftaran

Metode ini membuat atau memperbarui pendaftaran untuk perangkat tempat mereka dipanggil. Ini berarti bahwa untuk memperbarui handel atau tag, Anda harus menimpa seluruh pendaftaran. Ingat bahwa pendaftaran bersifat sementara, jadi Anda harus selalu memiliki toko yang dapat diandalkan dengan tag saat ini yang dibutuhkan 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 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");
}

Manajemen pendaftaran dari backend

Mengelola pendaftaran dari backend memerlukan penulisan kode tambahan. Aplikasi dari perangkat harus menyediakan handel PNS yang diperbarui ke backend setiap kali aplikasi dimulai (bersama dengan tag dan templat), dan backend harus memperbarui handel ini pada hub pemberitahuan. Gambar berikut mengilustrasikan desain ini.

Keuntungan mengelola pendaftaran dari backend mencakup 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 backend menggunakan instalasi

Perangkat klien masih mendapatkan handel PNS dan properti instalasi yang relevan seperti sebelumnya dan memanggil API khusus pada backend yang dapat melakukan pendaftaran dan mengotorisasi tag dll. Backend dapat memanfaatkan Notification Hub SDK untuk operasi backend.

Anda juga dapat memakai metode PATCH menggunakan standar JSON-Patch untuk memperbarui instalasi.

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

Contoh kode untuk mendaftar dengan 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 konkurensi antara pembaruan pendaftaran. Service Bus menawarkan kontrol konkurensi optimis untuk manajemen pendaftaran. Di tingkat HTTP, ini diimplementasikan dengan penggunaan ETag pada operasi manajemen pendaftaran. Fitur ini secara transparan digunakan oleh Microsoft SDK, yang memberikan pengecualian jika pembaruan ditolak karena alasan konkurensi. Backend aplikasi bertanggung jawab untuk menangani pengecualian ini dan mencoba kembali pembaruan jika perlu.