キーと値のペア
このページでは、キーと値のペアを使用してユーザーデバイスに追加のデータペイロードを送信する方法について説明します。この機能は、プッシュ、アプリ内メッセージ、メール、Content Cardsのメッセージングチャネルで利用できます。
キーと値のペアを使用すると、メッセージに構造化されたメタデータを追加できます。これらの追加データペイロードにより、メッセージのレンダリングや処理方法に影響を与える、文脈に応じた追加情報でメッセージを充実させることができます。
キーと値のペアはメタデータであるため、このデータは必ずしも受信者に表示されるわけではありませんが、接続されたシステムやプロセスでメッセージの処理をカスタマイズするために使用できます。
各ペアは以下で構成されます。
- キー: 識別子(例:
utm_source) - 値: 関連するデータ(例:
newsletter)
ユースケース
キーと値のペアでメタデータを追加するユースケースの例を次に示します。
- トラッキングパラメーター: 分析目的で UTM パラメーターを付加する
- キー:
utm_campaign - 値:
spring_sale
- キー:
- カスタムタグ: 内部ルーティングや分類のためにタグを追加する
- キー:
priority - 値:
high
- キー:
- 動作トリガー: アプリ内の動作をトリガーまたはカスタマイズするために使用するメタデータ
- キー:
deep_link - 値:
app://promo-page
- キー:
プッシュ通知
キーと値のペアは、Android、iOS、Web のプッシュ通知に追加できます。キーと値のペアを使用すると、内部メトリクスやアプリのコンテンツを更新したり、アラートの優先度、ローカライゼーション、サウンドなどのプッシュ通知プロパティをカスタマイズしたりできます。
メッセージ作成画面で設定タブを選択し、新しいペアを追加を選択して、キーと値のペアを指定します。
メッセージ作成画面でキーと値のペアを追加すると、値は文字列として送信されます。iOS プッシュの場合、アラートオプションから追加した Apple Push Notification service (APNs) の予約済みアラートキー (ローカライゼーション引数の loc-args など) は、ペイロード内で正しい JSON 型にフォーマットされます。カスタムキーの場合、統合でパースしない限り、アプリは文字列値を受け取ります。
iOS
Apple Push Notification service (APNs) では、キーと値のペアを使用して、アラートの設定やカスタムデータの送信ができます。APNs は Apple が予約している aps ライブラリーを使用します。このライブラリーには、アラートのプロパティを制御するあらかじめ定められたキーと値が含まれています。
APS ライブラリー
| キー | 値の型 | 値の説明 |
|---|---|---|
| alert | 文字列または辞書オブジェクト | 文字列が入力された場合は、その文字列をメッセージとして、閉じるボタンと表示ボタン付きのアラートを表示します。文字列以外が入力された場合は、入力の子プロパティに応じてアラートまたはバナーを表示します |
| badge | 数値 | アプリアイコンにバッジとして表示される数値を制御します |
| sound | 文字列 | アラートとして再生するサウンドファイルの名前。アプリのバンドルまたは Library/Sounds フォルダーに配置されている必要があります |
| content-available | 数値 | 入力値が 1 の場合、起動時またはセッション再開時に新しい情報が利用可能であることをアプリに通知します |
アラートプロパティライブラリー
| キー | 値の型 | 値の説明 |
|---|---|---|
| title | 文字列 | 通知の一部として Apple Watch に短時間表示される短い文字列 |
| body | 文字列 | プッシュ通知のコンテンツ |
| title-loc-key | 文字列または null | Localizable.strings ファイルから、現在のローカライゼーションのタイトル文字列を設定するキー |
| title-loc-args | 文字列の配列または null | title-loc-key 内のタイトルのローカライゼーション書式指定子の代わりに表示できる文字列値 |
| action-loc-key | 文字列の配列または null | 存在する場合、指定された文字列によって閉じるボタンと表示ボタンのローカライゼーションが設定されます |
| loc-key | 文字列または null | Localizable.strings ファイルから、現在のローカライゼーションの通知メッセージを設定するキー |
| loc-args | 文字列の配列 | loc-key 内のローカライゼーション書式指定子の代わりに表示できる文字列値 |
| launch-image | 文字列 | ユーザーがアクションボタンをタップしたとき、またはアクションスライダーを動かしたときに起動画像として使用する、アプリバンドル内の画像ファイルの名前 |
Braze のメッセージ作成画面では、alert とそのプロパティ、content-available、sound、category のキーが自動的に作成されます。
これらの値は、プッシュメッセージを作成する際に設定タブで入力できます。アラートオプションを選択し、アラート辞書キーを選択すると、そのキーが新しいキーと値のエントリに自動的に入力されます。

Braze が APNs にプッシュ通知を送信する際、ペイロードは JSON 形式でフォーマットされます。
シンプルなペイロード
{
"aps" : { "alert" : "Message received from Spencer" },
}
複雑なペイロード
{
"aps" : {
"alert" : {
"body" : "Hi, welcome to our app!",
"loc-key" : "France",
"loc-args" : ["Bonjour", "bienvenue"],
"action-loc-key" : "Button_Type_1",
"launch-image" : "Paris"
},
"content-available" : 1
},
}
カスタムのキーと値のペア
aps ライブラリーのペイロード値に加えて、カスタムのキーと値のペアをユーザーのデバイスに送信できます。これらのペアの値は、辞書 (オブジェクト)、配列、文字列、数値、ブール値のプリミティブ型に制限されます。

カスタムのキーと値のペアのユースケースには、内部メトリクスの記録やユーザーインターフェイスのコンテキスト設定などがありますが、これらに限定されません。Braze では、プッシュ通知とともに追加のキーと値のペアを送信し、extras キー内でアプリケーション全体で使用できます。別のキーを使用する場合は、アプリがそのカスタムキーを処理できることを確認してください。

アプリケーションで、ab という名前のトップレベルのキーまたは辞書を処理しないようにしてください。
Apple は、顧客情報や機密データをカスタムペイロードデータとして含めないようクライアントに勧めています。さらに Apple は、アラートメッセージに関連付けられたアクションでデバイス上のデータを削除しないよう推奨しています。

HTTP/2 プロバイダー API を使用している場合、APNs に送信する個々のペイロードのサイズは 4096 バイトを超えることはできません。まもなく廃止予定の従来のバイナリーインターフェイスでは、2048 バイトのペイロードサイズのみサポートされます。
API トリガーキャンペーン
Braze では、extras と呼ばれる、カスタム定義された文字列のキーと値のペアを送信できます。API トリガーキャンペーンおよびスケジュールされた API トリガーキャンペーンで extras にアクセスするには、ダッシュボードでキーを “example_key”、値を "$json:{"foo": 1, "bar": 1}" に設定します。これにより、開発者コンソールに "extras": { "test": { "foo": 1, "bar": 1 } が出力されます。
Android
Braze では、キーと値のペアを使用して、プッシュ通知で追加のデータペイロードを送信できます。
データペイロード
iOS プッシュと同様に、カスタムのキーと値のペアをユーザーのデバイスに送信できます。
カスタムのキーと値のペアのユースケースには、内部メトリクスの記録やユーザーインターフェイスのコンテキスト設定などがありますが、任意の目的に使用できます。

データペイロードが正しく機能するには、アプリのバックエンドでカスタムのキーと値のペアを処理できる必要があります。
API トリガーキャンペーン
Braze では、extras と呼ばれる、カスタム定義された文字列のキーと値のペアを送信できます。API トリガーキャンペーンおよびスケジュールされた API トリガーキャンペーンで extras にアクセスするには、ダッシュボードでキーを “example_key”、値を "$json:{"foo": 1, "bar": 1}" に設定します。これにより、開発者コンソールに "extras": { "test": { "foo": 1, "bar": 1 } が出力されます。
FCM メッセージングオプション
Android のプッシュ通知は、FCM メッセージオプションを使用してさらにカスタマイズできます。これには、通知の優先度、サウンド、遅延、有効期間、折りたたみ可能性が含まれます。これらの値は、プッシュメッセージを作成する際に設定タブで指定できます。Braze のメッセージ作成画面でこれらのオプションを設定する方法の詳細については、プッシュ通知の詳細設定を参照してください。

サイレントプッシュ通知
サイレントプッシュ通知とは、アラートメッセージやサウンドを含まないプッシュ通知で、バックグラウンドでアプリのインターフェイスやコンテンツを更新するために使用されます。これらの通知は、キーと値のペアを使用してバックグラウンドでのアプリのアクションをトリガーします。サイレントプッシュ通知は、アンインストール追跡にも使用されています。
マーケターは、アプリのユーザーにサイレントプッシュ通知を送信する前に、想定どおりの動作がトリガーされるかテストする必要があります。iOS または Android のサイレントプッシュ通知を作成したら、外部ユーザー ID またはメールアドレスでフィルタリングして、テストユーザーのみをターゲットにしていることを確認してください。
キャンペーンの開始時に、テストデバイスで表示されるプッシュ通知を受信していないことを確認してください。

iOS のサイレント通知の制限により、次のような症状が発生する場合があります。
- iOS ユーザーのアンインストール追跡メトリクスが想定より低い
- サイレントプッシュ通知の配信が不安定、または遅延する
- Push Storiesが表示されない
- Push Stories が、想定される画像、動画、ページなしで届く
これは Braze の問題ではなく、Apple のプラットフォームの制限です。iOS では、アンインストール追跡や Push Stories など、一部の Braze 機能のバックグラウンド通知が遅延または破棄される場合があります。iOS が何をいつ制限するかの詳細については、iOS の制限事項を参照してください。
アプリ内メッセージ
Brazeで作成するすべてのアプリ内メッセージにキーと値のペアを追加できます。
- キャンペーンまたはキャンバスで、アプリ内メッセージを作成または編集します。
- メッセージ作成画面で、設定タブを選択します。
- 新しいペアを追加を選択します。
- 従来のエディター:キーと値のペアで、新しいペアを追加を選択します。
- ドラッグ&ドロップエディター:キーと値のペアタブを選択し、新しいペアを追加を選択します。
- 各ペアのキーと値を入力します。さらにペアを追加するには、もう一度新しいペアを追加を選択します。
API トリガーキャンペーン
Brazeでは、extras と呼ばれるカスタム定義の文字列のキーと値のペアを送信できます。API トリガーキャンペーンおよびスケジュールされた API トリガーキャンペーンで extras にアクセスするには、ダッシュボードでキーを “example_key” に、値を "$json:{"foo": 1, "bar": 1}" に設定します。これにより、開発者コンソールに "extras": { "test": { "foo": 1, "bar": 1 } が出力されます。
メール
SparkPost と SendGrid は、いずれもメールのキーと値のペアをサポートしています。SendGrid を使用している場合、キーと値のペアは一意の引数として送信されます。SendGrid では、最大 10,000 バイトのデータまで、キーと値のペアを無制限に添付できます。これらのキーと値のペアは、SendGrid の Event Webhook からのポストで確認できます。

バウンスしたメールでは、キーと値のペアは SparkPost または SendGrid に配信されません。
![Braze のメールメッセージ作成画面の [送信情報] タブ。](/docs/ja/assets/img_archive/keyvalue_email.png?af271ea39c591baa641a4d28096aa956)
Content Cards
Content Cardsにキーと値のペアを追加するには、Brazeのメッセージ作成画面のSettingsタブに移動し、Add New Pairを選択します。


コントロールバリアントはキーと値のペアをサポートしていません。A/Bテストでコントロールグループの分析をキャプチャする必要がある場合は、control=trueなどのキーと値のペアを持つメッセージバリアントを作成し、インプレッションをログに記録しながらアプリコード内で非表示にしてください。