おすすめイベント

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

eコマース推奨イベント

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、アイテムのおすすめなどのBrazeAI^TM機能への活用、およびその他の機能も利用可能です。

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

重要

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

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

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

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

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

また、プラットフォームがカスタムイベントをサポートする場所であれば、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コマース推奨イベントは、購入ジャーニーのステージに対応しています。ユーザーが対応するアクションを完了した時点で各イベントを発火させてください。

• ecommerce.product_viewed
• ecommerce.cart_updated
• ecommerce.checkout_started
• ecommerce.order_placed
• ecommerce.order_cancelled
• ecommerce.order_refunded

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

イベントプロパティ

プロパティ名	データタイプ	必須	説明
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	オブジェクト	いいえ	柔軟なキーと値のペア。認識されるサブプロパティ: sku (文字列)

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

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

このイベントは以下の2つの方法で送信できます:

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

警告

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

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

ヒント

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

イベントプロパティ

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

コード例

以下の各プラットフォームタブでは、そのインテグレーションパスに対応するスニペットレイアウトを使用しています (例: フェンスブロック内の見出しやラベル)。add、remove、replaceのペイロードはプラットフォーム間で同じです。SDKまたはAPIサーフェスのみが異なります。

• web
• android
• swift
• rest api

add

addは数量を増加させるか、新しいラインを追加します。quantityプロパティは追加するユニット数です。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
braze.logCustomEvent("ecommerce.cart_updated", {
  cart_id: "cart_abc123",
  action: "add",
  currency: "USD",
  source: "web",
  products: [
    {
      product_id: "SKU-RUN-4821",
      product_name: "Ultraboost Running Shoe",
      variant_id: "UB-BLK-11",
      quantity: 1,
      price: 189.99,
    },
  ],
});

remove

removeはquantityの量だけ数量を減少させます。数量が0に達するとラインが削除されます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
braze.logCustomEvent("ecommerce.cart_updated", {
  cart_id: "cart_abc123",
  action: "remove",
  currency: "USD",
  source: "web",
  products: [
    {
      product_id: "SKU-SOC-1102",
      product_name: "Performance Running Socks",
      variant_id: "SOC-WHT-L",
      quantity: 1,
      price: 14.99,
    },
  ],
});

replace

replace (またはactionを省略) はカート全体を送信します。total_valueは必須です。

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
braze.logCustomEvent("ecommerce.cart_updated", {
  cart_id: "cart_abc123",
  action: "replace",
  total_value: 234.96,
  currency: "USD",
  source: "web",
  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,
    },
    {
      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,
    },
  ],
});

追加

addは数量を増加させるか、新しいラインを追加します。quantityプロパティは追加するユニット数です。

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
Kotlin

// add — units to add
Braze.getInstance(context).logCustomEvent(
  "ecommerce.cart_updated",
  BrazeProperties(
    JSONObject()
      .put("cart_id", "cart_abc123")
      .put("action", "add")
      .put("currency", "USD")
      .put("source", "android")
      .put(
        "products",
        JSONArray().put(
          JSONObject()
            .put("product_id", "SKU-RUN-4821")
            .put("product_name", "Ultraboost Running Shoe")
            .put("variant_id", "UB-BLK-11")
            .put("quantity", 1)
            .put("price", 189.99),
        ),
      ),
  ),
)

JavaScript

// add — units to add
Braze.getInstance(context).logCustomEvent(
    "ecommerce.cart_updated",
    new BrazeProperties(new JSONObject()
        .put("cart_id", "cart_abc123")
        .put("action", "add")
        .put("currency", "USD")
        .put("source", "android")
        .put("products", new JSONArray()
            .put(new JSONObject()
                .put("product_id", "SKU-RUN-4821")
                .put("product_name", "Ultraboost Running Shoe")
                .put("variant_id", "UB-BLK-11")
                .put("quantity", 1)
                .put("price", 189.99)))));

削除

removeはquantityの量だけ数量を減少させます。数量が0に達するとラインが削除されます。

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
Kotlin

// remove — units to remove
Braze.getInstance(context).logCustomEvent(
  "ecommerce.cart_updated",
  BrazeProperties(
    JSONObject()
      .put("cart_id", "cart_abc123")
      .put("action", "remove")
      .put("currency", "USD")
      .put("source", "android")
      .put(
        "products",
        JSONArray().put(
          JSONObject()
            .put("product_id", "SKU-SOC-1102")
            .put("product_name", "Performance Running Socks")
            .put("variant_id", "SOC-WHT-L")
            .put("quantity", 1)
            .put("price", 14.99),
        ),
      ),
  ),
)

JavaScript

// remove — units to remove
Braze.getInstance(context).logCustomEvent(
    "ecommerce.cart_updated",
    new BrazeProperties(new JSONObject()
        .put("cart_id", "cart_abc123")
        .put("action", "remove")
        .put("currency", "USD")
        .put("source", "android")
        .put("products", new JSONArray()
            .put(new JSONObject()
                .put("product_id", "SKU-SOC-1102")
                .put("product_name", "Performance Running Socks")
                .put("variant_id", "SOC-WHT-L")
                .put("quantity", 1)
                .put("price", 14.99)))));

置き換え

replace (またはactionを省略) はカート全体を送信します。total_valueは必須です。

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
59
Kotlin

// replace — full cart; total_value required
Braze.getInstance(context).logCustomEvent(
  "ecommerce.cart_updated",
  BrazeProperties(
    JSONObject()
      .put("cart_id", "cart_abc123")
      .put("action", "replace")
      .put("total_value", 234.96)
      .put("currency", "USD")
      .put("source", "android")
      .put(
        "products",
        JSONArray()
          .put(
            JSONObject()
              .put("product_id", "SKU-RUN-4821")
              .put("product_name", "Ultraboost Running Shoe")
              .put("variant_id", "UB-BLK-11")
              .put("quantity", 1)
              .put("price", 189.99),
          )
          .put(
            JSONObject()
              .put("product_id", "SKU-SOC-1102")
              .put("product_name", "Performance Running Socks")
              .put("variant_id", "SOC-WHT-L")
              .put("quantity", 2)
              .put("price", 14.99),
          ),
      ),
  ),
)

JavaScript

// replace — full cart; total_value required
Braze.getInstance(context).logCustomEvent(
    "ecommerce.cart_updated",
    new BrazeProperties(new JSONObject()
        .put("cart_id", "cart_abc123")
        .put("action", "replace")
        .put("total_value", 234.96)
        .put("currency", "USD")
        .put("source", "android")
        .put("products", new JSONArray()
            .put(new JSONObject()
                .put("product_id", "SKU-RUN-4821")
                .put("product_name", "Ultraboost Running Shoe")
                .put("variant_id", "UB-BLK-11")
                .put("quantity", 1)
                .put("price", 189.99))
            .put(new JSONObject()
                .put("product_id", "SKU-SOC-1102")
                .put("product_name", "Performance Running Socks")
                .put("variant_id", "SOC-WHT-L")
                .put("quantity", 2)
                .put("price", 14.99)))));

追加

addは数量を増加させるか、新しいラインを追加します。quantityプロパティは追加するユニット数です。

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
Swift

// add — units to add
AppDelegate.braze?.logCustomEvent(
  name: "ecommerce.cart_updated",
  properties: [
    "cart_id": "cart_abc123",
    "action": "add",
    "currency": "USD",
    "source": "ios",
    "products": [
      [
        "product_id": "SKU-RUN-4821",
        "product_name": "Ultraboost Running Shoe",
        "variant_id": "UB-BLK-11",
        "quantity": 1,
        "price": 189.99,
      ],
    ],
  ]
)

Objective-C

// add — units to add
[AppDelegate.braze logCustomEvent:@"ecommerce.cart_updated"
                       properties:@{
  @"cart_id": @"cart_abc123",
  @"action": @"add",
  @"currency": @"USD",
  @"source": @"ios",
  @"products": @[@{
    @"product_id": @"SKU-RUN-4821",
    @"product_name": @"Ultraboost Running Shoe",
    @"variant_id": @"UB-BLK-11",
    @"quantity": @1,
    @"price": @189.99,
  }],
}];

削除

removeはquantityの量だけ数量を減少させます。数量が0に達するとラインが削除されます。

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
Swift

// remove — units to remove
AppDelegate.braze?.logCustomEvent(
  name: "ecommerce.cart_updated",
  properties: [
    "cart_id": "cart_abc123",
    "action": "remove",
    "currency": "USD",
    "source": "ios",
    "products": [
      [
        "product_id": "SKU-SOC-1102",
        "product_name": "Performance Running Socks",
        "variant_id": "SOC-WHT-L",
        "quantity": 1,
        "price": 14.99,
      ],
    ],
  ]
)

Objective-C

// remove — units to remove
[AppDelegate.braze logCustomEvent:@"ecommerce.cart_updated"
                       properties:@{
  @"cart_id": @"cart_abc123",
  @"action": @"remove",
  @"currency": @"USD",
  @"source": @"ios",
  @"products": @[@{
    @"product_id": @"SKU-SOC-1102",
    @"product_name": @"Performance Running Socks",
    @"variant_id": @"SOC-WHT-L",
    @"quantity": @1,
    @"price": @14.99,
  }],
}];

置き換え

replace (またはactionを省略) はカート全体を送信します。total_valueは必須です。

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
Swift

// replace — full cart; total_value required
AppDelegate.braze?.logCustomEvent(
  name: "ecommerce.cart_updated",
  properties: [
    "cart_id": "cart_abc123",
    "action": "replace",
    "total_value": 234.96,
    "currency": "USD",
    "source": "ios",
    "products": [
      [
        "product_id": "SKU-RUN-4821",
        "product_name": "Ultraboost Running Shoe",
        "variant_id": "UB-BLK-11",
        "quantity": 1,
        "price": 189.99,
      ],
      [
        "product_id": "SKU-SOC-1102",
        "product_name": "Performance Running Socks",
        "variant_id": "SOC-WHT-L",
        "quantity": 2,
        "price": 14.99,
      ],
    ],
  ]
)

Objective-C

// replace — full cart; total_value required
[AppDelegate.braze logCustomEvent:@"ecommerce.cart_updated"
                       properties:@{
  @"cart_id": @"cart_abc123",
  @"action": @"replace",
  @"total_value": @234.96,
  @"currency": @"USD",
  @"source": @"ios",
  @"products": @[
    @{
      @"product_id": @"SKU-RUN-4821",
      @"product_name": @"Ultraboost Running Shoe",
      @"variant_id": @"UB-BLK-11",
      @"quantity": @1,
      @"price": @189.99,
    },
    @{
      @"product_id": @"SKU-SOC-1102",
      @"product_name": @"Performance Running Socks",
      @"variant_id": @"SOC-WHT-L",
      @"quantity": @2,
      @"price": @14.99,
    },
  ],
}];

add

addは数量を増加させるか、新しいラインを追加します。quantityプロパティは追加するユニット数です。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.cart_updated",
      "time": "2026-04-28T14:25:33Z",
      "properties": {
        "cart_id": "cart_abc123",
        "action": "add",
        "currency": "USD",
        "source": "web",
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "quantity": 1,
            "price": 189.99
          }
        ]
      }
    }
  ]
}

remove

removeはquantityの量だけ数量を減少させます。数量が0に達するとラインが削除されます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.cart_updated",
      "time": "2026-04-28T14:26:10Z",
      "properties": {
        "cart_id": "cart_abc123",
        "action": "remove",
        "currency": "USD",
        "source": "web",
        "products": [
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "quantity": 1,
            "price": 14.99
          }
        ]
      }
    }
  ]
}

replace

replace (またはactionを省略) はカート全体を送信します。total_valueは必須です。

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
{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.cart_updated",
      "time": "2026-04-28T14:27:00Z",
      "properties": {
        "cart_id": "cart_abc123",
        "action": "replace",
        "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"
        }
      }
    }
  ]
}

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

イベントプロパティ

プロパティ	タイプ	必須	説明
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	オブジェクト	いいえ	柔軟なキーと値のペア (例: color、size)。

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

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

重要

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

イベントプロパティ

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

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

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

重要

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

イベントプロパティ

プロパティ	タイプ	必須	説明
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の例

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

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

重要

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

イベントプロパティ

プロパティ	データタイプ	必須	説明
order_id	文字列	はい	元の注文の一意の識別子。
total_value	フロート	はい	返金の合計金額。0以上である必要があります。絶対値を送信してください。Brazeがtotal_refundsへの増加処理を行います。
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の例

• 全額返金
• 一部返金

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

重要

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

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

ヒント

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

ソースフィールド

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

メタデータの柔軟性

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

重要

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

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

注

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

失敗の確認

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

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