@capacitor/push-notifications
プッシュ通知APIは、ネイティブプッシュ通知へのアクセスを提供します。
インストール
npm install @capacitor/push-notifications
npx cap sync
iOS
iOSでは、プッシュ通知機能を有効にする必要があります。機能の有効化方法については、機能の設定を参照してください。
プッシュ通知機能を有効にしたら、アプリの AppDelegate.swift に以下を追加します。
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
NotificationCenter.default.post(name: .capacitorDidRegisterForRemoteNotifications, object: deviceToken)
}
func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
NotificationCenter.default.post(name: .capacitorDidFailToRegisterForRemoteNotifications, object: error)
}
Android
プッシュ通知APIは、通知の処理にFirebase Cloud Messaging SDKを使用します。AndroidでFirebase Cloud Messagingクライアントアプリをセットアップするを参照し、Firebaseプロジェクトを作成し、アプリケーションを登録する手順に従ってください。Firebase SDKをアプリに追加したり、アプリのマニフェストを編集したりする必要はありません。プッシュ通知がそれを提供します。必要なのは、Firebaseプロジェクトの google-services.json ファイルをアプリのモジュール（アプリレベル）ディレクトリに追加することだけです。
Android 13では、プッシュ通知を受信するために権限チェックが必要です。SDK 33をターゲットにする場合は、必要に応じて checkPermissions() と requestPermissions() を呼び出す必要があります。
変数
このプラグインは、以下のプロジェクト変数（アプリの variables.gradle ファイルで定義）を使用します。
firebaseMessagingVersioncom.google.firebase:firebase-messagingのバージョン（デフォルト:23.3.1）
プッシュ通知アイコン
Androidでは、適切な名前のプッシュ通知アイコンを AndroidManifest.xml ファイルに追加する必要があります。
<meta-data android:name="com.google.firebase.messaging.default_notification_icon" android:resource="@mipmap/push_icon_name" />
アイコンが指定されていない場合、Androidはアプリケーションアイコンを使用しますが、プッシュアイコンは透明な背景に白いピクセルである必要があります。アプリケーションアイコンは通常そうではないため、白い正方形または円が表示されます。したがって、プッシュ通知用に別のアイコンを提供することをお勧めします。
Android Studioには、プッシュ通知アイコンを作成するために使用できるアイコンジェネレーターがあります。
プッシュ通知チャネル
Android 8.0（APIレベル26）以降では、通知チャネルがサポートされ、推奨されています。SDKは、受信プッシュ通知の channelId を次の順序で導出します。
- まず、受信した通知に
channelIdが設定されているかどうかを確認します。 FCMダッシュボードまたはAPIからプッシュ通知を送信する場合、channelIdを指定できます。 - 次に、
AndroidManifest.xmlで可能な値があるかどうかを確認します。独自のデフォルトチャネルを作成して使用する場合は、以下に示すように、通知チャネルオブジェクトのIDにdefault_notification_channel_idを設定します。FCMは、受信メッセージが通知チャネルを明示的に設定していない場合にこの値を使用します。
<meta-data
android:name="com.google.firebase.messaging.default_notification_channel_id"
android:value="@string/default_notification_channel_id" />
- 最後に、Firebase SDKが提供するフォールバック
channelIdを使用します。FCMは、基本的な設定を備えたデフォルトの通知チャネルをすぐに提供します。このチャネルは、最初のプッシュメッセージを受信すると、Firebase SDKによって作成されます。
警告 オプション1または2を使用する場合でも、選択したオプションで使用したIDと一致するIDを持つ通知チャネルをコードで作成する必要があります。これには、
createChannel(...)を使用できます。これを行わないと、SDKはオプション3にフォールバックします。
フォアグラウンドでのプッシュ通知の表示
アプリがフォアグラウンドにあるときにプッシュ通知を表示する方法を構成できます。
| プロパティ | タイプ | 説明 | 開始バージョン |
|---|---|---|---|
presentationOptions | PresentationOption[] | これは、組み合わせることができる文字列の配列です。配列内の可能な値は次のとおりです： - badge：アプリのアイコンのバッジカウントが更新されます（デフォルト値） - sound：プッシュ通知を受信すると、デバイスが鳴ったり振動したりします - alert：プッシュ通知がネイティブダイアログに表示されます オプションが不要な場合は、空の配列を指定できます。badgeはiOSでのみ使用できます。 | 1.0.0 |
例
capacitor.config.json で
{
"plugins": {
"PushNotifications": {
"presentationOptions": ["badge", "sound", "alert"]
}
}
}
capacitor.config.ts で
/// <reference types="@capacitor/push-notifications" />
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
plugins: {
PushNotifications: {
presentationOptions: ["badge", "sound", "alert"],
},
},
};
export default config;
サイレントプッシュ通知/データ専用通知
iOS
このプラグインは、iOSサイレントプッシュ（リモート通知）をサポートしていません。これらのタイプの通知を処理するには、ネイティブコードソリューションを使用することをお勧めします。アプリへのバックグラウンドアップデートのプッシュを参照してください。
Android
このプラグインはデータ専用通知をサポートしていますが、アプリが強制終了された場合は pushNotificationReceived を呼び出しません。このシナリオを処理するには、FirebaseMessagingService を拡張するサービスを作成する必要があります。FCMメッセージの処理を参照してください。
一般的な問題
Androidでは、プッシュ通知の配信に影響を与える可能性のあるさまざまなシステムおよびアプリの状態があります。
- デバイスがDozeモードに入った場合、アプリケーションの機能が制限される可能性があります。通知が受信される可能性を高めるには、FCM高優先度メッセージの使用を検討してください。
- 開発環境と本番環境では動作が異なります。Android Studioから起動されたアプリ以外でテストしてください。詳細については、こちらをご覧ください。
例
import { PushNotifications } from '@capacitor/push-notifications';
const addListeners = async () => {
await PushNotifications.addListener('registration', token => {
console.info('Registration token: ', token.value);
});
await PushNotifications.addListener('registrationError', err => {
console.error('Registration error: ', err.error);
});
await PushNotifications.addListener('pushNotificationReceived', notification => {
console.log('Push notification received: ', notification);
});
await PushNotifications.addListener('pushNotificationActionPerformed', notification => {
console.log('Push notification action performed', notification.actionId, notification.inputValue);
});
}
const registerNotifications = async () => {
let permStatus = await PushNotifications.checkPermissions();
if (permStatus.receive === 'prompt') {
permStatus = await PushNotifications.requestPermissions();
}
if (permStatus.receive !== 'granted') {
throw new Error('User denied permissions!');
}
await PushNotifications.register();
}
const getDeliveredNotifications = async () => {
const notificationList = await PushNotifications.getDeliveredNotifications();
console.log('delivered notifications', notificationList);
}
API
register()unregister()getDeliveredNotifications()removeDeliveredNotifications(...)removeAllDeliveredNotifications()createChannel(...)deleteChannel(...)listChannels()checkPermissions()requestPermissions()addListener('registration', ...)addListener('registrationError', ...)addListener('pushNotificationReceived', ...)addListener('pushNotificationActionPerformed', ...)removeAllListeners()- インターフェース
- 型エイリアス
register()
register() => Promise<void>
プッシュ通知を受信するためにアプリを登録します。
このメソッドは、プッシュトークンで 'registration' イベントをトリガーするか、問題が発生した場合は 'registrationError' をトリガーします。通知権限を求めるプロンプトは表示されません。最初に requestPermissions() を使用してください。
開始バージョン 1.0.0
unregister()
unregister() => Promise<void>
プッシュ通知からのアプリの登録を解除します。
これにより、Androidでfirebaseトークンが削除され、iOSでAPNSの登録が解除されます。
開始バージョン 5.0.0
getDeliveredNotifications()
getDeliveredNotifications() => Promise<DeliveredNotifications>
通知画面に表示されている通知のリストを取得します。
戻り値: Promise<DeliveredNotifications>
開始バージョン 1.0.0
removeDeliveredNotifications(...)
removeDeliveredNotifications(delivered: DeliveredNotifications) => Promise<void>
通知画面から指定された通知を削除します。
| パラメータ | タイプ |
|---|---|
delivered | DeliveredNotifications |
開始バージョン 1.0.0
removeAllDeliveredNotifications()
removeAllDeliveredNotifications() => Promise<void>
通知画面からすべての通知を削除します。
開始バージョン 1.0.0
createChannel(...)
createChannel(channel: Channel) => Promise<void>
通知チャネルを作成します。
Android O 以降（SDK 26 以降）でのみ利用可能です。
| パラメータ | タイプ |
|---|---|
channel | Channel |
開始バージョン 1.0.0
deleteChannel(...)
deleteChannel(args: { id: string; }) => Promise<void>
通知チャネルを削除します。
Android O 以降（SDK 26 以降）でのみ利用可能です。
| パラメータ | タイプ |
|---|---|
args | { id: string; } |
開始バージョン 1.0.0
listChannels()
listChannels() => Promise<ListChannelsResult>
利用可能な通知チャネルをリスト表示します。
Android O 以降（SDK 26 以降）でのみ利用可能です。
戻り値: Promise<ListChannelsResult>
開始バージョン 1.0.0
checkPermissions()
checkPermissions() => Promise<PermissionStatus>
プッシュ通知を受信する許可を確認します。
Android 12 以下では、プッシュ通知は常に受信可能であるため、ステータスは常に許可になります。ユーザーが通知を表示することを許可しているかどうかを確認する必要がある場合は、local-notificationsプラグインを使用してください。
戻り値: Promise<PermissionStatus>
開始バージョン 1.0.0
requestPermissions()
requestPermissions() => Promise<PermissionStatus>
プッシュ通知を受信する許可を要求します。
Android 12 以下では、プッシュ通知は常に受信可能であるため、許可を求めるプロンプトは表示されません。
iOSでは、この関数を初めて使用するときに、ユーザーにプッシュ通知の許可を求めるプロンプトが表示され、ユーザーの選択に基づいて許可または拒否が返されます。それ以降の呼び出しでは、再度プロンプトを表示せずに、現在の許可ステータスを取得します。
戻り値: Promise<PermissionStatus>
開始バージョン 1.0.0
addListener('registration', ...)
addListener(eventName: 'registration', listenerFunc: (token: Token) => void) => Promise<PluginListenerHandle>
プッシュ通知の登録が問題なく完了したときに呼び出されます。
プッシュ通知トークンを提供します。
| パラメータ | タイプ |
|---|---|
eventName | 'registration' |
listenerFunc | (token: Token) => void |
戻り値: Promise<PluginListenerHandle>
開始バージョン 1.0.0
addListener('registrationError', ...)
addListener(eventName: 'registrationError', listenerFunc: (error: RegistrationError) => void) => Promise<PluginListenerHandle>
プッシュ通知の登録が問題ありで終了したときに呼び出されます。
登録の問題を示すエラーを提供します。
| パラメータ | タイプ |
|---|---|
eventName | 'registrationError' |
listenerFunc | (error: RegistrationError) => void |
戻り値: Promise<PluginListenerHandle>
開始バージョン 1.0.0
addListener('pushNotificationReceived', ...)
addListener(eventName: 'pushNotificationReceived', listenerFunc: (notification: PushNotificationSchema) => void) => Promise<PluginListenerHandle>
デバイスがプッシュ通知を受信したときに呼び出されます。
| パラメータ | タイプ |
|---|---|
eventName | 'pushNotificationReceived' |
listenerFunc | (notification: PushNotificationSchema) => void |
戻り値: Promise<PluginListenerHandle>
開始バージョン 1.0.0
addListener('pushNotificationActionPerformed', ...)
addListener(eventName: 'pushNotificationActionPerformed', listenerFunc: (notification: ActionPerformed) => void) => Promise<PluginListenerHandle>
プッシュ通知に対してアクションが実行されたときに呼び出されます。
| パラメータ | タイプ |
|---|---|
eventName | 'pushNotificationActionPerformed' |
listenerFunc | (notification: ActionPerformed) => void |
戻り値: Promise<PluginListenerHandle>
開始バージョン 1.0.0
removeAllListeners()
removeAllListeners() => Promise<void>
このプラグインのすべてのネイティブリスナーを削除します。
開始バージョン 1.0.0
インターフェース
DeliveredNotifications
| プロパティ | タイプ | 説明 | 開始バージョン |
|---|---|---|---|
notifications | PushNotificationSchema[] | 通知画面に表示される通知のリスト。 | 1.0.0 |
PushNotificationSchema
| プロパティ | タイプ | 説明 | 開始バージョン |
|---|---|---|---|
title | string | 通知のタイトル。 | 1.0.0 |
subtitle | string | 通知のサブタイトル。 | 1.0.0 |
body | string | 通知のメインテキストペイロード。 | 1.0.0 |
id | string | 通知の識別子。 | 1.0.0 |
tag | string | 通知のタグ。Android（プッシュ通知から）でのみ利用可能です。 | 4.0.0 |
badge | number | アプリのアイコンバッジに表示する数値。 | 1.0.0 |
notification | any | 返されません。 | 1.0.0 |
data | any | プッシュ通知ペイロードに含まれていた追加データ。 | 1.0.0 |
click_action | string | ユーザーが通知を開いたときに実行されるアクション。Androidでのみ利用可能です。 | 1.0.0 |
link | string | 通知からのディープリンク。Androidでのみ利用可能です。 | 1.0.0 |
group | string | 通知のグループ化に使用するグループ識別子を設定します。Androidでのみ利用可能です。iOSのthreadIdentifierのように機能します。 | 1.0.0 |
groupSummary | boolean | この通知を、関連するgroupの概要として指定します。Androidでのみ利用可能です。 | 1.0.0 |
Channel
| プロパティ | タイプ | 説明 | id | 開始バージョン |
|---|---|---|---|---|
id | string | チャネル識別子。 | 1.0.0 | |
name | string | このチャネルの人間が読める名前（ユーザーに提示されます）。 | 1.0.0 | |
description | string | このチャネルの説明（ユーザーに提示されます）。 | 1.0.0 | |
sound | string | このチャネルに投稿された通知に対して再生されるサウンド。重要度が少なくとも3の通知チャネルにはサウンドが必要です。サウンドファイルのファイル名は、androidアプリのres/rawディレクトリからの相対パスで指定する必要があります。 | 1.0.0 | |
importance | Importance | このチャネルに投稿された通知の中断レベル。 | | 1.0.0 |
visibility | Visibility | このチャネルに投稿された通知の可視性。この設定は、このチャネルに投稿された通知をロック画面に表示するかどうか、および表示する場合に、編集された形式で表示するかどうかを設定します。 | 1.0.0 | |
lights | boolean | このチャネルに投稿された通知が、サポートするデバイスで通知ライトを表示するかどうか。 | 1.0.0 | |
lightColor | string | このチャネルに投稿された通知のライトの色。このチャネルでライトが有効になっており、デバイスがそれをサポートしている場合にのみサポートされます。サポートされている色の形式は、#RRGGBBと#RRGGBBAAです。 | 1.0.0 | |
vibration | boolean | このチャネルに投稿された通知を振動させるかどうか。 | 1.0.0 |
ListChannelsResult
| プロパティ | タイプ | 説明 | 開始バージョン |
|---|---|---|---|
channels | Channel[] | アプリによって作成されたすべてのチャネルのリスト。 | 1.0.0 |
PermissionStatus
| プロパティ | タイプ | 説明 | 開始バージョン |
|---|---|---|---|
receive | PermissionState | 通知を受信する許可の状態。 | 1.0.0 |
PluginListenerHandle
| プロパティ | タイプ |
|---|---|
remove | () => Promise<void> |
Token
| プロパティ | タイプ | 説明 | 開始バージョン |
|---|---|---|---|
value | string | iOSではAPNSトークンが含まれます。AndroidではFCMトークンが含まれます。 | 1.0.0 |
RegistrationError
| プロパティ | タイプ | 説明 | 開始バージョン |
|---|---|---|---|
error | string | 登録の失敗を説明するエラーメッセージ。 | 4.0.0 |
ActionPerformed
| プロパティ | タイプ | 説明 | 開始バージョン |
|---|---|---|---|
actionId | string | 通知で実行されたアクション。 | 1.0.0 |
inputValue | string | 通知アクションで入力されたテキスト。iOSでのみ利用可能です。 | 1.0.0 |
notification | PushNotificationSchema | アクションが実行された通知。 | 1.0.0 |
タイプエイリアス
Importance
重要度レベル。詳細については、Androidデベロッパーのドキュメントを参照してください
1 | 2 | 3 | 4 | 5Visibility
通知の可視性。詳細については、Androidデベロッパーのドキュメントを参照してください
-1 | 0 | 1PermissionState
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'