Skip to content

おすすめイベント

おすすめイベントは、定義済みのJSONスキーマを持つ標準化されたカスタムイベントを送信するフレームワーク上に構築されています。おすすめイベントを送信すると、Brazeは取り込み時にスキーマに対してバリデーションを行い、自動フィールド計算やカート管理など、汎用カスタムイベントでは適用されない特別な後処理を実行します。特定の業界向けイベントセットについては、CampaignsやCanvasesの専用アクションベーストリガーなど、Brazeが特別な処理をサポートする場合があります。

eコマース推奨イベントは、購入ジャーニーの6つのステップをカバーします: product_viewed、cart_updated、checkout_started、order_placed、order_cancelled、order_refunded。これらのイベントを正常に送信すると、Brazeはデータをバリデーションし、拡大し続けるプラットフォーム機能で利用可能にします。

これらの機能には、閲覧放棄、カート放棄、チェックアウト放棄、注文確認フロー向けのCanvasテンプレート、eコマースレポート、合計収益、合計注文数、_合計返金額_の計算済みユーザープロファイルフィールドが含まれます。また、セグメントエクステンションを使用したネストされた製品プロパティフィルタリングによるSegmentの構築、{% shopping_cart %} Liquidタグを使用したカート放棄メッセージのパーソナライゼーション、Predictive Events、Predictive Churn、アイテムのおすすめなどのBrazeAITM機能への活用、およびその他の機能も利用可能です。

これらのイベントは定義済みスキーマに従うため、サポートされる各機能は、カスタムプロパティマッピングや機能ごとの設定なしに構造化データを読み取ることができます。

eコマースイベントの仕組み

eコマースイベントは、事前定義された名前とプロパティスキーマを持つカスタムイベントです。Braze SDKまたは/users/track REST APIエンドポイントを使用して送信し、Brazeは取り込み時に各イベントをスキーマに対してバリデーションします。バリデーションに合格すると、Brazeは収益フィールドの計算やユーザープロファイルのカート状態管理など、そのイベントタイプに固有の後処理を自動的に適用します。

eコマースイベントは、他のカスタムイベントが機能するすべての場所で機能します: 実行済みカスタムイベントのトリガーとフィルター、カスタムイベントレポートなど。ただし、スキーマバリデーションにより、以下の追加機能が利用可能になります:

  • Campaigns、Canvases、アクションパス、アプリ内メッセージトリガー、コンテンツカードの削除における「注文する」トリガーアクション
  • 計算済みeコマースユーザープロファイルフィールド (合計収益、合計注文数、合計返金額)
  • カート放棄フロー向けのカート状態管理
  • Predictive Events、Predictive Churn、アイテムのおすすめなどのBrazeAITM機能向けのリッチデータ

また、プラットフォームがカスタムイベントをサポートする場所であれば、eコマースイベントを名前で参照することもできます。例えば、ecommerce.product_viewedイベントでアクションベースのCampaignをトリガーしたり、ecommerce.checkout_startedイベントでフィルタリングするSegmentを構築したり、Currentsを通じてecommerce.order_placedイベントをエクスポートしたりできます。

イベント命名

イベント名は正確で、大文字と小文字が区別され、ドット区切りです。常に正規フォーマットを使用してください。イベント名が6つの正規名のいずれかと正確に一致しない場合、Brazeはそれを標準カスタムイベントとして扱い、eコマースの後処理は行われません。

イベントのカスタマイズや名前変更はできません。

  • 正しい例: ecommerce.order_placed
  • 誤った例: order.placed、eCommerce_order_placed、Order_Placed

イベントスキーマ

6つのeコマース推奨イベントは、購入ジャーニーのステージに対応しています。ユーザーが対応するアクションを完了した時点で各イベントを発火させてください。

6つのeコマース推奨イベント (product_viewed、cart_updated、checkout_started、order_placed、order_cancelled、order_refunded) を通じたユーザージャーニーの図

ユーザーが商品詳細ページを閲覧した時点でトリガーします。このイベントは、Brazeカタログの在庫復活通知および値下げ通知と互換性があります。

イベントプロパティ

REST APIの例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.product_viewed",
      "time": "2026-04-28T14:22:11Z",
      "properties": {
        "product_id": "SKU-RUN-4821",
        "product_name": "Ultraboost Running Shoe",
        "variant_id": "UB-BLK-11",
        "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
        "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
        "price": 189.99,
        "currency": "USD",
        "source": "web",
        "type": ["price_drop", "back_in_stock"],
        "metadata": {
          "sku": "UB-BLK-11-SKU",
          "category": "Running Shoes",
          "brand": "Shoe Brand"
        }
      }
    }
  ]
}

ユーザーのカートの内容が変更されるたびにトリガーします。

このイベントは置換モデルを使用しており、各呼び出しには変更されたアイテムだけでなく、完全な現在のカート配列を含める必要があります。Brazeは送信された配列で以前のカート状態を上書きします。

このイベントからメッセージングをトリガーするには、CanvasおよびCampaignsのカート更新イベントの実行トリガーを使用します。このトリガーには、カートがショッピングファネルを進行するのを停止する特別な処理が含まれています。

イベントプロパティ

製品プロパティ (products[])

REST APIの例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.cart_updated",
      "time": "2026-04-28T14:25:33Z",
      "properties": {
        "cart_id": "cart_abc123",
        "total_value": 234.96,
        "subtotal_value": 219.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
            "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "cart_source": "product_page_atc_button"
        }
      }
    }
  ]
}

ユーザーがチェックアウトフローを開始した時点 (例: 「チェックアウト」を選択した場合やチェックアウトページに到達した場合) でトリガーします。

イベントプロパティ

製品プロパティ (products[])

REST APIの例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.checkout_started",
      "time": "2026-04-28T14:30:05Z",
      "properties": {
        "checkout_id": "chk_88291",
        "cart_id": "cart_abc123",
        "total_value": 234.96,
        "subtotal_value": 219.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
            "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "checkout_url": "https://www.example.com/checkout/chk_88291",
          "checkout_type": "express"
        }
      }
    }
  ]
}

注文が正常に完了した場合、または支払いが確認された時点でトリガーします。

イベントプロパティ

製品プロパティ (products[])

REST APIの例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_placed",
      "time": "2026-04-28T14:35:42Z",
      "properties": {
        "order_id": "ord_77821",
        "cart_id": "cart_abc123",
        "total_value": 224.96,
        "subtotal_value": 209.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "total_discounts": 10.0,
        "discounts": [
          {
            "code": "SPRING10",
            "amount": 10.0,
            "type": "percentage"
          }
        ],
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
            "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}

注文がキャンセルされた時点でトリガーします。

イベントプロパティ

製品プロパティ (products[])

REST APIの例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_cancelled",
      "time": "2026-04-28T16:10:00Z",
      "properties": {
        "order_id": "ord_77821",
        "total_value": 224.96,
        "subtotal_value": 209.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "total_discounts": 10.0,
        "cancel_reason": "customer_request",
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}

全額または一部の返金が発行された時点でトリガーします。

イベントプロパティ

製品プロパティ (products[])

REST APIの例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_refunded",
      "time": "2026-04-29T10:05:00Z",
      "properties": {
        "order_id": "ord_77821",
        "total_value": 189.99,
        "currency": "USD",
        "total_discounts": 0,
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11",
              "refund_reason": "size_mismatch"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_refunded",
      "time": "2026-05-02T11:08:30Z",
      "properties": {
        "order_id": "ORD-20260428-7891",
        "total_value": 29.98,
        "currency": "USD",
        "products": [
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "refund_method": "store_credit",
          "initiated_by": "customer"
        }
      }
    }
  ]
}

eコマースイベントの後処理

eコマースイベントを送信すると、Brazeはそのイベント名に対して期待されるスキーマに対してバリデーションを行います。

以下の表は、バリデーションに合格した場合にBrazeが各イベントに対して自動的に行う処理をまとめたものです。バリデーションに失敗した場合の動作については、イベントバリデーションとトラブルシューティングを参照してください。

eコマースイベントの実装

eコマースイベントは、/users/trackエンドポイント (サーバーサイド) またはクライアントSDKメソッド logCustomEvent を通じて送信できます。

サーバーサイドでイベントを送信する

/users/trackエンドポイントを使用して、バックエンドからeコマースイベントを送信します。各イベントには、正確なイベント名、ユーザーの external_id、およびイベントスキーマに一致するプロパティオブジェクトが必要です。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

POST /users/track

{
  "events": [
    {
      "external_id": "user_abc123",
      "name": "ecommerce.order_placed",
      "time": "2026-04-26T14:32:00Z",
      "properties": {
        "order_id": "order_7891011",
        "total_value": 84.99,
        "currency": "USD",
        "source": "custom_api",
        "total_discounts": 10.00,
        "products": [
          {
            "product_id": "sku_2001",
            "product_name": "Trail Runner Pro",
            "variant_id": "var_2001_black_10",
            "quantity": 1,
            "price": 94.99,
            "metadata": {
              "color": "black",
              "size": "10"
            }
          }
        ],
        "metadata": {
          "gift_wrapped": true,
          "loyalty_points_earned": 170
        }
      }
    }
  ]
}

データポイントと課金

eコマースイベントはデータポイントを消費しません。データポイント使用量に影響を与えることなく記録できます。

イベントサイズの制限

/users/trackに送信されるイベントプロパティは、イベントあたり102,400バイト (100 KB) が上限です。トリガーされたCampaignおよびCanvasメッセージの場合、/campaigns/trigger/send および /canvas/trigger/send に送信される trigger_properties のデフォルト上限は51,200バイト (50 KB) とより厳しくなっています。

ベストプラクティスとして、トリガー、パーソナライゼーション、またはイベントのアトリビューションに必要な製品情報のみを送信してください。説明、完全なバリアントリスト、在庫、代替画像などのリッチな製品詳細はBrazeカタログに保存してください。メッセージ送信時に product_id または variant_id でこれらの詳細を参照します。metadata オブジェクトは、メッセージングで使用する注文または製品固有のコンテキストに対して選択的に使用してください。

通貨の処理

Brazeは米ドル以外の通貨値を、イベントが報告された日の為替レートを使用して自動的に米ドルに変換します。この変換された値が収益指標に表示されます。

ソースフィールド

ソースプロパティは、イベントの発生元を識別する必須の文字列です。例えば、shopify、in-store POS、custom_api などです。これにより、Currentsエクスポートでデータを分析する際やバリデーションの問題をデバッグする際に、インテグレーションソースを区別できます。

メタデータの柔軟性

イベントレベルおよび製品レベルのmetadataオブジェクトは任意のキーと値のペアを受け入れるため、コアスキーマを変更せずにカスタムディメンションを付加できます。一般的な例としては、order_status_url、gift_wrapped、loyalty_points_earned、warehouse_id などがあります。これらのプロパティは、Liquidパーソナライゼーション、Currentsエクスポート、およびセグメントエクステンションを通じたセグメンテーションで利用可能です。

イベントバリデーションとトラブルシューティング

おすすめeコマースイベントを /users/track または任意のBraze SDKを通じて送信すると、Brazeはおすすめイベントの処理中にペイロードをイベントのJSONスキーマに対してバリデーションします。バリデーションは、名前がおすすめイベントと正確に一致するすべてのイベント (例: ecommerce.order_placed や ecommerce.cart_updated) に対して自動的に実行されます。

バリデーション内容

名前がeコマース推奨イベントと一致する各イベントについて、Brazeは以下をチェックします:

バリデーションを行う理由

eコマースイベントは、収益トラッキング、{% shopping_cart %} Liquidタグ、カート放棄トリガー、レポートなど、一貫性のある予測可能なデータに依存する機能を動作させます。ペイロードがスキーマから逸脱すると、これらの機能はサイレントな不正確さ (誤った収益合計、欠落したカート、壊れたトリガー) を生み出します。バリデーションは、下流の機能が予測どおりに動作するようにコントラクトを事前に強制します。

バリデーションに合格した場合

イベントは、関連するすべての後処理を伴うeコマース推奨イベントとして処理されます。各イベントタイプによってトリガーされる動作の完全なリストについては、イベントスキーマを参照してください。

成功したイベントの確認

イベントを送信した後、以下のいずれかを使用して、イベントが受け入れられ正しく処理されたことを確認できます:

  • イベントユーザーログ: ダッシュボードでユーザーのプロファイルを開き、アクティビティを確認します。おすすめイベントは完全なプロパティペイロードとともに表示されるため、イベントが到達し、送信した値と一致していることを確認できます。
  • カスタムイベントレポート: Analytics > Custom Events に移動して、各おすすめイベントの経時的な集計カウントを確認します。これは、インテグレーションが本番稼働している際に、本番トラフィックが期待どおりに流れていることを確認するのに役立ちます。
  • テストユーザー: 開発ワークスペースでユーザーをテストユーザーとしてマークし、そのユーザーに対してインテグレーションからイベントをトリガーします。テストユーザーはダッシュボードでフラグが付けられるため、エンドツーエンドの動作を簡単に分離して検査できます。

バリデーションに失敗した場合

イベントはおすすめイベントとして処理されません。具体的には:

  • イベントは完全にドロップされます。 無効なおすすめeコマースイベントはユーザープロファイルに記録されず、Currentsに表示されず、セグメンテーションでも利用できません。
  • 以下を含む下流のおすすめイベント機能は実行されません:
    • 収益トラッキング (収益レポート、total_revenue などのユーザー計算フィールド)
    • ユーザープロファイル上のカートオブジェクトの更新
    • CanvasおよびCampaignsの「カート更新イベントの実行」または「注文する」トリガー

エラーの報告方法は取り込みパスによって異なります:

  • REST API (/users/track): 各無効なイベントはレスポンスのerrors配列で報告されます。各エントリには、どのイベントが失敗したか (インデックス) と理由 (タイプ) が記載されます。トップレベルのmessageフィールドは引き続き「success」と表示されますが、これはリクエストがBrazeに到達したことを意味するだけで、すべてのイベントが有効であったことを意味するものではありません。レスポンスのerrors配列を常に確認してください。
  • Braze SDK: SDK呼び出しは即座に返され、バリデーションはバックグラウンドで実行されるため、エラーはアプリに返されません。eコマースイベントのバリデーション失敗を確認するには、失敗サマリーメール (失敗の確認を参照) を監視してください。

APIエラーレスポンスの例

/users/trackエンドポイントは、どのプロパティが失敗したか、およびその理由を示すフィールドレベルのエラーを返します。トップレベルの message はイベントがパイプラインに受け入れられたため "success" を返す場合があることに注意してください。errors 配列がスキーマバリデーションに失敗したフィールドを示します。以下のエラーレスポンスの例を参照してください。

1
2
3
4

{
 "message": "success",
 "errors": [{ "index": 0, "input_array": "purchases", "type": "'currency' must be an ISO 4217 currency" }]
}

失敗は内部的にも分類され、失敗サマリーメール用に集計されます:

失敗の確認

Brazeはワークスペース管理者に、おすすめイベントのバリデーション失敗のサマリーをメールで送信するため、すべてのイベントを手動で監視することなくインテグレーションの問題を特定して修正できます。

サマリーメールには以下が含まれます:

  • 合計エラー数: レポート期間のエラー数。
  • イベント別エラー: 各おすすめイベントタイプ (例: ecommerce.cart_updated や ecommerce.order_placed) で失敗したイベント数の内訳。これを使用して、インテグレーションのどのイベントに最初に対応すべきかを特定します。
  • ソース別エラー: APIとSDKの分割。これにより、どのインテグレーションが失敗を生成しているかを特定できます。

これらのメールを受信していない場合や受信者リストを確認したい場合は、Brazeアカウントチームにお問い合わせください。

失敗の診断と修正

失敗サマリーメールを受信した場合:

  1. 失敗しているイベントとソースを特定します。 メールはイベント名とインテグレーションソース (sdk 対 rest_api) ごとに失敗を分離するため、どのインテグレーションに修正が必要かを特定できます。同じイベントを送信する複数のソースがある場合 (例: ストアフロントSDKとバックエンドWebhookの両方が cart_updated を送信している場合)、それぞれ独立して対処してください。
  2. ペイロードをイベントスキーマのスキーマと比較します。 ほとんどの失敗は以下の3つのパターンのいずれかに該当します:
    • missing_property: 必須フィールドが欠落しています。解決するには、必須フィールドを追加してください。
    • extra_property: カスタムフィールドが properties のトップレベルにあります。解決するには、カスタムフィールドを metadata (イベントレベル) または products[].metadata (製品ごと) 内に移動してください。
    • unexpected_data_type: 値のタイプが間違っています (例: total_value が文字列として送信された場合)。解決するには、送信前に値を変換してください。
  3. 修正したペイロードを本番環境にロールアウトする前に開発ワークスペースでテストします。 テストユーザーに対して既知のテストイベントを送信し、そのユーザーのプロファイルで期待されるおすすめイベントの動作 (例: カートオブジェクトの更新、収益の増加、カート放棄トリガーの発火) を確認してください。
  4. 次の失敗メールを監視して、そのイベント、ソース、タイプの失敗数がゼロに減少したことを確認します。

イベントごとの完全なプロパティ要件については、イベントスキーマを参照してください。
New Stuff!