iOS のプッシュペイロード

iOS のプッシュペイロードの形式について解説します。
iOS のプッシュペイロードは JSON 形式です。
ここでは、JSON の書き方および主要なキーの解説をします。

プッシュ通知ペイロードの例

以下は一般的なプッシュ通知ペイロードの例です。
このうち aps キーが iOS によって参照されて通知の表示に使われるデータとなり、それ以外のデータはアプリで使う任意のデータとなります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "aps": {
    "alert": {
      "title": "New Message",
      "body":  "新しいメッセージが届きました"
    },
    "sound": "default",
    "interruption-level": "time-sensitive",
    "relevance-score": 0.8
  },
  "screen": "message-detail",
  "message-id": 1100
}

主要なapsキー内のオブジェクト

aps キーは iOS によって参照され、通知の表示や動作に影響します。
ここではよく使われる主要なキーについて解説します。
詳細な情報については Apple から公開されている以下のドキュメントをご確認ください。

• Keys to include in the aps dictionary | Documentation - Apple Inc.
  • HTTP/2 interface を想定している資料です
• Payload Key Reference | Documentation Archive - Apple Inc.
  • binary interface 時代の資料です

aps.alert キー

このキーは通知メッセージに表示される内容を、辞書又は文字列としてセット出来ます。
文字列をセットした場合はその文字列が body にのみセットされているものとして振る舞います。
現在は、辞書をセットすることが推奨されています。

辞書を使用する場合は、以下のようなサブキーを指定できます。

詳細な情報については Apple から公開されている以下のドキュメントをご確認ください。

• Keys to include in the alert dictionary | Documentation - Apple Inc.

aps.badge キー

アプリアイコンの右上に表示する値を数値でセット出来ます。
キーをセットしなかった場合は変更なし、0を指定した場合はバッジが削除されます。

aps.sound キー

再生するサウンドを文字列または辞書でセット出来ます。
アプリのメインバンドル又はアプリのコンテナディレクトリの Library/Sounds にあるファイル名を指定します。
ファイルが見つからない場合や default を指定した場合はデフォルトのサウンドが再生されます。

特別なサウンドを実装したい場合は、Apple から公開されている以下のドキュメントをご確認ください。

• Class UNNotificationSound; The sound played upon delivery of a notification. | Documentation - Apple Inc.

aps.content-available キー

バックグラウンド通知フラグです。
このキーが指定されたプッシュ通知が配信されると、アプリのバックグラウンド更新が起動します。

バックグラウンド更新が実行されるときは application(_:didReceiveRemoteNotification:fetchCompletionHandler:) が呼び出されます。(アプリが起動していない場合は先行して AppDelegate の application(_:, didFinishLaunchingWithOptions:) デリゲートメソッドが呼ばれます)

値に 1 を指定し、payload に alert、badge、sound を含めずに通知を行うと、無音で実行可能です。

1
2
3
4
5
6
7

{
   "aps" : {
      "content-available" : 1
   },
   "acme1" : "bar",
   "acme2" : 42
}

システムはバックグラウンド通知を低優先度で扱います。
バックグラウンド通知を使用してアプリのコンテンツを更新できますが、システムはそれらの配信を保証しません。 更に、総数が過剰になるとシステムはバックグラウンド通知の配信を抑制する可能性があります。 バックグラウンド通知は、1 時間に 2〜3 回程度に抑える必要があります。

このバックグラウンド更新にはいくつか制限があります。

• ユーザーが App スイッチャーからアプリを削除している場合は起動しない。
• 30秒以内に処理を完了させ fetchCompletionHandler を呼び出す必要がある。
• 電力を浪費する場合は起動回数に制限を受ける場合がある。
• その他、端末の状態などによっては起動しない場合がある。

詳細な情報については Apple から公開されている以下のドキュメントをご確認ください。

• Article - Pushing Background Updates to Your App | Documentation - Apple Inc.

aps.mutable-content キー

通知サービス拡張フラグです。
このキーに値 1 が指定されたプッシュ通知が配信されると、アプリに含まれている Notification Service Extension が実行されます。

Notification Service Extension を使うと表示される通知の内容を端末上で一度加工した上でユーザーに表示出来ます。 これにより以下のようなことが可能です。

• 通知本文を暗号化した形式で送信し、データを復号する
• 画像付きなどのリッチプッシュ通知
• デバイスからのデータを用いて通知の内容を書き換える

暗号化通知の例です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
   "aps" : {
      "category" : "SECRET",
      "mutable-content" : 1,
      "alert" : {
         "title" : "Secret Message",
         "body"  : "(Encrypted)"
     },
   },
   "ENCRYPTED_DATA" : "Salted__·öîQÊ$UDì_¶Ù∞èΩ^¬%gq∞NÿÒQùw"
}

BoltzEngine での使用方法については、以下のドキュメントをご確認ください。

• iOS で Extension を使ったプッシュ通知の拡張

詳細な情報については Apple から公開されている以下のドキュメントをご確認ください。

• Article - Modifying Content in Newly Delivered Notifications | Documentation - Apple Inc.

aps.interruption-level キー

iOS 15、macOS 12.0、Mac Catalyst 15.0、tvOS 15.0、watchOS 15.0 以降をターゲットにする場合指定する必要があります。

これらのバージョン以降、Apple 製の端末には集中モード（Focus mode）が実装されます。
システム又はユーザーの任意操作によって定義され、通知を許可する人やアプリケーションが限定されます。 この機能は BoltzEngine によって実装される機能ではないため、回避方法はありません。

このキーには、通知内容の重要性と通知タイミングを示すために指定された文字列をセットします。
セット可能な文字列は以下の通りです。

詳細な情報については Apple から公開されている以下のドキュメント等をご確認ください。

• Enumeration - UNNotificationInterruptionLevel | Documentation - Apple Inc.
• Send communication and Time Sensitive notifications | Videos - Apple Inc.

通知レベルの考え方

passive (iOS15等以降で追加される挙動)

通知音やバイブレーションは鳴動しますが、画面は点灯しません。
通知音もバイブレーションも鳴動せず、画面も点灯しません。
（記載に誤りがありましたので、修正しました：2022-10-14）

また、集中モードで割り込まないように設定されている場合は、割り込めません。

このモードは、すぐに対応する必要がないものや、 いずれ確認してもらうべきものを通知するのに向いています。

具体的には、以下のような通知が対象になると考えられます。

• おすすめの食事
• 新エピソードの解放
• セールの予告
• 実績解除
• ランクアップの予告通知

active

通知音やバイブレーションは鳴動し、画面も点灯します。
しかし、集中モードで割り込まないように設定されている場合は、割り込めません。

今後、Apple が想定しているデフォルトの通知レベルは、このレベルを指します。

具体的には、以下のような通知が対象になると考えられます。

• スポーツ速報
• ニュース速報
• ライブストリーミングの開始通知
• 即時性を求めない一般的な通知
• ユーザーが設定した集中モードを突破してまで通知する必要がないと考えられるもの

time-sensitive (iOS15等以降で追加される挙動)

通知音やバイブレーションは鳴動し、画面も点灯します。
また、集中モードを突破して割り込むことが出来ます。

即時対応を求められるような通知をするのに向いています。

具体的には、以下のような通知が対象になると考えられます。

• アカウントのセキュリティ情報
• 荷物の宅配情報
• 二段階認証の通知
• その他、数分内に何らかの対応を行う必要がある一刻を争うような内容の通知

この通知を受け取るためには、アプリ側の対応も必要です。
Apple Developer Program にログインし、 既存アプリか新規アプリケーションの Capabilities から Push Notifications に合わせて Time Sensitive Notifications を有効にしたプロビジョニングファイルを用いてビルドを行います。

time-sensitive を指定すれば、集中モードが有効になっていても通知が到達するようになります。
一方で、受信するユーザーの心情を考えずにこのモードを乱用すると非常に危険です。

集中モードを使用しているにもかかわらず緊急性がないプロモーション通知が何度も届き続けた場合、 利用者はそのアプリからの通知をミュートして受信しないようにするか、 そのアプリに対してヘイトを抱えたまま削除する可能性があります。

また、ユーザーはシステムから一括で time-sensitive の受信すら拒絶することが可能です。

critical

通知音やバイブレーションは鳴動し、画面も点灯します。
また、集中モードを突破して割り込むことが出来ます。
更に、マナーモードも突破して割り込むことも出来ます。

このレベルの通知を使用するには、Apple から承認された資格が必要です。

具体的には、以下のような通知が対象になると考えられます。

• 荒天情報
  • 気象警報や特別警戒情報
  • ゲリラ豪雨
  • 竜巻注意報
  • ダウンバースト
  • 着氷予想
  • 濃霧情報
  • 台風情報
• 地域の安全情報
  • 土砂災害警戒情報
  • 避難指示情報等
• 緊急地震速報
• 津波到達予測等
• 国民保護に関する情報
• その他、速やかに生命や財産を守るための退避行動を行わないといけない緊急性が高い情報

この通知は、生死に関わるか財産を失う可能性がある通知に用いることが想定されていると考えられます。

aps.relevance-score キー

iOS 15、macOS 12.0、Mac Catalyst 15.0、tvOS 15.0、watchOS 15.0 以降をターゲットにする場合指定を検討すべきです。

これらのバージョン以降、Apple 製の端末には通知要約（Notification Summary）が実装されます。
システム又はユーザーの任意操作によって定義され、特定の時間に要約された通知のみを確認することが可能になります。
一度ここに追加されると、指定された時間になるまで通知が到達しなくなります。
この機能は BoltzEngine によって実装される機能ではないため、回避方法はありません。

このキーには、アプリからの通知を分類するためにシステムが使用する関連性スコアを 0～1 の数値を小数でセット出来ます。
システムは関連性スコアの値を使用して、アプリからの通知を並べ替えます。 最も高いスコアは、通知のサマリーで紹介されます。

通知は要約されてしまうので、同日に何度も同様の通知を送り続けると要約されてインパクトが薄まります。
必ず見て欲しい最も重要な情報に対して高いスコアを振るようにした方が良いです。

また、戦略的に最も高いスコアをつける通知は目立たせるのが良いと思われます。
例えば、タイトルを短くインパクトがあるものにして更に絵文字を用いたり、 リッチプッシュを用いて目立つように仕立てると良いと思われますが、 このストラテジは絶対的なものではありません。

対象ユーザー層を正しく理解した上で、適切なアプローチを行うようにして下さい。

詳細な情報については Apple から公開されている以下のドキュメント等をご確認ください。

• Instance Property - relevanceScore | Documentation - Apple Inc.
• Send communication and Time Sensitive notifications | Videos - Apple Inc.