コンテンツにスキップ

推奨イベント

推奨イベントは、定義済みの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の削除における「Places order」トリガーアクション
  • 計算済みの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) を通じたユーザージャーニーの図。

クライアント側のログ記録では、ecommerce.product_viewed、ecommerce.cart_updated、ecommerce.checkout_started、ecommerce.order_placedは利用可能な場合SDKのeコマースイベントAPIを使用し、ecommerce.order_cancelledとecommerce.order_refundedはlogCustomEventを使用します。

返金イベントとキャンセルイベントは、返金フローなどのサーバー側のロジックの完了に依存することが多いため、通常はBraze REST APIを介してサーバーから送信されます。プラットフォーム固有の実装例については、Braze SDKを介してeコマースイベントをログに記録するを参照してください。

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

クライアント側の実装

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

イベントプロパティ

プロパティ名 データタイプ 必須 説明
product_id 文字列 はい 一意の製品識別子 (SKUやアイテムIDなど)。
product_name 文字列 はい 製品の表示名。
variant_id 文字列 はい 製品バリアントの識別子 (shirt_medium_blueなど)。
image_url 文字列 いいえ 製品画像のURL。
product_url 文字列 いいえ 詳細を確認できる製品ページのURL。
price 浮動小数点数 はい 閲覧時点のバリアントの単価。
currency 文字列 はい 3文字のISO 4217コード (USDやEURなど)。
source 文字列 はい イベントの発生元 (web、ios、androidなど)。
type 文字列の配列 いいえ 在庫復活アラートと値下げアラートにBrazeのカタログトリガー機能を使用する場合は必須です。指定可能な値: "price_drop"、"back_in_stock"
metadata オブジェクト いいえ 柔軟なキーと値のペア (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になると明細を削除します。addとremoveでは、total_valueは任意です。

このイベントからメッセージングをトリガーするには、キャンバスとキャンペーンでPerform Cart Updated Eventトリガーを使用します。このトリガーには、カートがショッピングファネルを進まないようにするための特別な処理が含まれています。

イベントプロパティ

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

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

プロパティ データタイプ 必須 説明
product_id 文字列 はい 一意の製品識別子。
product_name 文字列 はい 製品の表示名。
variant_id 文字列 はい バリアントの識別子。
image_url 文字列 いいえ 製品画像のURL。
product_url 文字列 いいえ 製品ページのURL。
quantity 整数 はい 全体置換 (actionなしまたはreplace) の場合は、この明細のカート内の数量。addまたはremoveの場合は、追加または削除する数量。
price 浮動小数点数 はい バリアントの単価。
metadata オブジェクト いいえ 柔軟なキーと値のペア (colorやsizeなど)。

ユーザーがチェックアウトフローを開始したとき (「チェックアウト」を選択した、またはチェックアウトページにアクセスしたときなど) にトリガーします。

クライアント側の実装

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

イベントプロパティ

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

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

プロパティ データタイプ 必須 説明
product_id 文字列 はい 一意の製品識別子。
product_name 文字列 はい 製品の表示名。
variant_id 文字列 はい バリアントの識別子。
image_url 文字列 いいえ 製品画像のURL。
product_url 文字列 いいえ 製品ページのURL。
quantity 整数 はい カート内の数量。
price 浮動小数点数 はい バリアントの単価。
metadata オブジェクト いいえ 柔軟なキーと値のペア (色、サイズなど)。

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 文字列 はい 注文の一意の識別子。
cart_id 文字列 いいえ カートの識別子。ユーザーのカートマッピングのため、カート、チェックアウト、注文の各イベント間で共有されます。
total_value 浮動小数点数 はい 注文の合計金額。
subtotal_value 浮動小数点数 いいえ 小計 (割引後、税金/送料前)。
tax 浮動小数点数 いいえ 注文に適用される税金の合計。
shipping 浮動小数点数 いいえ 送料の合計。
currency 文字列 はい 3文字のISO 4217コード。
total_discounts 浮動小数点数 いいえ 注文に適用された割引の合計額。
discounts 配列 いいえ 適用された割引の詳細リスト。
products 配列 はい 注文に含まれるアイテム。製品プロパティのサブテーブルを参照してください。
source 文字列 はい イベントの発生元。
metadata オブジェクト いいえ 柔軟なキーと値のペア。認識されるサブプロパティ: order_status_url (文字列)

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

プロパティ データタイプ 必須 説明
product_id 文字列 はい 一意の製品識別子。
product_name 文字列 はい 製品の表示名。
variant_id 文字列 はい バリアントの識別子。
image_url 文字列 いいえ 製品画像のURL。
product_url 文字列 いいえ 製品ページのURL。
quantity 整数 はい カート内の数量。
price 浮動小数点数 はい バリアントの単価。
metadata オブジェクト いいえ 柔軟なキーと値のペア (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 文字列 はい 注文の一意の識別子。
total_value 浮動小数点数 はい キャンセルされる注文の合計金額。0以上である必要があります。絶対額を送信してください。減算はBrazeが処理します。
subtotal_value 浮動小数点数 いいえ 小計 (割引後、税金/送料前)。
tax 浮動小数点数 いいえ 注文に適用される税金の合計。
shipping 浮動小数点数 いいえ 送料の合計。
currency 文字列 はい 3文字のISO 4217コード。
total_discounts 浮動小数点数 いいえ 注文に適用された割引の合計額。
discounts 配列 いいえ 適用された割引の詳細リスト。
cancel_reason 文字列 はい 注文がキャンセルされた理由。
products 配列 はい キャンセルされた注文に含まれるアイテム。製品プロパティのサブテーブルを参照してください。
source 文字列 はい イベントの発生元。
metadata オブジェクト いいえ 柔軟なキーと値のペア。認識されるサブプロパティ: order_status_url (文字列)

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

プロパティ データタイプ 必須 説明
product_id 文字列 はい 一意の製品識別子。
product_name 文字列 はい 製品の表示名。
variant_id 文字列 はい バリアントの識別子。
image_url 文字列 いいえ 製品画像のURL。
product_url 文字列 いいえ 製品ページのURL。
quantity 整数 はい カート内の数量。
price 浮動小数点数 はい バリアントの単価。
metadata オブジェクト いいえ 柔軟なキーと値のペア (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 文字列 はい 元の注文の一意の識別子。
total_value 浮動小数点数 はい 返金の合計金額。0以上である必要があります。絶対額を送信してください。total_refundsへの加算はBrazeが処理します。
currency 文字列 はい 3文字のISO 4217コード。
total_discounts 浮動小数点数 いいえ 元の注文に適用された割引の合計額。
discounts 配列 いいえ 割引の詳細リスト。
products 配列 はい 返金対象のアイテム。製品プロパティのサブテーブルを参照してください。
source 文字列 はい イベントの発生元。
metadata オブジェクト いいえ 柔軟なキーと値のペア。認識されるサブプロパティ: order_status_url (文字列)。

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

プロパティ データタイプ 必須 説明
product_id 文字列 はい 一意の製品識別子。
product_name 文字列 はい 製品の表示名。
variant_id 文字列 はい バリアントの識別子。
image_url 文字列 いいえ 製品画像のURL。
product_url 文字列 いいえ 製品ページのURL。
quantity 整数 はい カート内の数量。
price 浮動小数点数 はい バリアントの単価。
metadata オブジェクト いいえ 柔軟なキーと値のペア (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 ユーザープロファイル上のcartsマッピングオブジェクトを作成または更新します (カート全体のペイロード、または任意のaction (add、remove、replace) による増分更新)。カートは、30日間更新がないと期限切れになります。
ecommerce.product_viewed ユーザープロファイルは変更されません。セグメンテーション、トリガー、BrazeAITM機能 (アイテムレコメンデーションなど) で使用できます。
ecommerce.checkout_started ユーザープロファイルは変更されません。セグメンテーションとトリガー (チェックアウト放棄フローなど) で使用できます。

実装の詳細

データポイントと請求

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

イベントサイズの上限

/users/track に送信されるイベントプロパティは、1イベントあたり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 プロパティは、イベントの発生元を識別する必須の文字列です。たとえば、shopify、in-store POS、custom_api などです。これにより、Currentsエクスポートでデータを分析する際や、バリデーションの問題をデバッグする際に、連携元を区別しやすくなります。

メタデータの柔軟性

イベントレベルと製品レベルのメタデータオブジェクトはどちらも任意のキーと値のペアを受け付けるため、コアスキーマを変更せずにカスタムディメンションを追加できます。一般的な例としては、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は次の項目をチェックします。

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

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

eコマースイベントは、収益トラッキング、{% shopping_cart %} Liquidタグ、放棄カートトリガー、レポートなど、一貫性があり予測可能なデータに依存する機能を支えています。ペイロードがスキーマから外れると、これらの機能では気づかないうちに不正確な結果（誤った収益合計、カートの欠落、トリガーの不具合）が生じます。バリデーションによって事前に契約を徹底することで、下流の機能が予測どおりに動作します。

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

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

成功したイベントを確認する

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

  • イベントユーザーログ：ダッシュボードでユーザーのプロファイルを開き、アクティビティを確認します。推奨イベントはプロパティのペイロード全体とともに表示されるため、イベントが届いていること、および値が送信した内容と一致していることを確認できます。
  • カスタムイベントレポート：分析 > カスタムイベントレポートに移動すると、各推奨イベントの経時的な集計数を確認できます。インテグレーションの稼働後に、本番トラフィックが想定どおりに流れていることを確認するのに役立ちます。
  • テストユーザー：開発用ワークスペースでユーザーをテストユーザーとしてマークし、そのユーザーに対してインテグレーションからイベントをトリガーします。テストユーザーはダッシュボード上でフラグが付けられるため、エンドツーエンドの動作を簡単に切り分けて調べることができます。

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

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

  • イベントは完全に破棄されます。無効な推奨eコマースイベントはユーザープロファイルに記録されず、Currentsにも表示されず、セグメンテーションにも使用できません。
  • 次のような下流の推奨イベント機能は実行されません。
    • 収益トラッキング（収益レポート、total_revenueなどのユーザー計算フィールド）
    • ユーザープロファイル上のカートオブジェクトの更新
    • キャンバスおよびキャンペーンにおけるUpdate CartまたはPlace Orderトリガー

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

  • REST API（/users/track）：無効なイベントはそれぞれ、レスポンスのerrors配列で報告されます。各エントリには、どのイベントが失敗したか（index）と、その理由（type）が示されます。トップレベルのmessageフィールドには引き続き「success」と表示されますが、これはリクエストがBrazeに到達したことを意味するだけで、すべてのイベントが有効だったことを意味するわけではありません。レスポンスにerrors配列が含まれていないか、必ず確認してください。
  • 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_idなしで送信されたorder_placed。
extra_property スキーマで定義されていないフィールドが追加されています。 metadata内ではなくpropertiesのトップレベルに置かれたカスタムのgift_wrappedフィールド。
unexpected_data_type フィールドのタイプが誤っています。 29.99（数値）ではなくtotal_value: "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. 次の失敗メールをモニタリングし、そのイベント、ソース、タイプの失敗数がゼロになったことを確認します。

各イベントのプロパティ要件の詳細については、イベントスキーマを参照してください。

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

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