ServiceWorkerRegistration: showNotification() メソッド
Baseline
広く利用可能
*
この機能は広く実装されており、多くのバージョンの端末やブラウザーで動作します。2023年3月以降、すべてのブラウザーで利用可能です。
もっと多くのブラウザーがこの機能に対応してほしいですか? 理由を教えてください。
* この機能の一部は、対応レベルにばらつきがある場合があります。
安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。
メモ: この機能はウェブワーカー内で利用可能です。
ServiceWorkerRegistration インターフェイスの showNotification() メソッドは、アクティブなサービスワーカー上で通知を作成します。
構文
showNotification(title)
showNotification(title, options)
引数
title-
通知ウィンドウの上部に表示する通知のタイトルを定義します。
options省略可-
通知に適用するカスタム設定を含むオブジェクトです。指定できるオプションは次のとおりです。
actions省略可-
通知に表示するアクションの配列です。デフォルトは空の配列です。配列内の各要素は、次のメンバーを持つオブジェクトです。
action-
アクション配列内の個々のアクションを一意に識別する文字列です。
navigateURL のないアクションボタンがクリックされたときは、notificationclickイベントリスナー内でevent.actionを確認すると、どのボタンが選択されたか判断できます。 title-
ユーザーに表示するアクションテキストを含む文字列です。
icon省略可-
アクションとともに表示するアイコンの URL を含む文字列です。
-
ユーザーがこのアクションを有効化したときに移動する URL を含む文字列です。 設定すると、ユーザーエージェントは
notificationclickイベントを発生させる代わりに、この URL に移動します。 詳細はNotification.navigateを参照してください。
badge省略可-
ウェブアプリケーション自体を表す小さなアイコンの URL を含む文字列です。 通知全体を表示する十分なスペースがない場合(例えばステータスバーなど)に、プラットフォームがバッジを使用します。
iconおよびimageオプションよりも視覚的な優先度を低くしてください。 Android では、バッジは最大 4 倍のディスプレイ解像度(約 96×96 ピクセル)に対応する必要があり、画像は自動的に単色のシルエットにマスクされます。 body省略可-
通知のタイトルの下に表示する本文テキストを表す文字列です。デフォルトは空文字列です。
data省略可-
通知に関連付ける任意のデータです。任意の構造化複製可能なデータ型を指定できます。デフォルトは
nullです。 dir省略可-
通知を表示する方向です。デフォルトの
autoはブラウザーの言語設定に従いますが、ltrまたはrtlを設定して動作を上書きできます(ただし、ほとんどのブラウザーはこれらの設定を無視するようです)。 icon省略可-
通知を補足する小さな画像(アプリのロゴやメッセージの送信者の写真など)の URL を含む文字列です。通知のタイトルと本文の横に表示されます。
image省略可-
通知の本文の一部として表示する大きな画像(ニュース写真や商品のサムネイルなど)の URL を含む文字列です。3 つの画像オプション(
image、icon、badge)の中で最も視覚的な優先度が高くなります。 lang省略可-
BCP 47 言語タグを表す文字列で指定する通知の言語です。デフォルトは空文字列です。
-
ユーザーが通知を有効化したときに移動する URL を含む文字列です。 設定すると、ユーザーエージェントは
notificationclickイベントを発生させる代わりに、この URL に移動します。 値はサービスワーカーのベース URL を基準に構文解析されます。 詳細はNotification.navigateを参照してください。 renotify省略可-
新しい通知が古い通知を置き換えた後に、ユーザーに通知するかどうかを指定する論理値です。デフォルトの
falseは、ユーザーに通知しないことを示します。trueの場合は、tagも設定する必要があります。 requireInteraction省略可-
通知が自動的に閉じられるのではなく、ユーザーがクリックするか閉じるまでアクティブなままにすることを示します。デフォルト値は
falseです。 silent省略可-
通知を無音(音やバイブレーションを発生させない状態)にするかどうかを、端末の設定にかかわらず指定する論理値です。デフォルトの
nullは端末のデフォルト設定に従うことを示します。trueの場合、vibrateを指定してはいけません。 tag省略可-
通知を識別するタグを表す文字列です。デフォルトは空文字列です。
timestamp省略可-
通知に関連付けられた時刻を表すタイムスタンプです。Unix timeのミリ秒単位で指定します。 端末がオフラインでメッセージをすぐに配信できなかった場合の通知では過去の時刻、これから始まる会議の通知では未来の時刻になることがあります。
vibrate省略可-
通知とともに端末のバイブレーション機能で実行するバイブレーションパターンです。 指定する場合、
silentをtrueにしてはいけません。
返値
undefined に解決する Promise です。
例外
TypeError-
次の場合に発生します。
- 現在のサービスワーカーの状態が
activatingまたはactivatedではない場合。 - ユーザーが、この API を使用するためのブラウザーの許可要求を明示的に拒否した場合。
silentオプションがtrueで、vibrateオプションが指定されている場合。renotifyオプションがtrueで、tagオプションが空の場合。
- 現在のサービスワーカーの状態が
DataCloneErrorDOMException-
dataオプションのシリアライズに失敗した場合に発生します。
例
>基本的な使い方
この例では、サービスワーカー内で実行される関数が、許可を要求して許可された後に通知を表示します。関数を実際に呼び出すコードは示していません。
navigator.serviceWorker.register("sw.js");
async function showNotification() {
const result = await Notification.requestPermission();
if (result === "granted") {
const registration = await navigator.serviceWorker.ready;
registration.showNotification("バイブレーションの例", {
body: "ブンブン! ブンブン!",
icon: "../images/touch/chrome-touch-icon-192x192.png",
vibrate: [200, 100, 200, 100, 200, 100, 200],
tag: "vibration-sample",
});
}
}
次のコードは、この通知に対するユーザー操作を処理するために、notificationclick イベントを監視する方法を示しています。
self.addEventListener("notificationclick", (event) => {
const notification = event.notification;
// 通知が不要になった場合は閉じる。
notification.close();
// 対象の通知を処理する
if (notification.tag === "vibration-sample") {
// Promise が解決するまでサービスワーカーを実行し続けるために event.waitUntil を使用する
event
.waitUntil
// 特定のイベントを処理するコード。
();
}
});
現在のサービスワーカーから発生した Notification の詳細は、ServiceWorkerRegistration.getNotifications() を使用して取得することもできます。
画像の異なる通知
この例では、badge、icon、image の各オプションに、アプリのシンボル、送信者の肖像写真、風景写真という異なる画像を設定します。URL は独自の画像へのパスに置き換えてください。この例では、サービスワーカーが登録済みで、通知の許可が得られているものとします。
const registration = await navigator.serviceWorker.ready;
await registration.showNotification("アレックスから新しい写真", {
body: "アレックスが今日のハイキングの写真を共有しました。",
badge: "/images/app-badge.png",
icon: "/images/alex-avatar.png",
image: "/images/hiking-photo.png",
});
次の図は、デスクトップ、モバイルのホーム画面、モバイルのバナーでこれらの画像がどのように表示されるかを示しています。ステータスバーには badge、タイトルと本文の横には icon、展開された通知には image が表示されます。実際のレイアウトと表示される画像は、ブラウザーとオペレーティングシステムによって異なります。
アクションとアクションハンドラーを使った通知
この例では、例えばメールの受信時にプッシュメッセージによって通知される可能性がある、持続的な通知を表示する方法を示します。
通知を生成するコードには、通知に表示される 2 つの actions が含まれます。1 つはメッセージへの返信用、もう 1 つは通知を閉じるためのものです。
各アクションには title があり、通常は通知上のボタンテキストとして表示されます。また、ユーザーが通知を操作したときに選択されたアクションを識別するための action もあります。
registration.showNotification("新しいメッセージ", {
body: "メールが届いています。",
icon: "/images/icon.png",
actions: [
{ action: "reply", title: "返信" },
{ action: "dismiss", title: "閉じる" },
],
});
次のコードは、通知の notificationclick イベントを監視し、event.action プロパティの値を使用して選択されたアクションを判断する方法を示しています。
ユーザーがアクションボタンではなく通知本文をクリックした場合、event.action は空文字列になることに注意してください。
self.addEventListener("notificationclick", (event) => {
event.notification.close();
if (event.action === "reply") {
// 返信を処理する
} else if (event.action === "dismiss") {
// 通知を閉じる処理を行う
}
});
仕様書
| 仕様書 |
|---|
| Notifications API> # dom-serviceworkerregistration-shownotification> |