Customize the notification payload
Not supported
通知ペイロードのカスタマイズは、接客サービス内アクションのカスタマイズで設定することができます。
接客のカスタマイズはサポート対象外となりますので、必ずテスト配信等行った上でご活用ください。
KARTEのプッシュ通知では、バックエンドに Firebase Cloud Messaging (以下FCM) を採用しています。
そのため通知ペイロードをカスタマイズするにあたっては、基本的に FCM v1 APIのペイロード仕様を理解しておく必要があります。
加えて iOS 向けの通知ペイロードをカスタマイズする場合は、別途 APNs のペイロード仕様についても理解しておく必要があります。
FCM v1 API ペイロード仕様
https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages
通知アクションの設定について
If you want to send push notifications from KARTE, you need to set the notification action using the push notification template provided by KARTE by default.
プッシュ通知テンプレートでは一般的によく利用されるペイロード値を変数としてデフォルト定義しており、容易にプッシュ通知の送信設定を行えるようになっています。
なおデフォルトで定義されているもの以外で送信したい値がある場合は、独自に変数を定義することで送信することが可能です。
この方法については、プラットフォーム固有のペイロード値の設定方法について および アプリケーション上で利用する独自変数の設定方法について をご覧ください。
デフォルト変数とペイロード値の対応関係について
Several static variables are defined by default in the template.
The correspondence between static variables and payload values defined by default is described in the following table.
Android関連
Static variable name | Payload object path | Contents |
---|---|---|
title | message.android.data.krt_attributes.title | Notification title |
body | message.android.data.krt_attributes.body | Notification body |
sound_for_android | message.android.data.krt_attributes.sound | Sound name to sound when notification is received |
android_channel_id | message.android.data.krt_attributes.android_channel_id | Channel ID |
url | message.android.data.krt_attributes.url | Transition destination at notification opening (URL / deep link) |
attachment_url | message.android.data.krt_attributes.attachment_url | File (image / video / audio) URL to be displayed in notification |
iOS関連
Static variable name | Payload object path | Contents |
---|---|---|
title | message.apns.payload.aps.alert.title | Notification title |
body | message.apns.payload.aps.alert.body | Notification body |
sound_for_ios | message.apns.payload.aps.sound | Sound name to sound when notification is received |
badge_for_ios | message.apns.payload.aps.badge | badge |
content_available | message.apns.payload.aps.content-available | サイレント通知のフラグ サイレント通知の対応方法はドキュメントをご確認ください |
thread_id | message.apns.payload.aps.thread-id | Thread ID |
url | message.apns.payload.krt_attributes | Transition destination at notification opening (URL / deep link) |
attachment_url | message.apns.payload.krt_attributes | File (image / video / audio) URL to be displayed in notification |
テーブルに記載がない静的変数に関して
app_name
やformat_type
など一部の静的変数は、KARTE内部でのみ使用される変数になるため通知ペイロードには含まれません。
なお、これらの静的変数は動作上必要な変数であるため削除しないようにしてください。
プラットフォーム固有のペイロード値の設定方法について
FCMの通知ペイロードにはプラットフォーム固有の値が存在します。
デフォルト変数以外のプラットフォーム (Android / iOS) 固有の値を送信したい場合は、独自に静的変数を定義することで可能です。
静的変数名に、ペイロードに含まれるオブジェクトのプロパティ名をドットで結合したもの(ペイロードオブジェクトパス)を指定すると、FCMの通知ペイロードに展開して配信されます。
ペイロードオブジェクトパスの指定の際は、静的変数名にドットを含める形の記述で指定可能です。
また、KARTEの静的変数では、変数名に「ハイフン(-)」は使用できないため指定の際にエラーとなりますが、ペイロードの指定に際しては、エラーを無視して保存することで設定頂けます。
例:プッシュ通知の有効期限 (ttl
/ apns-expiration
) を指定する場合
FCM v1 API Payload (excludes only the part related to the specification of expiration date)
{
"validate_only": false,
"message": {
"android": {
"ttl": "86400s",
"data": {
}
},
"apns": {
"headers": {
"apns-expiration": "1556636400",
},
"payload": {
}
}
}
}
この場合の静的変数名は以下のようになります (message
部分は静的変数名には含めません)
android.ttl
apns.headers.apns-expiration
なお上記のような、ぺイロードオブジェクトパスを静的変数名に指定したペイロードカスタマイズは、プラットフォーム固有のオブジェクト (message.android / message.apns) 配下の値に限り、利用可能です。
その他の値は、展開されないか、配信時エラーとなります。
Interruption levels(iOS 15以上)の設定方法について
集中モード時の通知の届き方をコントロールするために Interruption levels を設定することが可能です。
例えば interruption-level を time-sensitive に設定したい場合、以下表のように静的変数と値を設定ください。
なお、Time Sensitive Notifications の受信にはアプリ側の対応が必要です、詳細は Appleの公式資料 を参照ください。
Static variable name | value |
---|---|
apns.payload.aps.interruption-level | time-sensitive |
relevance score(iOS 15以上)の設定方法について
通知要約の並び順に影響を与えるために関連スコア(relevance score) を設定することが可能です。
例えば relevance score を最大値にしたい場合、以下表のように静的変数と値を設定します。
詳細は Generating a Remote Notification(Apple公式ドキュメント) やrelevanceScore(Apple公式リファレンス)を参照ください。
Static variable name | value |
---|---|
apns.payload.aps.relevance-score | 1.0 |
アプリケーション上で利用する独自変数の設定方法について
KARTEから配信するプッシュ通知に、アプリケーション上で利用したい独自の変数を設定することが可能です。
アクション設定画面にて静的変数を設定することで、プッシュ通知のペイロードに展開されます。
参考:静的変数の利用
独自変数の設定方法
If you want to set your own variable to be used in the application, please define a static variable of any name.
例:静的変数 query
を定義する場合
静的変数名を query
とした変数を設定することで、下記の表のペイロードオブジェクトパスに変数が配置されます。
プラットフォーム毎に別々の変数を配信したい場合は、前項 プラットフォーム固有のペイロード値の設定方法について を参照し、 android.data.query
/ apns.payload.query
という変数名にすることで、配信プラットフォームを制御することができます。
Static variable name | platform | Payload object path |
---|---|---|
query or android.data.query | Android | message.android.data.query |
query or apns.payload.query | iOS | message.apns.payload.query |
注意が必要な静的変数名
静的変数名が
android.
およびapns.
から始まる名前を指定する場合、プラットフォーム固有のペイロード値の設定方法について に基づいて値が設定されるため、意図した通りに値の設定が行えない点ご注意ください。
設定した値の参照方法
If you want to reference your own variables in the application, please implement according to the following.
例:静的変数 query
を参照する場合
Static variable namequery
(プラットフォーム毎の場合: android.data.query
/ apns.payload.query
) の変数は、FCMの通知ペイロードに展開されるため、下記のような実装で参照できます。
Android
class MyFirebaseMessagingService : FirebaseMessagingService() {
override fun onMessageReceived(remoteMessage: RemoteMessage?) {
val query = remoteMessage?.data?.get("query")
...
}
}
public class MyFirebaseMessagingService extends FirebaseMessagingService {
public void onMessageReceived(RemoteMessage remoteMessage) {
String query = remoteMessage.getData().get("query");
...
}
}
iOS
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
let query = userInfo["query"] as? String
...
}
// UNUserNotificationCenterDelegate (iOS10-)
func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
let userInfo = response.notification.request.content.userInfo
let query = userInfo["query"] as? String
...
}
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(nonnull NSDictionary *)userInfo fetchCompletionHandler:(nonnull void (^)(UIBackgroundFetchResult))completionHandler
{
NSString *query = userInfo[@"query"];
...
}
// UNUserNotificationCenterDelegate (iOS10-)
- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler
API_AVAILABLE(ios(10.0)) {
NSDictionary *userInfo = response.notification.request.content.userInfo;
NSString *query = userInfo[@"query"];
...
}
ペイロード未指定の場合のデフォルト値
基本的にテンプレートで指定された値のみペイロードに設定されますが、
数点例外があり、以下のパラメータについてはKARTE側でデフォルトで設定されます。
尚、デフォルト値は予告なく変更する可能性があります。
message.android.priority = 'HIGH'
message.ios.headers.apns-priority = 10
message.ios.headers.apns-push-type = alert
以下の値は、画像等のファイルが添付されている場合に限り設定されます。
message.ios.payload.aps.mutable-content = 1
以下の値は、設定されていたとしても削除されます。
message.android.notification
Updated 12 months ago