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

推奨イベント

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

eコマース推奨イベント

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

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

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

重要

レガシーの購入イベントはメンテナンスモードに移行します。既存のBrazeのお客様は、レガシーの購入イベントを引き続き使用できます。購入イベントは引き続き期待どおりに動作しますが、今後はeコマース推奨イベントを基盤として新しい機能が構築されます。Brazeは、サポート終了日が設定されるかなり前に事前通知を行います。新規のBrazeのお客様は、eコマース推奨イベントを使用してください。レガシーの購入イベントは利用できません。

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

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

注

CSVアップロードはeコマースイベントをサポートしていません。これらのイベントを送信するには、SDK、/users/track、またはCDIを使用してください。

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

キャンペーン、キャンバス、アクションパス、アプリ内メッセージトリガー、Content Cardsの削除における「注文する」トリガーアクション
計算済みeコマースユーザープロファイルフィールド（合計収益、合計注文数、合計返金額）
カート放棄フローのためのカート状態管理
予測イベント、解約予測、アイテムレコメンデーションなどのBrazeAI^TM機能のためのより豊富なデータ

また、プラットフォームがカスタムイベントをサポートしている場所であれば、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）を通じたユーザージャーニーの図

ヒント

以下の例は、各イベントのREST APIペイロードを示しています。クライアントサイドのロギングでは、ecommerce.product_viewed、ecommerce.cart_updated、ecommerce.checkout_started、ecommerce.order_placedは利用可能な場合にSDKのeコマースイベントAPIを使用し、ecommerce.order_cancelledとecommerce.order_refundedはlogCustomEventを使用します。プラットフォーム固有の実装例については、Braze SDKを通じたeコマースイベントのロギングを参照してください。

ユーザーが製品詳細ページを閲覧したときにトリガーします。このイベントは、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"
        }
      }
    }
  ]
}

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

クライアントサイドの実装

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

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

警告

特定のcart_idに対して、増分カート更新（addまたはremove）またはカート全体の置換（actionなしまたはreplace）のいずれかを使用してください。同じcart_idに対して両方のアプローチを混在させることは推奨されず、Brazeでカート状態が不整合になる可能性があります。

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

ヒント

カートは、{% shopping_cart %} Liquidタグを動作させるユーザープロファイル上のカートマッピングオブジェクトを作成します。カートは更新なしで30日後に期限切れになります。2つのユーザープロファイルがマージされた場合、Brazeは両方のカートを保持します。

イベントプロパティ

プロパティ	データタイプ	必須	説明
`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`）。

ユーザーがチェックアウトフローを開始したとき（例：「チェックアウト」を選択した場合やチェックアウトページに到達した場合）にトリガーします。

クライアントサイドの実装

イベントプロパティ

プロパティ	タイプ	必須	説明
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"
        }
      }
    }
  ]
}

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

クライアントサイドの実装

重要

このイベントは主要な収益ドライバーです。ユーザープロファイル上でtotal_revenueをtotal_valueの値だけ増加させ、total_ordersを1増加させます。

イベントプロパティ

プロパティ	データタイプ	必須	説明
`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コマースイベントのロギングを参照してください。

重要

このイベントはユーザープロファイル上のtotal_ordersを1減少させます。total_revenueには影響しません。収益を調整するにはorder_refundedを使用してください。

イベントプロパティ

プロパティ	タイプ	必須	説明
`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コマースイベントのロギングを参照してください。

重要

このイベントはユーザープロファイル上のtotal_revenueをtotal_valueの値だけ減少させ、total_refundsを増加させます。一部返金の場合、total_valueを元の注文合計ではなく、返金額のみに設定してください。

イベントプロパティ

プロパティ	データタイプ	必須	説明
`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`）。

{
  "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`	ユーザープロファイルの変更はありません。セグメンテーション、トリガー、およびBrazeAI^TM機能（アイテムレコメンデーションなど）で利用可能です。
`ecommerce.checkout_started`	ユーザープロファイルの変更はありません。セグメンテーションとトリガー（例：チェックアウト放棄フロー）で利用可能です。

重要

USD以外の通貨値は、イベントが報告された日の為替レートを使用して自動的にUSDに変換されます。すでにUSDで報告している場合は、意図しない変換を避けるために通貨としてUSDをハードコードしてください。

実装の詳細

データポイントと課金

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に変換します。この変換された値が収益指標に表示されます。

ヒント

USDのみで運用している場合は、不要な変換を避けるために、すべてのイベントで"currency": "USD"をハードコードしてください。

sourceフィールド

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

メタデータの柔軟性

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

重要

推奨イベントは厳密なスキーマを使用します。そのため、プロパティのトップレベルにカスタムプロパティを追加するとバリデーションに失敗します。すべてのカスタムプロパティは、イベントレベルのmetadataオブジェクトまたはproducts[]内の製品レベルのmetadataオブジェクトに配置してください。これらはトップレベルのフィールドと同様に、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コマース推奨イベントを参照してください。

成功したイベントの確認

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

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

バリデーション失敗時

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

イベントは完全にドロップされます。無効な推奨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`（数値）の代わりに送信された場合。

注

推奨イベントと名前が完全に一致しないイベント名（例：ecommerce.OrderPlaced）はバリデーションを完全にスキップし、通常のカスタムイベントとして記録されます。これらはCurrentsやセグメンテーションに送信した名前で表示されますが、推奨イベントの処理は行われず、レスポンスにerrorsエントリも含まれません。

失敗の確認

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

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

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

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

失敗の診断と修正

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

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

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

New Stuff!

推奨イベント

eコマース推奨イベント

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

イベントの命名

イベントスキーマ

クライアントサイドの実装

イベントプロパティ

REST APIの例

クライアントサイドの実装

イベントプロパティ

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

クライアントサイドの実装

イベントプロパティ

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

REST APIの例

クライアントサイドの実装

イベントプロパティ

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

REST APIの例

クライアントサイドの実装

イベントプロパティ

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

REST APIの例

クライアントサイドの実装

イベントプロパティ

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

REST APIの例

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

実装の詳細

データポイントと課金

イベントサイズの制限

通貨の処理

sourceフィールド

メタデータの柔軟性

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

バリデーション内容

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

バリデーション成功時

成功したイベントの確認

バリデーション失敗時

APIエラーレスポンスの例

失敗の確認

失敗の診断と修正

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

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

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

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

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