🚧

サポート対象外

通知ペイロードのカスタマイズは、接客サービス内アクションのカスタマイズで設定することができます。
接客のカスタマイズはサポート対象外となりますので、必ずテスト配信等行った上でご活用ください。

KARTEのプッシュ通知では、バックエンドに Firebase Cloud Messaging (以下FCM) を採用しています。
そのため通知ペイロードをカスタマイズするにあたっては、基本的に FCM v1 APIのペイロード仕様を理解しておく必要があります。
加えて iOS 向けの通知ペイロードをカスタマイズする場合は、別途 APNs のペイロード仕様についても理解しておく必要があります。

📘

FCM v1 API ペイロード仕様

https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages

通知アクションの設定について

KARTEからプッシュ通知を送信する場合は、KARTEがデフォルトで用意しているプッシュ通知テンプレートを利用して通知アクションの設定を行う必要があります。

プッシュ通知テンプレートでは一般的によく利用されるペイロード値を変数としてデフォルト定義しており、容易にプッシュ通知の送信設定を行えるようになっています。
なおデフォルトで定義されているもの以外で送信したい値がある場合は、独自に変数を定義することで送信することが可能です。
この方法については、プラットフォーム固有のペイロード値の設定方法について および アプリケーション上で利用する独自変数の設定方法について をご覧ください。

デフォルト変数とペイロード値の対応関係について

テンプレートにはいくつかの静的変数がデフォルトで定義されています。
デフォルトで定義されている静的変数とペイロード値との対応関係は、以下の表に記載しています。

Android関連

iOS関連

🚧

テーブルに記載がない静的変数に関して

app_name や format_type など一部の静的変数は、KARTE内部でのみ使用される変数になるため通知ペイロードには含まれません。
なお、これらの静的変数は動作上必要な変数であるため削除しないようにしてください。

プラットフォーム固有のペイロード値の設定方法について

デフォルト変数以外のプラットフォーム (Android / iOS) 固有の値を送信したい場合は、独自に静的変数を定義する必要があります。
なお静的変数名はペイロードに含まれるオブジェクトのプロパティ名をドットで結合したものを指定する必要があります。

例：プッシュ通知の有効期限 (ttl / apns-expiration) を指定する場合

FCM v1 API ペイロード (有効期限の指定に関連する箇所だけを抜粋)

{
  "validate_only": false,
  "message": {
    ...
    "android": {
      "ttl": "86400s",
      "data": {
        ...
      }
    },
    "apns": {
      "headers": {
        "apns-expiration": "1556636400",
        ...
      },
      "payload": {
        ...
      }
    }
  }
}

この場合の静的変数名は以下のようになります (message 部分は静的変数名には含めません)

• android.ttl
• apns.headers.apns-expiration

なおプラットフォーム固有のオブジェクト (android / apns) 配下の値に限り、上記の形での指定が可能です。

Interruption levels（iOS 15以上）の設定方法について

集中モード時の通知の届き方をコントロールするために Interruption levels を設定することが可能です。
例えば interruption-level を time-sensitive に設定したい場合、以下表のように静的変数と値を設定ください。
なお、Time Sensitive Notifications の受信にはアプリ側の対応が必要です、詳細は Appleの公式資料 を参照ください。

relevance score（iOS 15以上）の設定方法について

通知要約の並び順に影響を与えるために関連スコア（relevance score） を設定することが可能です。
例えば relevance score を最大値にしたい場合、以下表のように静的変数と値を設定します。
詳細は Generating a Remote Notification（Apple公式ドキュメント） やrelevanceScore（Apple公式リファレンス）を参照ください。

アプリケーション上で利用する独自変数の設定方法について

独自変数の設定方法

アプリケーション上で利用する独自変数を設定したい場合は、任意の名前の静的変数を定義してください。

例：query という静的変数を定義する場合

設定した静的変数が配置される場所は、以下の通りです。

🚧

注意が必要な静的変数名

静的変数名が android. および apns. から始まる名前を指定する場合、プラットフォーム固有のペイロード値の設定方法について に基づいて値が設定されるため、意図した通りに値の設定が行えない点ご注意ください。

設定した値の参照方法

独自変数をアプリケーション上で参照したい場合は、以下を参考に実装を行なってください。

例：query という静的変数を参照する場合

Android

class MyFirebaseMessagingService : FirebaseMessagingService() {

  override fun onMessageReceived(remoteMessage: RemoteMessage?) {
    val query = remoteMessage?.data?.get("query")
    ...
  }
}

public class MyFirebaseMessagingService extends FirebaseMessagingService {

  @Override
  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