コンテンツにスキップ

キーと値のペア

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

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

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

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

  • キー: 識別子(例: 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 形式でフォーマットされます。

シンプルなペイロード

{
    "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 キー内でアプリケーション全体で使用できます。別のキーを使用する場合は、アプリがそのカスタムキーを処理できることを確認してください。

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 またはメールアドレスでフィルタリングして、テストユーザーのみをターゲットにしていることを確認してください。

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

アプリ内メッセージ

Brazeで作成するすべてのアプリ内メッセージにキーと値のペアを追加できます。

  1. キャンペーンまたはキャンバスで、アプリ内メッセージを作成または編集します。
  2. メッセージ作成画面で、設定タブを選択します。
  3. 新しいペアを追加を選択します。
    • 従来のエディター:キーと値のペアで、新しいペアを追加を選択します。
    • ドラッグ&ドロップエディター:キーと値のペアタブを選択し、新しいペアを追加を選択します。
  4. 各ペアのキーと値を入力します。さらにペアを追加するには、もう一度新しいペアを追加を選択します。

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!