如要傳送推播訊息,您必須先取得使用者權限,然後將使用者的裝置訂閱推播服務。這包括使用 JavaScript API 取得 PushSubscription 物件,然後將物件傳送至伺服器。
JavaScript API 可直接管理這項程序。本指南說明整個流程,包括功能偵測、要求權限和管理訂閱程序。
特徵偵測
首先,請確認瀏覽器是否支援推播訊息。您可以透過兩項檢查,確認是否支援推送:
- 檢查
navigator物件上是否有serviceWorker。 - 檢查
window物件上是否有PushManager。
if (!('serviceWorker' in navigator)) {
// Service Worker isn't supported on this browser, disable or hide UI.
return;
}
if (!('PushManager' in window)) {
// Push isn't supported on this browser, disable or hide UI.
return;
}
雖然瀏覽器對 Service Worker 和推播訊息的支援度越來越高,但請務必偵測這兩項功能,並漸進增強應用程式。
註冊 Service Worker
功能偵測完成後,您會知道系統支援 Service Worker 和推播訊息。接著,註冊 Service Worker。
註冊 Service Worker 時,您會告知瀏覽器 Service Worker 檔案的位置。該檔案是 JavaScript 檔案,但瀏覽器會授予其 Service Worker API 的存取權,包括推播訊息。具體來說,瀏覽器會在 Service Worker 環境中執行檔案。
如要註冊 Service Worker,請呼叫 navigator.serviceWorker.register() 並傳遞檔案路徑。例如:
function registerServiceWorker() {
return navigator.serviceWorker
.register('/service-worker.js')
.then(function (registration) {
console.log('Service worker successfully registered.');
return registration;
})
.catch(function (err) {
console.error('Unable to register service worker.', err);
});
}
這個函式會告訴瀏覽器 Service Worker 檔案的位置。在這裡,Service Worker 檔案位於 /service-worker.js。呼叫 register() 後,瀏覽器會執行下列步驟:
下載 Service Worker 檔案。
執行 JavaScript。
如果檔案正確執行且未發生錯誤,
register()傳回的 Promise 就會解析。如果發生錯誤,Promise 會拒絕。
注意:如果 register() 拒絕,請在 Chrome 開發人員工具中檢查 JavaScript 是否有錯字或錯誤。
register() 解析後,會傳回 ServiceWorkerRegistration。您可以使用這項註冊資訊存取 PushManager API。
PushManager API 瀏覽器相容性
要求權限
註冊 Service Worker 並取得權限後,請向使用者取得傳送推播訊息的權限。
取得權限的 API 很簡單。不過,API 最近從接受回呼變更為傳回 Promise。由於您無法判斷瀏覽器實作的 API 版本,因此必須實作並處理這兩個版本。
function askPermission() {
return new Promise(function (resolve, reject) {
const permissionResult = Notification.requestPermission(function (result) {
resolve(result);
});
if (permissionResult) {
permissionResult.then(resolve, reject);
}
}).then(function (permissionResult) {
if (permissionResult !== 'granted') {
throw new Error("We weren't granted permission.");
}
});
}
在上述程式碼中,呼叫 Notification.requestPermission() 會向使用者顯示提示:

使用者與權限提示互動後,無論是選取「允許」、「封鎖」或關閉提示,您都會收到字串形式的結果:'granted'、'default' 或 'denied'。
在程式碼範例中,如果授予權限,askPermission() 傳回的 Promise 會解析;否則會擲回錯誤,且 Promise 會拒絕。
處理使用者點選「封鎖」按鈕的極端情況。如果發生這種情況,網頁應用程式就無法再次要求使用者授予權限。使用者必須在設定面板中變更權限狀態,手動解除封鎖應用程式。請仔細考慮要求權限的時機和方式,因為使用者一旦點選「封鎖」,就不容易撤銷該決定。
如果使用者瞭解應用程式要求權限的原因,大多會授予權限。
本文稍後會討論一些熱門網站如何要求權限。
使用 PushManager 訂閱使用者
註冊 Service Worker 並取得權限後,您可以呼叫 registration.pushManager.subscribe() 來訂閱使用者。
function subscribeUserToPush() {
return navigator.serviceWorker
.register('/service-worker.js')
.then(function (registration) {
const subscribeOptions = {
userVisibleOnly: true,
applicationServerKey: urlBase64ToUint8Array(
'BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U',
),
};
return registration.pushManager.subscribe(subscribeOptions);
})
.then(function (pushSubscription) {
console.log(
'Received PushSubscription: ',
JSON.stringify(pushSubscription),
);
return pushSubscription;
});
}
呼叫 subscribe() 方法時,您會傳遞由必要和選用參數組成的 options 物件。
本節說明可傳遞的選項。
userVisibleOnly 選項
瀏覽器首次加入推播訊息功能時,開發人員不確定是否要在不顯示通知的情況下傳送推播訊息。這通常稱為「靜音推播」,因為使用者不知道背景發生了事件。
因為開發人員可能會在使用者不知情的情況下,持續追蹤其位置。
為避免這種情況,並讓規格作者考慮如何以最佳方式支援這項功能,我們新增了 userVisibleOnly 選項。傳遞 true 值,代表與瀏覽器達成象徵性協議,即網頁應用程式每次收到推播訊息時,都會顯示通知 (也就是沒有靜音推播)。
您必須傳遞 true 的值。如果未加入 userVisibleOnly 鍵或傳遞 false,系統會顯示下列錯誤:
Chrome currently only supports the Push API for subscriptions that will result
in user-visible messages. You can indicate this by calling
`pushManager.subscribe({userVisibleOnly: true})` instead. See
[https://goo.gl/yqv4Q4](https://goo.gl/yqv4Q4) for more details.
Chrome 僅支援會產生使用者可見訊息的訂閱項目。請呼叫 pushManager.subscribe({userVisibleOnly: true}) 來表示這一點。詳情請參閱 https://goo.gl/yqv4Q4。
Chrome 似乎不會全面實施靜音推播。相反地,規格作者正在探索預算 API,讓網頁應用程式根據網頁應用程式用量傳送特定數量的靜音推播訊息。
applicationServerKey 選項
本文先前曾提及應用程式伺服器金鑰。推播服務會使用應用程式伺服器金鑰,識別訂閱使用者的應用程式,並確保使用者收到的是同一個應用程式傳送的訊息。
應用程式伺服器金鑰是應用程式專屬的公開和私密金鑰組。請勿將私密金鑰告知他人,但公開金鑰可自由分享。
傳入 subscribe() 呼叫的 applicationServerKey 選項是應用程式的公開金鑰。瀏覽器會在訂閱使用者時,將這組金鑰傳遞給推播服務,讓推播服務將應用程式的公開金鑰與使用者的 PushSubscription 建立關聯。
下圖說明這些步驟。
- 在瀏覽器中載入網頁應用程式,並呼叫
subscribe(),傳遞公開應用程式伺服器金鑰。 - 接著,瀏覽器會向推播服務發出網路要求,產生端點,將這個端點與應用程式的公開金鑰建立關聯,並將端點傳回瀏覽器。
- 瀏覽器會將這個端點新增至
subscribe()承諾傳回的PushSubscription。
傳送推播訊息時,請建立 Authorization 標頭,其中包含使用應用程式伺服器私密金鑰簽署的資訊。推送服務收到傳送推送訊息的要求時,會查詢與接收要求的端點連結的公開金鑰,驗證這個已簽署的 Authorization 標頭。如果簽章有效,推播服務就會知道要求來自具有相符私密金鑰的應用程式伺服器。這項安全措施可防止他人傳送訊息給應用程式的使用者。
技術上來說,applicationServerKey 為選填。不過,Chrome 最簡單的實作方式需要這項功能,其他瀏覽器日後也可能需要。在 Firefox 上則為選填。
VAPID 規格定義了應用程式伺服器金鑰。應用程式伺服器金鑰和 VAPID 金鑰是相同的。
建立應用程式伺服器金鑰
您可以使用 web-push 指令列產生金鑰,建立一組公開和私密的應用程式伺服器金鑰,如下所示:
$ npm install -g web-push
$ web-push generate-vapid-keys
請只為應用程式建立一次這些金鑰,並確保私密金鑰不會外洩。
權限和 subscribe()
呼叫 subscribe() 有一個副作用。如果網頁應用程式在呼叫 subscribe() 時沒有顯示通知的權限,瀏覽器會為您要求權限。如果您的 UI 適用於這個流程,這項功能就非常實用。不過,如果您想進一步控管 (大多數開發人員都想這麼做),請使用本文稍早討論的 Notification.requestPermission() API。
PushSubscription 總覽
呼叫 subscribe()、傳遞選項,並接收解析為 PushSubscription 的 Promise。例如:
function subscribeUserToPush() {
return navigator.serviceWorker
.register('/service-worker.js')
.then(function (registration) {
const subscribeOptions = {
userVisibleOnly: true,
applicationServerKey: urlBase64ToUint8Array(
'BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U',
),
};
return registration.pushManager.subscribe(subscribeOptions);
})
.then(function (pushSubscription) {
console.log(
'Received PushSubscription: ',
JSON.stringify(pushSubscription),
);
return pushSubscription;
});
}
PushSubscription 物件包含傳送推播訊息給該使用者所需的所有資訊。如果使用 JSON.stringify() 列印內容,會看到以下內容:
{
"endpoint": "https://some.pushservice.com/something-unique",
"keys": {
"p256dh":
"BIPUL12DLfytvTajnryr2PRdAgXS3HGKiLqndGcJGabyhHheJYlNGCeXl1dn18gSJ1WAkAPIxr4gK0_dQds4yiI=",
"auth":"FPssNDTKnInHVndSTdbKFw=="
}
}
endpoint 是推送服務的網址。如要觸發推播訊息,請向這個網址發出 POST 要求。
keys 物件包含的值,用於加密與推播訊息一併傳送的訊息資料。(本文稍後會討論訊息加密)。
將訂閱項目傳送至伺服器
取得推送訂閱項目後,請將其傳送至伺服器。您可以自行決定傳送方式,但建議使用 JSON.stringify() 從訂閱物件中擷取所有必要資料。或者,您也可以手動組合相同的結果,例如:
const subscriptionObject = {
endpoint: pushSubscription.endpoint,
keys: {
p256dh: pushSubscription.getKeys('p256dh'),
auth: pushSubscription.getKeys('auth'),
},
};
// The above is the same output as:
const subscriptionObjectToo = JSON.stringify(pushSubscription);
如要從網頁傳送訂閱,請使用下列指令:
function sendSubscriptionToBackEnd(subscription) {
return fetch('/api/save-subscription/', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(subscription),
})
.then(function (response) {
if (!response.ok) {
throw new Error('Bad status code from server.');
}
return response.json();
})
.then(function (responseData) {
if (!(responseData.data && responseData.data.success)) {
throw new Error('Bad response from server.');
}
});
}
Node.js 伺服器收到這項要求後,會將資料儲存至資料庫,以供日後使用。
app.post('/api/save-subscription/', function (req, res) {
if (!isValidSaveRequest(req, res)) {
return;
}
return saveSubscriptionToDatabase(req.body)
.then(function (subscriptionId) {
res.setHeader('Content-Type', 'application/json');
res.send(JSON.stringify({data: {success: true}}));
})
.catch(function (err) {
res.status(500);
res.setHeader('Content-Type', 'application/json');
res.send(
JSON.stringify({
error: {
id: 'unable-to-save-subscription',
message:
'The subscription was received but we were unable to save it to our database.',
},
}),
);
});
});
伺服器上有了 PushSubscription 詳細資料,您隨時可以傳送訊息給使用者。
定期重新訂閱,避免到期
訂閱推播通知時,通常會收到 null 的 PushSubscription.expirationTime。理論上,這表示訂閱項目永不過期。(相較之下,DOMHighResTimeStamp 則表示確切的到期時間)。不過,瀏覽器通常會讓訂閱項目過期。舉例來說,如果使用者長時間未收到推播通知,或瀏覽器偵測到使用者並未使用具有推播通知權限的應用程式,就可能發生這種情況。如要避免這種情況,其中一種模式是在每次收到通知時重新訂閱使用者,如以下程式碼片段所示。因此,您必須經常傳送通知,以免瀏覽器自動將訂閱項目設為過期。請仔細權衡利弊,在合法通知需求與避免訂閱到期而向使用者發送垃圾訊息之間取得平衡。最後,請勿試圖規避瀏覽器的機制,以免使用者收到早已遺忘的通知訂閱。
/* In the Service Worker. */
self.addEventListener('push', function(event) {
console.log('Received a push message', event);
// Display notification or handle data
// Example: show a notification
const title = 'New Notification';
const body = 'You have new updates!';
const icon = '/images/icon.png';
const tag = 'simple-push-demo-notification-tag';
event.waitUntil(
self.registration.showNotification(title, {
body: body,
icon: icon,
tag: tag
})
);
// Attempt to resubscribe after receiving a notification
event.waitUntil(resubscribeToPush());
});
function resubscribeToPush() {
return self.registration.pushManager.getSubscription()
.then(function(subscription) {
if (subscription) {
return subscription.unsubscribe();
}
})
.then(function() {
return self.registration.pushManager.subscribe({
userVisibleOnly: true,
applicationServerKey: urlBase64ToUint8Array('YOUR_PUBLIC_VAPID_KEY_HERE')
});
})
.then(function(subscription) {
console.log('Resubscribed to push notifications:', subscription);
// Optionally, send new subscription details to your server
})
.catch(function(error) {
console.error('Failed to resubscribe:', error);
});
}
常見問題
以下是一些常見問題:
可以變更瀏覽器使用的推送服務嗎?
否,瀏覽器會選取推送服務。如本文在 subscribe() 呼叫中討論,瀏覽器會向推送服務發出網路要求,擷取構成 PushSubscription 的詳細資料。
不同的推播服務是否使用不同的 API?
所有推送服務都預期使用相同的 API。
這個常見的 API 稱為網路推播通訊協定,說明應用程式為觸發推播訊息而提出的網路要求。
如果使用者在電腦上訂閱,是否也會在手機上訂閱?
不行。使用者必須在每個要接收訊息的瀏覽器上註冊推播訊息。使用者也必須在每部裝置上授予權限。
後續步驟
- 網路推播通知總覽
- 推播訊息的運作方式
- 為使用者訂閱方案
- 權限使用者體驗
- 使用網路推播程式庫傳送訊息
- 網頁推送通訊協定
- 處理推送事件
- 顯示通知
- 通知行為
- 常見的通知模式
- 推播通知常見問題
- 常見問題和回報錯誤