Skip to content

キーと値のペア

このページでは、キーと値のペアを使用してユーザーデバイスに追加のデータペイロードを送信する方法について説明します。この機能は、プッシュ通知、アプリ内メッセージ、メール、Content カードのメッセージングチャネルで利用できます。

キーと値のペアを使用して、メッセージに構造化されたメタデータを追加します。これらの追加データペイロードにより、メッセージのレンダリングや処理方法に影響を与える文脈に応じた情報でメッセージを充実させることができます。

キーと値のペアはメタデータであるため、このデータは必ずしも受信者に表示されるわけではありませんが、接続されたシステムやプロセスがメッセージ処理をカスタマイズするために使用できます。

各ペアは以下で構成されます:

  • キー: 識別子（例: utm_source）
  • 値: 関連データ（例: newsletter）

ユースケース

キーと値のペアでメタデータを追加するユースケースの例を以下に示します。

  1. トラッキングパラメーター:分析目的で UTM パラメーターを付与します
    • キー: utm_campaign
    • 値: spring_sale
  2. カスタムタグ:内部ルーティングやカテゴリ分けのためにタグを追加します
    • キー: priority
    • 値: high
  3. 動作トリガー:アプリ内の動作をトリガーまたはカスタマイズするために使用するメタデータです
    • キー: 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 としてフォーマットされます。

シンプルなペイロード

1
2
3

{
    "aps" : { "alert" : "Message received from Spencer" },
}

複雑なペイロード

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

{
    "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 キーを通じて使用するための追加キーと値のペアをプッシュ通知と一緒に送信できます。別のキーを使用する場合は、アプリがそのカスタムキーを処理できることを確認してください。

Apple は、カスタムペイロードデータとして顧客情報や機密データを含めないようクライアントに推奨しています。さらに、Apple はアラートメッセージに関連するアクションがデバイス上のデータを削除しないよう推奨しています。

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 のメッセージ作成画面でこれらのオプションを設定する方法の詳細については、プッシュ通知の詳細設定を参照してください。

FCM メッセージングオプションに関連するスクリーンショット。

サイレントプッシュ通知

サイレントプッシュ通知は、アラートメッセージやサウンドを含まないプッシュ通知で、バックグラウンドでアプリのインターフェイスやコンテンツを更新するために使用されます。これらの通知はキーと値のペアを利用して、バックグラウンドのアプリアクションをトリガーします。サイレントプッシュ通知はアンインストール追跡にも使用されています。

マーケターは、アプリのユーザーにサイレントプッシュ通知を送信する前に、期待される動作がトリガーされることをテストする必要があります。iOS または Android のサイレントプッシュ通知を作成した後、外部ユーザー ID またはメールアドレスでフィルターして、テストユーザーのみをターゲットにしてください。

キャンペーンの開始後、テストデバイスに表示されるプッシュ通知を受信していないことを確認してください。

アプリ内メッセージ

従来のエディターで作成するアプリ内メッセージにキーと値のペアを追加します。

  1. キャンペーンまたはキャンバスで、アプリ内メッセージを作成または編集し、従来のエディター（ドラッグ＆ドロップではない）を選択します。
  2. メッセージ作成画面で、Settings タブを選択します。
  3. Key value pairs で、Add new pair を選択します。
  4. 各ペアのキーと値を入力します。別のペアを追加するには、Add new pair をもう一度選択します。

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 からの投稿で確認できます。

Braze のメールメッセージ作成画面の「送信情報」タブ。

Content Cards

Content Cardsにキーと値のペアを追加するには、Brazeのメッセージ作成画面のSettingsタブに移動し、Add New Pairを選択します。

Content Cardsにキーと値のペアを追加
New Stuff!