コンテンツにスキップ

キーと値のペア

このページでは、キーと値のペアを使用してユーザーデバイスに追加のデータペイロードを送信する方法について説明します。この機能は、プッシュ、アプリ内メッセージ、メール、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 またはメールアドレスでフィルタリングして、テストユーザーのみをターゲットにしてください。

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

アプリ内メッセージ

作成画面で作成する任意のアプリ内メッセージに、キーと値のペアを追加できます。

  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 のイベント Webhook からの POST で確認できます。

Braze のメッセージ作成画面の [送信情報] タブ。

Content Cards

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

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

Brazeカスタマーエンゲージメントプラットフォームのドキュメント。

リソース
法的情報
会社情報
© 2026 Braze, Inc. All rights reserved.
Braze ステータスの確認
New Stuff!