Gambaran umum Windows Push Notification Services (WNS)
Windows Push Notification Services (WNS) memungkinkan pengembang pihak ketiga untuk mengirim toast, petak peta, lencana, dan pembaruan mentah dari layanan cloud mereka sendiri. Ini menyediakan mekanisme untuk memberikan pembaruan baru kepada pengguna Anda dengan cara yang hemat daya dan dapat diandalkan.
Cara kerjanya
Diagram berikut menunjukkan aliran data lengkap untuk mengirim pemberitahuan push. Fase peninjauan ini melibatkan langkah-langkah berikut:
- Aplikasi Anda meminta saluran pemberitahuan push dari WNS.
- Windows meminta WNS untuk membuat saluran pemberitahuan. Saluran ini dikembalikan ke perangkat panggilan dalam bentuk Pengidentifikasi Sumber Daya Seragam (URI).
- URI saluran pemberitahuan dikembalikan oleh WNS ke aplikasi Anda.
- Aplikasi Anda mengirimkan URI ke layanan cloud Anda sendiri. Anda kemudian menyimpan URI di layanan cloud Anda sendiri sehingga Anda dapat mengakses URI saat mengirim pemberitahuan. URI adalah antarmuka antara aplikasi Anda sendiri dan layanan Anda sendiri; Anda bertanggung jawab untuk menerapkan antarmuka ini dengan standar web yang aman dan aman.
- Saat layanan awan Anda memiliki pembaruan untuk dikirim, layanan cloud akan memberi tahu WNS menggunakan URI saluran. Ini dilakukan dengan mengeluarkan permintaan HTTP POST, termasuk payload pemberitahuan, melalui Secure Sockets Layer (SSL). Langkah ini memerlukan autentikasi.
- WNS menerima permintaan dan merutekan pemberitahuan ke perangkat yang sesuai.
Mendaftarkan aplikasi Anda dan menerima kredensial untuk layanan cloud Anda
Sebelum dapat mengirim pemberitahuan menggunakan WNS, aplikasi Anda harus terdaftar di Dasbor Toko, seperti yang dijelaskan di sini.
Meminta saluran pemberitahuan
Saat aplikasi yang mampu menerima pemberitahuan push berjalan, aplikasi harus terlebih dahulu meminta saluran pemberitahuan melalui CreatePushNotificationChannelForApplicationAsync. Untuk diskusi lengkap dan contoh kode, lihat Cara meminta, membuat, dan menyimpan saluran pemberitahuan. API ini mengembalikan URI saluran yang secara unik ditautkan ke aplikasi panggilan dan petak petanya, dan di mana semua jenis pemberitahuan dapat dikirim.
Setelah aplikasi berhasil membuat URI saluran, aplikasi mengirimkannya ke layanan cloudnya, bersama dengan metadata khusus aplikasi apa pun yang harus dikaitkan dengan URI ini.
Catatan penting
- Kami tidak menjamin bahwa URI saluran pemberitahuan untuk aplikasi akan selalu tetap sama. Kami menyarankan agar aplikasi meminta saluran baru setiap kali berjalan dan memperbarui layanannya saat URI berubah. Pengembang tidak boleh memodifikasi URI saluran dan harus menganggapnya sebagai string kotak hitam. Saat ini, URI saluran kedaluwarsa setelah 30 hari. Jika aplikasi Windows 10 Anda akan memperbarui salurannya secara berkala di latar belakang maka Anda dapat mengunduh sampel pemberitahuan Push dan berkala untuk Windows 8.1 dan menggunakan kembali kode sumbernya dan/atau pola yang ditunjukkannya.
- Antarmuka antara layanan cloud dan aplikasi klien diimplementasikan oleh Anda, pengembang. Sebaiknya aplikasi melalui proses autentikasi dengan layanannya sendiri dan mengirimkan data melalui protokol aman seperti HTTPS.
- Penting bahwa layanan cloud selalu memastikan bahwa URI saluran menggunakan domain "notify.windows.com". Layanan ini tidak boleh mendorong pemberitahuan ke saluran di domain lain. Jika panggilan balik untuk aplikasi Anda pernah disusupi, penyerang berbahaya dapat mengirimkan URI saluran ke WNS spoof. Tanpa memeriksa domain, layanan cloud Anda berpotensi mengungkapkan informasi kepada penyerang ini tanpa sadar. Subdomain URI saluran dapat berubah dan tidak boleh dipertimbangkan saat memvalidasi URI saluran.
- Jika layanan cloud Anda mencoba mengirimkan pemberitahuan ke saluran yang kedaluwarsa, WNS akan mengembalikan kode respons 410. Sebagai respons terhadap kode tersebut, layanan Anda tidak boleh lagi mencoba mengirim pemberitahuan ke URI tersebut.
Mengautentikasi layanan awan Anda
Untuk mengirim pemberitahuan, layanan awan harus diautentikasi melalui WNS. Langkah pertama dalam proses ini terjadi saat Anda mendaftarkan aplikasi Anda dengan Dasbor Microsoft Store. Selama proses pendaftaran, aplikasi Anda diberi Pengidentifikasi keamanan Paket (SID) dan kunci rahasia. Informasi ini digunakan oleh layanan awan Anda untuk mengautentikasi dengan WNS.
Skema autentikasi WNS diimplementasikan menggunakan profil kredensial klien dari protokol OAuth 2.0 . Layanan cloud mengautentikasi dengan WNS dengan memberikan kredensialnya (Package SID dan kunci rahasia). Sebagai imbalannya, ia menerima token akses. Token akses ini memungkinkan layanan cloud untuk mengirim pemberitahuan. Token diperlukan dengan setiap permintaan pemberitahuan yang dikirim ke WNS.
Pada tingkat tinggi, rantai informasi adalah sebagai berikut:
- Layanan cloud mengirimkan kredensialnya ke WNS melalui HTTPS mengikuti protokol OAuth 2.0. Ini mengautentikasi layanan dengan WNS.
- WNS mengembalikan token akses jika autentikasi berhasil. Token akses ini digunakan dalam semua permintaan pemberitahuan berikutnya hingga kedaluwarsa.
Dalam autentikasi dengan WNS, layanan cloud mengirimkan permintaan HTTP melalui Secure Sockets Layer (SSL). Parameter disediakan dalam format "application/x-www-for-urlencoded". Berikan SID Paket Anda di bidang "client_id" dan kunci rahasia Anda di bidang "client_secret" seperti yang ditunjukkan dalam contoh berikut. Untuk detail sintaks, lihat referensi permintaan token akses.
Catatan
Ini hanyalah contoh, bukan kode potong dan tempel yang berhasil Anda gunakan dalam kode Anda sendiri.
POST /accesstoken.srf HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: https://login.live.com
Content-Length: 211
grant_type=client_credentials&client_id=ms-app%3a%2f%2fS-1-15-2-2972962901-2322836549-3722629029-1345238579-3987825745-2155616079-650196962&client_secret=Vex8L9WOFZuj95euaLrvSH7XyoDhLJc7&scope=notify.windows.com
WNS mengautentikasi layanan cloud dan, jika berhasil, mengirimkan respons "200 OK". Token akses dikembalikan dalam parameter yang disertakan dalam isi respons HTTP, menggunakan jenis media "application/json". Setelah layanan Anda menerima token akses, Anda siap untuk mengirim pemberitahuan.
Contoh berikut menunjukkan respons autentikasi yang berhasil, termasuk token akses. Untuk detail sintaks, lihat Permintaan layanan pemberitahuan push dan header respons.
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Length: 422
Content-Type: application/json
{
"access_token":"EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA=",
"token_type":"bearer"
}
Catatan penting
- Protokol OAuth 2.0 yang didukung dalam prosedur ini mengikuti draf versi V16.
- Permintaan Komentar OAuth (RFC) menggunakan istilah "klien" untuk merujuk ke layanan cloud.
- Mungkin ada perubahan pada prosedur ini ketika draf OAuth diselesaikan.
- Token akses dapat digunakan kembali untuk beberapa permintaan pemberitahuan. Ini memungkinkan layanan awan untuk mengautentikasi hanya sekali untuk mengirim banyak pemberitahuan. Namun, ketika token akses kedaluwarsa, layanan awan harus mengautentikasi lagi untuk menerima token akses baru.
Mengirim pemberitahuan
Dengan menggunakan URI saluran, layanan cloud dapat mengirim pemberitahuan setiap kali memiliki pembaruan untuk pengguna.
Token akses yang dijelaskan di atas dapat digunakan kembali untuk beberapa permintaan pemberitahuan; server cloud tidak diperlukan untuk meminta token akses baru untuk setiap pemberitahuan. Jika token akses telah kedaluwarsa, permintaan pemberitahuan akan mengembalikan kesalahan. Kami menyarankan agar Anda tidak mencoba mengirim ulang pemberitahuan Anda lebih dari sekali jika token akses ditolak. Jika Anda mengalami kesalahan ini, Anda harus meminta token akses baru dan mengirim ulang pemberitahuan. Untuk kode kesalahan yang tepat, lihat Kode respons pemberitahuan push.
Layanan awan membuat HTTP POST ke URI saluran. Permintaan ini harus dibuat melalui SSL dan berisi header yang diperlukan dan payload pemberitahuan. Header otorisasi harus menyertakan token akses yang diperoleh untuk otorisasi.
Contoh permintaan ditampilkan di sini. Untuk detail sintaks, lihat Kode respons pemberitahuan push.
Untuk detail tentang menyusun payload pemberitahuan, lihat Mulai Cepat: Mengirim pemberitahuan push. Payload pemberitahuan push petak peta, roti panggang, atau lencana disediakan sebagai konten XML yang mematuhi skema petak peta Adaptif yang ditentukan masing-masing atau skema petak peta Warisan. Payload pemberitahuan mentah tidak memiliki struktur tertentu. Ini benar-benar ditentukan aplikasi.
POST https://cloud.notify.windows.com/?token=AQE%bU%2fSjZOCvRjjpILow%3d%3d HTTP/1.1 Content-Type: text/xml X-WNS-Type: wns/tile Authorization: Bearer EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA= Host: cloud.notify.windows.com Content-Length: 24 <body> ....WNS merespons untuk menunjukkan bahwa pemberitahuan telah diterima dan akan dikirimkan pada kesempatan berikutnya yang tersedia. Namun, WNS tidak memberikan konfirmasi end-to-end bahwa pemberitahuan Anda telah diterima oleh perangkat atau aplikasi.
Diagram ini mengilustrasikan aliran data:
Catatan penting
- WNS tidak menjamin keandalan atau latensi pemberitahuan.
- Pemberitahuan tidak boleh menyertakan data rahasia, sensitif, atau pribadi.
- Untuk mengirim pemberitahuan, layanan awan harus terlebih dahulu mengautentikasi dengan WNS dan menerima token akses.
- Token akses hanya memungkinkan layanan cloud untuk mengirim pemberitahuan ke aplikasi tunggal tempat token dibuat. Satu token akses tidak dapat digunakan untuk mengirim pemberitahuan di beberapa aplikasi. Oleh karena itu, jika layanan cloud Anda mendukung beberapa aplikasi, layanan tersebut harus menyediakan token akses yang benar untuk aplikasi saat mendorong pemberitahuan ke setiap URI saluran.
- Ketika perangkat offline, secara default WNS akan menyimpan salah satu dari setiap jenis pemberitahuan (petak peta, lencana, roti panggang) untuk setiap URI saluran dan tidak ada pemberitahuan mentah.
- Dalam skenario di mana konten pemberitahuan dipersonalisasi ke pengguna, WNS merekomendasikan agar layanan cloud segera mengirim pembaruan tersebut ketika mereka diterima. Contoh skenario ini termasuk pembaruan umpan media sosial, undangan komunikasi instan, pemberitahuan pesan baru, atau pemberitahuan. Sebagai alternatif, Anda dapat memiliki skenario di mana pembaruan umum yang sama sering dikirimkan ke subset besar pengguna Anda; misalnya, pembaruan cuaca, stok, dan berita. Pedoman WNS menentukan bahwa frekuensi pembaruan ini harus paling banyak satu setiap 30 menit. Pengguna akhir atau WNS dapat menentukan pembaruan rutin yang lebih sering menjadi kasar.
- Windows Notification Platform mempertahankan koneksi data berkala dengan WNS untuk menjaga soket tetap hidup dan sehat. Jika tidak ada aplikasi yang meminta atau menggunakan saluran pemberitahuan, soket tidak akan dibuat.
Kedaluwarsa pemberitahuan petak peta dan lencana
Secara default, pemberitahuan petak peta dan lencana kedaluwarsa tiga hari setelah diunduh. Ketika pemberitahuan kedaluwarsa, konten dihapus dari petak atau antrean dan tidak lagi ditampilkan kepada pengguna. Ini adalah praktik terbaik untuk mengatur kedaluwarsa (menggunakan waktu yang masuk akal untuk aplikasi Anda) pada semua pemberitahuan petak dan lencana sehingga konten petak peta Anda tidak bertahan lebih lama dari yang relevan. Waktu kedaluwarsa eksplisit sangat penting untuk konten dengan masa pakai yang ditentukan. Ini juga memastikan penghapusan konten kedaluarsa jika layanan cloud Anda berhenti mengirim pemberitahuan, atau jika pengguna memutuskan sambungan dari jaringan untuk jangka waktu yang lama.
Layanan cloud Anda dapat mengatur kedaluwarsa untuk setiap pemberitahuan dengan mengatur header HTTP X-WNS-TTL untuk menentukan waktu (dalam detik) bahwa pemberitahuan Anda akan tetap valid setelah dikirim. Untuk informasi selengkapnya, lihat Permintaan layanan pemberitahuan push dan header respons.
Misalnya, selama hari perdagangan aktif pasar saham, Anda dapat mengatur kedaluwarsa untuk pembaruan harga saham menjadi dua kali lipat dari interval pengiriman Anda (seperti satu jam setelah tanda terima jika Anda mengirim pemberitahuan setiap setengah jam). Sebagai contoh lain, aplikasi berita mungkin menentukan bahwa suatu hari adalah waktu kedaluwarsa yang sesuai untuk pembaruan petak berita harian.
Pemberitahuan push dan penghemat baterai
Penghemat baterai memperpanjang masa pakai baterai dengan membatasi aktivitas latar belakang pada perangkat. Windows 10 memungkinkan pengguna mengatur penghemat baterai untuk menyala secara otomatis ketika baterai turun di bawah ambang yang ditentukan. Ketika penghemat baterai aktif, tanda terima pemberitahuan push dinonaktifkan untuk menghemat energi. Tapi ada beberapa pengecualian untuk ini. Pengaturan penghemat baterai Windows 10 berikut (ditemukan di aplikasi Pengaturan) memungkinkan aplikasi Anda menerima pemberitahuan push bahkan ketika penghemat baterai aktif.
- Izinkan pemberitahuan push dari aplikasi apa pun saat berada di penghemat baterai: Pengaturan ini memungkinkan semua aplikasi menerima pemberitahuan push saat penghemat baterai aktif. Perhatikan bahwa pengaturan ini hanya berlaku untuk Windows 10 untuk edisi desktop (Home, Pro, Enterprise, dan Education).
- Selalu diizinkan: Pengaturan ini memungkinkan aplikasi tertentu berjalan di latar belakang saat penghemat baterai aktif - termasuk menerima pemberitahuan push. Daftar ini dipertahankan secara manual oleh pengguna.
Tidak ada cara untuk memeriksa status kedua pengaturan ini, tetapi Anda dapat memeriksa status penghemat baterai. Di Windows 10, gunakan properti EnergySaverStatus untuk memeriksa status penghemat baterai. Aplikasi Anda juga dapat menggunakan peristiwa EnergySaverStatusChanged untuk mendengarkan perubahan pada penghemat baterai.
Jika aplikasi Anda sangat bergantung pada pemberitahuan push, sebaiknya beri tahu pengguna bahwa mereka mungkin tidak menerima pemberitahuan saat penghemat baterai aktif dan memudahkan mereka menyesuaikan pengaturan penghemat baterai. Menggunakan skema URI pengaturan penghemat baterai di Windows 10, ms-settings:batterysaver-settings, Anda dapat menyediakan tautan yang nyaman ke aplikasi Pengaturan.
Tip
Saat memberi tahu pengguna tentang pengaturan penghemat baterai, sebaiknya berikan cara untuk menekan pesan di masa mendatang. Misalnya, dontAskMeAgainBox kotak centang dalam contoh berikut mempertahankan preferensi pengguna di Lokal Pengaturan.
Berikut adalah contoh cara memeriksa apakah penghemat baterai diaktifkan di Windows 10. Contoh ini memberi tahu pengguna dan meluncurkan aplikasi Pengaturan ke pengaturan penghemat baterai. memungkinkan dontAskAgainSetting pengguna menekan pesan jika mereka tidak ingin diberi tahu lagi.
using System;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Navigation;
using Windows.System;
using Windows.System.Power;
...
...
async public void CheckForEnergySaving()
{
//Get reminder preference from LocalSettings
bool dontAskAgain;
var localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;
object dontAskSetting = localSettings.Values["dontAskAgainSetting"];
if (dontAskSetting == null)
{ // Setting does not exist
dontAskAgain = false;
}
else
{ // Retrieve setting value
dontAskAgain = Convert.ToBoolean(dontAskSetting);
}
// Check if battery saver is on and that it's okay to raise dialog
if ((PowerManager.EnergySaverStatus == EnergySaverStatus.On)
&& (dontAskAgain == false))
{
// Check dialog results
ContentDialogResult dialogResult = await saveEnergyDialog.ShowAsync();
if (dialogResult == ContentDialogResult.Primary)
{
// Launch battery saver settings (settings are available only when a battery is present)
await Launcher.LaunchUriAsync(new Uri("ms-settings:batterysaver-settings"));
}
// Save reminder preference
if (dontAskAgainBox.IsChecked == true)
{ // Don't raise dialog again
localSettings.Values["dontAskAgainSetting"] = "true";
}
}
}
#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.Storage.h>
#include <winrt/Windows.System.h>
#include <winrt/Windows.System.Power.h>
#include <winrt/Windows.UI.Xaml.h>
#include <winrt/Windows.UI.Xaml.Controls.h>
#include <winrt/Windows.UI.Xaml.Navigation.h>
using namespace winrt;
using namespace winrt::Windows::Foundation;
using namespace winrt::Windows::Storage;
using namespace winrt::Windows::System;
using namespace winrt::Windows::System::Power;
using namespace winrt::Windows::UI::Xaml;
using namespace winrt::Windows::UI::Xaml::Controls;
using namespace winrt::Windows::UI::Xaml::Navigation;
...
winrt::fire_and_forget CheckForEnergySaving()
{
// Get reminder preference from LocalSettings.
bool dontAskAgain{ false };
auto localSettings = ApplicationData::Current().LocalSettings();
IInspectable dontAskSetting = localSettings.Values().Lookup(L"dontAskAgainSetting");
if (!dontAskSetting)
{
// Setting doesn't exist.
dontAskAgain = false;
}
else
{
// Retrieve setting value
dontAskAgain = winrt::unbox_value<bool>(dontAskSetting);
}
// Check whether battery saver is on, and whether it's okay to raise dialog.
if ((PowerManager::EnergySaverStatus() == EnergySaverStatus::On) && (!dontAskAgain))
{
// Check dialog results.
ContentDialogResult dialogResult = co_await saveEnergyDialog().ShowAsync();
if (dialogResult == ContentDialogResult::Primary)
{
// Launch battery saver settings
// (settings are available only when a battery is present).
co_await Launcher::LaunchUriAsync(Uri(L"ms-settings:batterysaver-settings"));
}
// Save reminder preference.
if (dontAskAgainBox().IsChecked())
{
// Don't raise the dialog again.
localSettings.Values().Insert(L"dontAskAgainSetting", winrt::box_value(true));
}
}
}
Ini adalah XAML untuk ContentDialog yang ditampilkan dalam contoh ini.
<ContentDialog x:Name="saveEnergyDialog"
PrimaryButtonText="Open battery saver settings"
SecondaryButtonText="Ignore"
Title="Battery saver is on.">
<StackPanel>
<TextBlock TextWrapping="WrapWholeWords">
<LineBreak/><Run>Battery saver is on and you may
not receive push notifications.</Run><LineBreak/>
<LineBreak/><Run>You can choose to allow this app to work normally
while in battery saver, including receiving push notifications.</Run>
<LineBreak/>
</TextBlock>
<CheckBox x:Name="dontAskAgainBox" Content="OK, got it."/>
</StackPanel>
</ContentDialog>
Topik terkait
- Mengirim pemberitahuan petak peta lokal
- Mulai cepat: Mengirim pemberitahuan push
- Cara memperbarui lencana melalui pemberitahuan push
- Cara meminta, membuat, dan menyimpan saluran pemberitahuan
- Cara mencegat pemberitahuan untuk menjalankan aplikasi
- Cara mengautentikasi dengan Windows Push Notification Service (WNS)
- Permintaan layanan pemberitahuan push dan header respons
- Panduan dan daftar periksa untuk pemberitahuan push
- Pemberitahuan mentah
Windows developer
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk