Skip to content

推奨イベント

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

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

これらの機能には、閲覧離脱、カート放棄、チェックアウト離脱、注文確認フローのキャンバステンプレート、eコマースレポート、合計収益、合計注文数、合計返金額の計算済みユーザープロファイルフィールドが含まれます。また、セグメントエクステンションを通じたネストされた製品プロパティフィルタリングによるセグメント構築、{% shopping_cart %} Liquidタグを使用した放棄カートメッセージのパーソナライゼーション、予測イベント、解約予測、アイテムレコメンデーションなどのBrazeAITM機能の活用も可能です。

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

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

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

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

  • キャンペーン、キャンバス、アクションパス、アプリ内メッセージトリガー、Content Cardの削除における「注文完了」トリガーアクション
  • eコマースのユーザープロファイル計算フィールド（合計収益、合計注文数、合計返金額）
  • 放棄カートフローのカート状態管理
  • 予測イベント、解約予測、アイテムレコメンデーションなどのBrazeAITM機能向けのリッチデータ

また、プラットフォームがカスタムイベントをサポートしている場所であれば、eコマースイベントを名前で参照することもできます。たとえば、ecommerce.product_viewedイベントでアクションベースのキャンペーンをトリガーしたり、ecommerce.checkout_startedイベントでフィルタリングしてセグメントを構築したり、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カタログの在庫復帰通知および値下げ通知と互換性があります。

クライアント側の実装

利用可能な場合はSDKのeコマースイベントAPIを使用してください。プラットフォーム固有の実装例については、Braze SDKを通じたeコマースイベントの記録を参照してください。

イベントプロパティ

プロパティ名 データ型 必須 説明
product_id String はい 一意の製品識別子（例：SKUまたはアイテムID）。
product_name String はい 製品の表示名。
variant_id String はい 製品バリアント識別子（例：shirt_medium_blue）。
image_url String いいえ 製品画像のURL。
product_url String いいえ 製品詳細ページへのURL。
price Float はい 閲覧時点でのバリアント単価。
currency String はい 3文字のISO 4217コード（例：USDまたはEUR）。
source String はい イベントの発生元（例：web、ios、android）。
type Array of strings いいえ Brazeのカタログトリガー機能（在庫復帰および値下げアラート）を使用するために必要です。許容値："price_drop"、"back_in_stock"
metadata Object いいえ 柔軟なキーと値のペア（例：categoryやbrand）。

REST APIの例




{
  "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": {
          "category": "Running Shoes",
          "brand": "Shoe Brand"
        }
      }
    }
  ]
}

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

クライアント側の実装

利用可能な場合はSDKのeコマースイベントAPIを使用してください。プラットフォーム固有の実装例については、Braze SDKを通じたeコマースイベントの記録を参照してください。

このイベントは次の2つの方法のいずれかで送信できます。

  • カート全体の置換: actionを省略するか、actionをreplaceに設定します。productsにカート内の絶対数量（バリアントごとのカート内合計ユニット数）を含むラインアイテムの完全なセットを含めます。total_valueを含める必要があります。
  • 増分カート更新: actionをaddまたはremoveに設定します。変更されたラインアイテムのみを含めます。各quantityは、カート内の合計数量ではなく、追加または削除するユニット数です。addの場合、Brazeはライン数量を増やすか、新しいラインを追加します。removeの場合、Brazeはライン数量を減らし、数量が0に達するとラインを削除します。total_valueはaddとremoveではオプションです。

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

イベントプロパティ

プロパティ データ型 必須 説明
cart_id String はい カートの一意の識別子。ユーザーのカートマッピング用にカート、チェックアウト、注文イベント間で共有されます。
action String いいえ add（数量を増やすか新しいラインを追加）、remove（数量を減らし、0でライン削除）、またはreplace（カート全体の置換、actionを省略した場合と同じ）。
total_value Float 条件付き actionが省略されているかreplaceの場合は必須。actionがaddまたはremoveの場合はオプション。
subtotal_value Float いいえ カートの小計値（割引後、税・送料前）。
tax Float いいえ カートに適用される合計税額。
shipping Float いいえ カートの合計送料。
currency String はい 3文字のISO 4217コード。
products Array はい この更新のラインアイテム。カート全体の置換（actionなしまたはreplace）の場合、絶対数量を含むカート全体を含めます。addまたはremoveの場合、変更されたラインのみを含めます。製品プロパティを参照してください。
source String はい イベントの発生元。
metadata Object いいえ 追加のイベントレベルデータ用の柔軟なキーと値のペア。

製品プロパティ（products[]）

プロパティ データ型 必須 説明
product_id String はい 一意の製品識別子。
product_name String はい 製品の表示名。
variant_id String はい バリアント識別子。
image_url String いいえ 製品画像のURL。
product_url String いいえ 製品ページへのURL。
quantity Integer はい カート全体の置換（actionなしまたはreplace）の場合、このラインのカート内ユニット数。addまたはremoveの場合、追加または削除するユニット数。
price Float はい バリアント単価。
metadata Object いいえ 柔軟なキーと値のペア（例：colorやsize）。

ユーザーがチェックアウトフローを開始したとき（たとえば、「チェックアウト」を選択するか、チェックアウトページに到達したとき）にトリガーします。

クライアント側の実装

利用可能な場合はSDKのeコマースイベントAPIを使用してください。プラットフォーム固有の実装例については、Braze SDKを通じたeコマースイベントの記録を参照してください。

イベントプロパティ

プロパティ 型 必須 説明
checkout_id String はい チェックアウトセッションの一意の識別子。
cart_id String いいえ カート識別子。ユーザーのカートマッピング用にカート、チェックアウト、注文イベント間で共有されます。
total_value Float はい チェックアウトの合計金額。
subtotal_value Float いいえ 小計値（割引後、税・送料前）。
tax Float いいえ チェックアウトに適用される合計税額。
shipping Float いいえ 合計送料。
currency String はい 3文字のISO 4217コード。
products Array はい チェックアウト対象のアイテム。製品プロパティのサブテーブルを参照してください。
source String はい イベントの発生元。
metadata Object いいえ 柔軟なキーと値のペア。認識されるサブプロパティ：checkout_url（String）

製品プロパティ（products[]）

プロパティ データ型 必須 説明
product_id String はい 一意の製品識別子。
product_name String はい 製品の表示名。
variant_id String はい バリアント識別子。
image_url String いいえ 製品画像のURL。
product_url String いいえ 製品ページへのURL。
quantity Integer はい カート内のユニット数。
price Float はい バリアント単価。
metadata Object いいえ 柔軟なキーと値のペア（例：color、size）。

REST APIの例




{
  "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"
        }
      }
    }
  ]
}

注文が正常に完了したとき、または支払いが確認されたときにトリガーします。

クライアント側の実装

利用可能な場合はSDKのeコマースイベントAPIを使用してください。プラットフォーム固有の実装例については、Braze SDKを通じたeコマースイベントの記録を参照してください。

イベントプロパティ

プロパティ データ型 必須 説明
order_id String はい 注文の一意の識別子。
cart_id String いいえ カート識別子。ユーザーのカートマッピング用にカート、チェックアウト、注文イベント間で共有されます。
total_value Float はい 注文の合計金額。
subtotal_value Float いいえ 小計値（割引後、税・送料前）。
tax Float いいえ 注文に適用される合計税額。
shipping Float いいえ 合計送料。
currency String はい 3文字のISO 4217コード。
total_discounts Float いいえ 注文に適用された割引の合計額。
discounts Array いいえ 適用された割引の詳細リスト。
products Array はい 注文内のアイテム。製品プロパティのサブテーブルを参照してください。
source String はい イベントの発生元。
metadata Object いいえ 柔軟なキーと値のペア。認識されるサブプロパティ：order_status_url（String）

製品プロパティ（products[]）

プロパティ データ型 必須 説明
product_id String はい 一意の製品識別子。
product_name String はい 製品の表示名。
variant_id String はい バリアント識別子。
image_url String いいえ 製品画像のURL。
product_url String いいえ 製品ページへのURL。
quantity Integer はい カート内のユニット数。
price Float はい バリアント単価。
metadata Object いいえ 柔軟なキーと値のペア（例：colorやsize）。

REST APIの例




{
  "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"
        }
      }
    }
  ]
}

注文がキャンセルされたときにトリガーします。

クライアント側の実装

logCustomEventを使用します。プラットフォーム固有の実装例については、Braze SDKを通じたeコマースイベントの記録を参照してください。

イベントプロパティ

プロパティ 型 必須 説明
order_id String はい 注文の一意の識別子。
total_value Float はい キャンセルされる注文の合計金額。0以上である必要があります — 絶対値を送信してください。Brazeが減算を処理します。
subtotal_value Float いいえ 小計値（割引後、税・送料前）。
tax Float いいえ 注文に適用される合計税額。
shipping Float いいえ 合計送料。
currency String はい 3文字のISO 4217コード。
total_discounts Float いいえ 注文に適用された割引の合計額。
discounts Array いいえ 適用された割引の詳細リスト。
cancel_reason String はい 注文がキャンセルされた理由。
products Array はい キャンセルされた注文内のアイテム。製品プロパティのサブテーブルを参照してください。
source String はい イベントの発生元。
metadata Object いいえ 柔軟なキーと値のペア。認識されるサブプロパティ：order_status_url（String）

製品プロパティ（products[]）

プロパティ データ型 必須 説明
product_id String はい 一意の製品識別子。
product_name String はい 製品の表示名。
variant_id String はい バリアント識別子。
image_url String いいえ 製品画像のURL。
product_url String いいえ 製品ページへのURL。
quantity Integer はい カート内のユニット数。
price Float はい バリアント単価。
metadata Object いいえ 柔軟なキーと値のペア（例：colorやsize）。

REST APIの例




{
  "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"
        }
      }
    }
  ]
}

全額または一部の返金が発行されたときにトリガーします。

クライアント側の実装

logCustomEventを使用します。プラットフォーム固有の実装例については、Braze SDKを通じたeコマースイベントの記録を参照してください。

イベントプロパティ

プロパティ データ型 必須 説明
order_id String はい 元の注文の一意の識別子。
total_value Float はい 返金の合計金額。0以上である必要があります — 絶対値を送信してください。Brazeがtotal_refundsへの増分を処理します。
currency String はい 3文字のISO 4217コード。
total_discounts Float いいえ 元々適用されていた割引の合計額。
discounts Array いいえ 割引の詳細リスト。
products Array はい 返金対象のアイテム。製品プロパティのサブテーブルを参照してください。
source String はい イベントの発生元。
metadata Object いいえ 柔軟なキーと値のペア。認識されるサブプロパティ：order_status_url（String）。

製品プロパティ（products[]）

プロパティ データ型 必須 説明
product_id String はい 一意の製品識別子。
product_name String はい 製品の表示名。
variant_id String はい バリアント識別子。
image_url String いいえ 製品画像のURL。
product_url String いいえ 製品ページへのURL。
quantity Integer はい カート内のユニット数。
price Float はい バリアント単価。
metadata Object いいえ 柔軟なキーと値のペア（例：colorやsize）。

REST APIの例




{
  "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"
        }
      }
    }
  ]
}






{
  "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が各イベントに対して自動的に行う処理をまとめたものです。バリデーションに失敗した場合の動作については、イベントのバリデーションとトラブルシューティングを参照してください。

イベント Brazeが自動的に行う処理
ecommerce.order_placed ユーザープロファイル上の合計収益をtotal_valueだけ増加させ、合計注文数を1増加させます。
ecommerce.order_cancelled 合計注文数を1減少させます。
ecommerce.order_refunded 合計収益をtotal_valueだけ減少させ、合計返金額を増加させます。
ecommerce.cart_updated ユーザープロファイル上のカートマッピングオブジェクトを作成または更新します（カート全体のペイロード、またはオプションのaction（add、remove、replace）を使用した増分カート更新）。カートは更新なしで30日後に期限切れになります。
ecommerce.product_viewed ユーザープロファイルの変更はありません。セグメンテーション、トリガー、およびアイテムレコメンデーションなどのBrazeAITM機能で利用可能です。
ecommerce.checkout_started ユーザープロファイルの変更はありません。セグメンテーションとトリガー（チェックアウト離脱フローなど）で利用可能です。

実装の詳細

データポイントと課金

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

イベントサイズの制限

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

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

通貨の処理

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

sourceフィールド

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

メタデータの柔軟性

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

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

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

バリデーションの内容

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

チェック項目 例
イベント名 正確に一致する必要があります。例えば、ecommerce.cart_updatedが正しく、ecommerce.Cart_Updated、cartupdated、cart_updatedは不正です。
必須プロパティの存在 order_placedにはorder_id、total_value、currency、products、sourceが必要です。
正しいデータタイプ total_valueは数値、currencyは文字列、productsは配列でなければなりません。
余分なトップレベルプロパティがないこと プロパティ配下のカスタムフィールドは失敗の原因になります。代わりにmetadataオブジェクトを使用してください。
値の制約 金額フィールドは0以上でなければなりません。currencyは有効なISO 4217文字列でなければなりません。
製品ごとのフィールド products[]の各アイテムにはproduct_id、product_name、variant_id、quantity、priceが含まれている必要があります。

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

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

バリデーション成功時

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

成功したイベントの確認

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

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

バリデーション失敗時

イベントは推奨イベントとして処理されません。具体的には以下のとおりです。

  • イベントは完全にドロップされます。無効な推奨eコマースイベントはユーザープロファイルに記録されず、Currentsに表示されず、セグメンテーションにも利用できません。
  • 以下を含む下流の推奨イベント機能が実行されません。
    • 収益トラッキング（収益レポート、total_revenueなどのユーザー計算フィールド）
    • ユーザープロファイルのカートオブジェクト更新
    • キャンバスやキャンペーンのカート更新または注文確定トリガー

エラーの報告方法はインジェストパスによって異なります。

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

APIエラーレスポンスの例

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




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

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

失敗タイプ 意味 例
missing_property 必須フィールドが存在しません。 order_placedがorder_idなしで送信された場合。
extra_property スキーマで定義されていないフィールドが追加されました。 カスタムのgift_wrappedフィールドがmetadata内ではなくpropertiesのトップレベルにある場合。
unexpected_data_type フィールドのタイプが不正です。 total_value: "29.99"（文字列）ではなく29.99（数値）であるべき場合。

失敗の検出

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. 次の失敗メールを監視して、そのイベント、ソース、タイプの失敗カウントがゼロに減少したことを確認します。

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

Documentation for the Braze customer engagement platform.

Resources
Legal
Company
© 2026 Braze, Inc. All rights reserved.
Braze ステータスの確認
New Stuff!