このページはAIにより自動翻訳されており、不正確な内容が含まれている可能性があります。翻訳の誤りを報告するには、ページ右側の目次の下にあるフィードバックをご利用ください。

API トリガーのキャンバスリクエストを Currentsのメッセージングイベントにリンクする

相関 IDをキャンバスエントリプロパティとして渡し、message_extras で送信イベントに付与して、dispatch_id と user_id でエンゲージメントイベントを結合することで、API トリガーのキャンバスリクエストからメッセージングの結果までを追跡します。

この例について

架空の金融サービスブランドである Pyrite Financialは、消費者の取引でアラートが必要になるたびに、自社システムからキャンバスをトリガーしています。イベントごとに /canvas/trigger/send を呼び出します。同社の分析チームは、Currents または Snowflake Data Sharing で、どのトリガーリクエストがどの送信、配信、クリックにつながったかを把握したいと考えています。どちらにも同じメッセージングイベントデータが含まれています。

Currentsと Snowflake Data Sharingのメッセージングイベントには、トリガーリクエストの識別子がそのままでは含まれません。この例では、次の方法を示します。

送信システムで相関 IDを生成し、トリガーリクエストでキャンバスエントリプロパティとして渡します。
メッセージ本文でそのプロパティを message_extras Liquidタグで参照し、送信イベントの message_extras フィールドに書き込みます。
dispatch_id と user_id で送信イベントを配信イベントおよびクリックイベントと結合します。

外部システムがトリガーを管理しており、リクエストごとに下流のエンゲージメントをレポートする必要がある場合に使用します。ユースケースにキャンバスではなくキャンペーンが適している場合は、代わりに送信識別子を使用してください。send_id フィールドはキャンペーンのメッセージングエンドポイントでサポートされており、/canvas/trigger/send ではサポートされていません。

考慮事項

キャンバスでは、dispatch_id だけでは一意のキーになりません。Brazeはキャンバスのステップをトリガーイベントとして扱うため、ステップによっては送信ごと・ユーザーごとに一意の dispatch_id が生成される場合と、同じ送信内のユーザー間で共有の dispatch_id が生成される場合があります。必ず user_id と組み合わせて使用してください。詳細については、ディスパッチ IDの動作を参照してください。
message_extras フィールドは送信イベントにのみ表示されます。配信、開封、クリックイベントには含まれないため、相関 IDは送信イベントを経由してから外側へ結合します。
メッセージエクストラは送信時にメッセージごとに付与されるため、複数のメッセージステップを持つキャンバスでは、レポート対象とする各ステップにタグが必要です。
すべての message_extras のキーと値の合計は 1,000 バイト (1 KB) 未満にする必要があり、それより長い値は Brazeによって切り捨てられます。空白も上限にカウントされます。
生成される JSONには文字列値のみが含まれます。キーまたは値には Liquid 変数を使用してください。message_extras の中に他の Liquidタグをネストしないでください。
Currentsのイベントでは、Braze ユーザー IDが user_id に、独自の識別子が external_user_id に保存されます。user_id で結合し、行を自社システムと照合する必要がある場合は external_user_id を選択してください。
このパターンには Currents または Snowflake Data Sharing を使用してください。どちらも、送信イベントの message_extras を含む同じメッセージングイベントフィールドを公開しています。
Currentsと Snowflakeのスキーマでは、message_extras は PIIとしてフラグが付けられています。消費者データではなく、不透明なリクエスト IDを使用してください。
キャンバスのトリガーリクエストの context オブジェクトは最大 50 KBで、渡すすべてのプロパティで共有されます。

設定

ステップ 1:リクエストごとに相関 IDを生成する

送信システムで、トリガーリクエストごとに識別子 (UUID など) を作成し、自社のリクエストログと一緒に保存します。不透明な値にし、message_extras のサイズ上限に収まる程度の短さに保ってください。

ステップ 2:IDをキャンバスエントリプロパティとして渡す

/canvas/trigger/send リクエストの context オブジェクトに IDを含めます。ユーザーごとに異なる IDがある場合は受信者ごとに設定し、1 つの IDでリクエスト内のすべての受信者をカバーする場合はトップレベルで設定します。

{
  "canvas_id": "canvas_identifier",
  "recipients": [
    {
      "external_user_id": "user_identifier",
      "context": {
        "request_id": "8f14e45f-ceea-467a-9e30-6b1b1c4a7d20"
      }
    }
  ]
}

キャンバスエントリプロパティは、キャンバス全体でコンテキスト変数として使用できます。

ステップ 3:IDを送信イベントに付与する

レポート対象とする各メッセージステップで、コンテキスト変数を割り当てて message_extras に渡します。

{% assign request_id = context.${request_id} %}
{% message_extras :key request_id :value {{request_id}} %}

Brazeは送信時に、このキーと値のペアを送信イベントの message_extras フィールドに付与します。

ステップ 4:テスト送信で確認する

キャンバスでテストエントリを送信し、Currentsまたは Snowflake Data Sharingの送信イベントに、request_id キーを含む message_extras があることを確認します。フィールドが空の場合は、タグの構文を確認してください。区切り文字の入力ミスや、キーと値の順序の誤りがよくある原因です。

ステップ 5:送信を配信イベントおよびクリックイベントと結合する

送信イベントに IDが付与されたら、dispatch_id と user_id で外側へ結合します。次のクエリビルダーの例では、メールのリクエストごとの配信およびクリックの結果をレポートします。

WITH sends AS (
  SELECT
    USER_ID,
    EXTERNAL_USER_ID,
    DISPATCH_ID,
    PARSE_JSON(MESSAGE_EXTRAS):request_id::STRING AS request_id,
    TIME AS send_time
  FROM USERS_MESSAGES_EMAIL_SEND_SHARED
  WHERE MESSAGE_EXTRAS IS NOT NULL
    AND PARSE_JSON(MESSAGE_EXTRAS):request_id IS NOT NULL
)
SELECT
  s.request_id AS "Request ID",
  s.EXTERNAL_USER_ID AS "External User ID",
  MIN(s.send_time) AS "Sent",
  MIN(d.TIME) AS "Delivered",
  MIN(c.TIME) AS "First Click"
FROM sends AS s
LEFT JOIN USERS_MESSAGES_EMAIL_DELIVERY_SHARED AS d
  ON d.USER_ID = s.USER_ID
  AND d.DISPATCH_ID = s.DISPATCH_ID
LEFT JOIN USERS_MESSAGES_EMAIL_CLICK_SHARED AS c
  ON c.USER_ID = s.USER_ID
  AND c.DISPATCH_ID = s.DISPATCH_ID
GROUP BY 1, 2
ORDER BY 3 DESC;

送信に使用するチャネルのテーブルに置き換えてください。たとえば、プッシュの場合は USERS_MESSAGES_PUSHNOTIFICATION_SEND_SHARED と USERS_MESSAGES_PUSHNOTIFICATION_OPEN_SHARED を使用します。テーブルごとの列の一覧については、SQL テーブルリファレンスを参照してください。

クエリビルダーの例は方法の 1 つです。Snowflake Data Sharing や、自社のウェアハウスへの Currents エクスポートでも同じ結合を適用できます。送信イベントの message_extras を解析し、dispatch_id と user_id でエンゲージメントイベントを結合してください。

New Stuff!