キーと値のペア

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

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

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

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

• キー: 識別子（例: 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) は、キーと値のペアを使用したアラート設定やカスタムデータの送信をサポートしています。APNs は、アラートプロパティを制御する事前定義されたキーと値を含む、Apple 予約済みの aps ライブラリーを使用します。

APS ライブラリー

アラートプロパティライブラリー

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

サイレントプッシュ通知

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

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

キャンペーンの起動時に、テストデバイスで目に見えるプッシュ通知を受信していないことを確認してください。

アプリ内メッセージ

従来のエディターで、設定タブを選択し、新しいペアを追加を選択してから、キーと値のペアを指定することで、アプリ内メッセージにキーと値のペアを追加できます。

API トリガーキャンペーン

Braze では、extras と呼ばれるカスタム定義の文字列キーと値のペアを送信できます。API トリガーおよびスケジュールされた API トリガーキャンペーンで extras にアクセスするには、ダッシュボードでキーを「example_key」、値を "$json:{"foo": 1, "bar": 1}" と設定します。これにより、開発者コンソールの出力は "extras": { "test": { "foo": 1, "bar": 1 } となります。

メール

SparkPost と SendGrid の両方がメールでのキーと値のペアをサポートしています。SendGrid を使用している場合、キーと値のペアは unique arguments として送信されます。SendGrid では、最大 10,000 バイトのデータまで無制限の数のキーと値のペアを添付できます。これらのキーと値のペアは、SendGrid の Event Webhook からの投稿で確認できます。

コンテンツカード

コンテンツカードにキーと値のペアを追加するには、Braze のメッセージ作成画面の設定タブに移動し、新しいペアを追加を選択します。