Skip to content

Empfohlene Events

Empfohlene Events basieren auf einem Framework, das standardisierte angepasste Events mit definierten JSON-Schemata sendet. Wenn Sie ein empfohlenes Event senden, validiert Braze es bei der Aufnahme gegen sein Schema und wendet eine spezialisierte Nachbearbeitung an – wie automatische Feldberechnungen oder Warenkorb-Verwaltung –, die generische angepasste Events nicht erhalten. Für bestimmte branchenspezifische Event-Sets unterstützt Braze außerdem eine spezielle Behandlung, wie z. B. dedizierte aktionsbasierte Trigger für Campaigns und Canvases.

Empfohlene E-Commerce-Events decken sechs Schritte der Kaufreise ab: product_viewed, cart_updated, checkout_started, order_placed, order_cancelled und order_refunded. Wenn Sie diese Events erfolgreich senden, validiert Braze die Daten und stellt sie einer wachsenden Anzahl von Plattform-Features zur Verfügung.

Zu diesen Features gehören Canvas-Templates für abgebrochenes Browsen, Warenkorb-Abbruch, abgebrochenen Checkout und Bestellbestätigungs-Flows; E-Commerce-Reporting; und berechnete Nutzerprofilfelder für Gesamtumsatz, Gesamtbestellungen und Gesamterstattungen. Sie können außerdem Segmente mithilfe verschachtelter Produkteigenschafts-Filterung über Segmenterweiterungen erstellen, Warenkorb-Abbruch-Nachrichten mit dem {% shopping_cart %} Liquid-Tag personalisieren und BrazeAITM-Funktionen wie Predictive Events, voraussichtliche Abwanderung und Artikelempfehlungen sowie weitere Funktionen nutzen.

Da diese Events einem definierten Schema folgen, kann jedes unterstützte Feature die strukturierten Daten ohne angepasstes Property-Mapping oder Feature-spezifische Konfiguration auf Ihrer Seite lesen.

So funktionieren E-Commerce-Events

E-Commerce-Events sind angepasste Events mit vordefinierten Namen und Eigenschafts-Schemas. Sie senden sie über das Braze SDK, den /users/track REST API-Endpunkt oder Cloud Data Ingestion (CDI), und Braze validiert jedes Event bei der Aufnahme gegen sein Schema. Wenn die Validierung erfolgreich ist, wendet Braze automatisch eine für diesen Event-Typ spezifische Nachverarbeitung an, wie z. B. die Berechnung von Umsatzfeldern und die Verwaltung des Warenkorb-Status in Nutzerprofilen.

E-Commerce-Events funktionieren überall dort, wo auch andere angepasste Events funktionieren: Trigger und Filter für durchgeführte angepasste Events, Reporting für angepasste Events und mehr. Ihre Schema-Validierung schaltet jedoch zusätzliche Funktionen frei, darunter:

  • Trigger-Aktionen „Gibt Bestellung auf“ in Campaigns, Canvases, Aktionspfaden, In-App-Nachricht-Triggern und Content-Card-Entfernung
  • Berechnete E-Commerce-Nutzerprofilfelder (Gesamtumsatz, Gesamtbestellungen, Gesamterstattungen)
  • Warenkorb-Status-Verwaltung für Warenkorb-Abbruch-Flows
  • Umfangreichere Daten für BrazeAITM-Features wie Predictive Events, voraussichtliche Abwanderung und Artikelempfehlungen

Sie können E-Commerce-Events auch überall dort namentlich referenzieren, wo die Plattform angepasste Events unterstützt. Zum Beispiel können Sie eine aktionsbasierte Campaign mit ecommerce.product_viewed-Events triggern, ein Segment erstellen, das nach ecommerce.checkout_started-Events filtert, oder ecommerce.order_placed-Events über Currents exportieren.

Event-Benennung

Event-Namen sind exakt, Groß-/Kleinschreibung wird beachtet, und sie sind durch Punkte getrennt. Verwenden Sie immer das kanonische Format. Wenn ein Event-Name nicht exakt einem der sechs kanonischen Namen entspricht, behandelt Braze ihn als Standard-Event und es findet keine E-Commerce-Nachverarbeitung statt.

Sie können Events nicht anpassen oder umbenennen.

  • Korrekt: ecommerce.order_placed
  • Falsch: order.placed, eCommerce_order_placed, Order_Placed

Event-Schemas

Die sechs empfohlenen E-Commerce-Events bilden Phasen der Kaufreise ab. Lösen Sie jedes Event in dem Moment aus, in dem die Nutzer:innen die entsprechende Aktion abschließen.

Diagramm der Nutzerreise durch alle sechs empfohlenen E-Commerce-Events: product_viewed, cart_updated, checkout_started, order_placed, order_cancelled und order_refunded.

Lösen Sie dieses Event aus, wenn Nutzer:innen eine Produktdetailseite aufrufen. Dieses Event ist kompatibel mit den Braze-Katalog-Features Wieder-verfügbar-Benachrichtigungen und Preissenkungsbenachrichtigungen.

Clientseitige Implementierung

Verwenden Sie die SDK-E-Commerce-Event-APIs, sofern verfügbar. Plattformspezifische Implementierungsbeispiele finden Sie unter E-Commerce-Events über das Braze SDK protokollieren.

Event-Eigenschaften

Eigenschaftsname Datentyp Erforderlich Beschreibung
product_id String Ja Eindeutiger Produktbezeichner (z. B. SKU oder Artikel-ID).
product_name String Ja Anzeigename des Produkts.
variant_id String Ja Produktvarianten-Bezeichner (z. B. shirt_medium_blue).
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite für weitere Details.
price Gleitkommazahl Ja Varianten-Stückpreis zum Zeitpunkt der Ansicht.
currency String Ja Dreistelliger ISO-4217-Code (z. B. USD oder EUR).
source String Ja Quelle, von der das Event stammt (z. B. web, ios oder android).
type String-Array Nein Erforderlich, um die Braze-Katalog-Trigger-Features für Wieder-verfügbar- und Preissenkungsbenachrichtigungen zu nutzen. Akzeptierte Werte: "price_drop", "back_in_stock"
metadata Object Nein Flexible Schlüssel-Wert-Paare (z. B. category oder brand).

REST API-Beispiel

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

Lösen Sie dieses Event jedes Mal aus, wenn sich der Inhalt des Warenkorbs ändert.

Clientseitige Implementierung

Verwenden Sie die SDK-E-Commerce-Event-APIs, sofern verfügbar. Plattformspezifische Implementierungsbeispiele finden Sie unter E-Commerce-Events über das Braze SDK protokollieren.

Sie können dieses Event auf zwei Arten senden:

  • Vollständiger Warenkorb-Ersatz: Lassen Sie action weg oder setzen Sie action auf replace. Fügen Sie den vollständigen Satz an Positionen in products mit absoluten Mengen (Gesamteinheiten pro Variante im Warenkorb) ein. Sie müssen total_value angeben.
  • Inkrementelle Warenkorb-Aktualisierungen: Setzen Sie action auf add oder remove. Fügen Sie nur die geänderten Positionen ein. Jede quantity ist die Anzahl der hinzuzufügenden oder zu entfernenden Einheiten, nicht die Gesamtmenge im Warenkorb. Bei add erhöht Braze die Positionsmenge oder fügt eine neue Position hinzu. Bei remove verringert Braze die Positionsmenge und entfernt die Position, wenn die Menge 0 erreicht. total_value ist bei add und remove optional.

Um Messaging über dieses Event auszulösen, verwenden Sie den Trigger Warenkorb-Aktualisierungs-Event durchführen in Canvas und Campaigns. Dieser Trigger enthält eine spezielle Behandlung, um zu verhindern, dass der Warenkorb im Shopping-Funnel weiter fortschreitet.

Event-Eigenschaften

Eigenschaft Datentyp Erforderlich Beschreibung
cart_id String Ja Eindeutiger Bezeichner für den Warenkorb. Wird über Warenkorb-, Checkout- und Bestell-Events für das Warenkorb-Mapping der Nutzer:innen geteilt.
action String Nein add (Menge erhöhen oder Position hinzufügen), remove (Menge verringern; Position wird bei 0 entfernt) oder replace (vollständiger Warenkorb-Ersatz, identisch mit dem Weglassen von action).
total_value Gleitkommazahl Bedingt Erforderlich, wenn action weggelassen wird oder replace ist. Optional, wenn action add oder remove ist.
subtotal_value Gleitkommazahl Nein Zwischensumme des Warenkorbs (nach Rabatt, vor Steuern/Versand).
tax Gleitkommazahl Nein Gesamtsteuer auf den Warenkorb.
shipping Gleitkommazahl Nein Gesamtversandkosten für den Warenkorb.
currency String Ja Dreistelliger ISO-4217-Code.
products Array Ja Positionen für diese Aktualisierung. Für vollständigen Ersatz (kein action oder replace) den vollständigen Warenkorb mit absoluten Mengen angeben. Für add oder remove nur geänderte Positionen angeben; siehe Produkteigenschaften.
source String Ja Quelle, von der das Event stammt.
metadata Object Nein Flexible Schlüssel-Wert-Paare für zusätzliche Daten auf Event-Ebene.

Produkteigenschaften (products[])

Eigenschaft Datentyp Erforderlich Beschreibung
product_id String Ja Eindeutiger Produktbezeichner.
product_name String Ja Anzeigename des Produkts.
variant_id String Ja Varianten-Bezeichner.
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Für vollständigen Ersatz (kein action oder replace) die Einheiten im Warenkorb für diese Position. Für add oder remove die Anzahl der hinzuzufügenden oder zu entfernenden Einheiten.
price Gleitkommazahl Ja Varianten-Stückpreis.
metadata Object Nein Flexible Schlüssel-Wert-Paare (z. B. color oder size).

Lösen Sie dieses Event aus, wenn Nutzer:innen den Checkout-Flow starten (z. B. „Zur Kasse“ auswählen oder auf der Checkout-Seite landen).

Clientseitige Implementierung

Verwenden Sie die SDK-E-Commerce-Event-APIs, sofern verfügbar. Plattformspezifische Implementierungsbeispiele finden Sie unter E-Commerce-Events über das Braze SDK protokollieren.

Event-Eigenschaften

Eigenschaft Typ Erforderlich Beschreibung
checkout_id String Ja Eindeutiger Bezeichner für die Checkout-Sitzung.
cart_id String Nein Warenkorb-Bezeichner. Wird über Warenkorb-, Checkout- und Bestell-Events für das Warenkorb-Mapping der Nutzer:innen geteilt.
total_value Gleitkommazahl Ja Gesamtgeldwert des Checkouts.
subtotal_value Gleitkommazahl Nein Zwischensumme (nach Rabatt, vor Steuern/Versand).
tax Gleitkommazahl Nein Gesamtsteuer auf den Checkout.
shipping Gleitkommazahl Nein Gesamtversandkosten.
currency String Ja Dreistelliger ISO-4217-Code.
products Array Ja Artikel im Checkout. Siehe Produkteigenschaften-Untertabelle.
source String Ja Quelle, von der das Event stammt.
metadata Object Nein Flexible Schlüssel-Wert-Paare. Erkannte Untereigenschaft: checkout_url (String)

Produkteigenschaften (products[])

Eigenschaft Datentyp Erforderlich Beschreibung
product_id String Ja Eindeutiger Produktbezeichner.
product_name String Ja Anzeigename des Produkts.
variant_id String Ja Varianten-Bezeichner.
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Gleitkommazahl Ja Varianten-Stückpreis.
metadata Object Nein Flexible Schlüssel-Wert-Paare (z. B. Farbe, Größe).

REST API-Beispiel

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

Lösen Sie dieses Event aus, wenn eine Bestellung erfolgreich abgeschlossen oder die Zahlung bestätigt wird.

Clientseitige Implementierung

Verwenden Sie die SDK-E-Commerce-Event-APIs, sofern verfügbar. Plattformspezifische Implementierungsbeispiele finden Sie unter E-Commerce-Events über das Braze SDK protokollieren.

Event-Eigenschaften

Eigenschaft Datentyp Erforderlich Beschreibung
order_id String Ja Eindeutiger Bezeichner für die Bestellung.
cart_id String Nein Warenkorb-Bezeichner. Wird über Warenkorb-, Checkout- und Bestell-Events für das Warenkorb-Mapping der Nutzer:innen geteilt.
total_value Gleitkommazahl Ja Gesamtgeldwert der Bestellung.
subtotal_value Gleitkommazahl Nein Zwischensumme (nach Rabatt, vor Steuern/Versand).
tax Gleitkommazahl Nein Gesamtsteuer auf die Bestellung.
shipping Gleitkommazahl Nein Gesamtversandkosten.
currency String Ja Dreistelliger ISO-4217-Code.
total_discounts Gleitkommazahl Nein Gesamtbetrag der auf die Bestellung angewendeten Rabatte.
discounts Array Nein Detaillierte Liste der angewendeten Rabatte.
products Array Ja Artikel in der Bestellung. Siehe Produkteigenschaften-Untertabelle.
source String Ja Quelle, von der das Event stammt.
metadata Object Nein Flexible Schlüssel-Wert-Paare. Erkannte Untereigenschaft: order_status_url (String)

Produkteigenschaften (products[])

Eigenschaft Datentyp Erforderlich Beschreibung
product_id String Ja Eindeutiger Produktbezeichner.
product_name String Ja Anzeigename des Produkts.
variant_id String Ja Varianten-Bezeichner.
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Gleitkommazahl Ja Varianten-Stückpreis.
metadata Object Nein Flexible Schlüssel-Wert-Paare (z. B. color oder size).

REST API-Beispiel

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

Lösen Sie dieses Event aus, wenn eine Bestellung storniert wird.

Clientseitige Implementierung

Verwenden Sie logCustomEvent. Plattformspezifische Implementierungsbeispiele finden Sie unter E-Commerce-Events über das Braze SDK protokollieren.

Event-Eigenschaften

Eigenschaft Typ Erforderlich Beschreibung
order_id String Ja Eindeutiger Bezeichner für die Bestellung.
total_value Gleitkommazahl Ja Gesamtgeldwert der stornierten Bestellung. Muss ≥ 0 sein – senden Sie den absoluten Betrag; Braze übernimmt die Verringerung.
subtotal_value Gleitkommazahl Nein Zwischensumme (nach Rabatt, vor Steuern/Versand).
tax Gleitkommazahl Nein Gesamtsteuer auf die Bestellung.
shipping Gleitkommazahl Nein Gesamtversandkosten.
currency String Ja Dreistelliger ISO-4217-Code.
total_discounts Gleitkommazahl Nein Gesamtbetrag der auf die Bestellung angewendeten Rabatte.
discounts Array Nein Detaillierte Liste der angewendeten Rabatte.
cancel_reason String Ja Grund für die Stornierung der Bestellung.
products Array Ja Artikel in der stornierten Bestellung. Siehe Produkteigenschaften-Untertabelle.
source String Ja Quelle, von der das Event stammt.
metadata Object Nein Flexible Schlüssel-Wert-Paare. Erkannte Untereigenschaft: order_status_url (String)

Produkteigenschaften (products[])

Eigenschaft Datentyp Erforderlich Beschreibung
product_id String Ja Eindeutiger Produktbezeichner.
product_name String Ja Anzeigename des Produkts.
variant_id String Ja Varianten-Bezeichner.
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Gleitkommazahl Ja Varianten-Stückpreis.
metadata Object Nein Flexible Schlüssel-Wert-Paare (z. B. color oder size).

REST API-Beispiel

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

Lösen Sie dieses Event aus, wenn eine vollständige oder teilweise Erstattung ausgestellt wird.

Clientseitige Implementierung

Verwenden Sie logCustomEvent. Plattformspezifische Implementierungsbeispiele finden Sie unter E-Commerce-Events über das Braze SDK protokollieren.

Event-Eigenschaften

Eigenschaft Datentyp Erforderlich Beschreibung
order_id String Ja Eindeutiger Bezeichner für die ursprüngliche Bestellung.
total_value Gleitkommazahl Ja Gesamtgeldwert der Erstattung. Muss ≥ 0 sein – senden Sie den absoluten Betrag; Braze übernimmt die Erhöhung von total_refunds.
currency String Ja Dreistelliger ISO-4217-Code.
total_discounts Gleitkommazahl Nein Gesamtbetrag der ursprünglich angewendeten Rabatte.
discounts Array Nein Detaillierte Liste der Rabatte.
products Array Ja Erstattete Artikel. Siehe Produkteigenschaften-Untertabelle.
source String Ja Quelle, von der das Event stammt.
metadata Object Nein Flexible Schlüssel-Wert-Paare. Erkannte Untereigenschaft: order_status_url (String).

Produkteigenschaften (products[])

Eigenschaft Datentyp Erforderlich Beschreibung
product_id String Ja Eindeutiger Produktbezeichner.
product_name String Ja Anzeigename des Produkts.
variant_id String Ja Varianten-Bezeichner.
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Gleitkommazahl Ja Varianten-Stückpreis.
metadata Object Nein Flexible Schlüssel-Wert-Paare (z. B. color oder size).

REST API-Beispiele

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-Commerce-Event-Nachverarbeitung

Wenn Sie ein E-Commerce-Event senden, validiert Braze es gegen das erwartete Schema für diesen Event-Namen.

Die folgende Tabelle fasst zusammen, was Braze automatisch für jedes Event tut, wenn die Validierung erfolgreich ist. Was passiert, wenn die Validierung fehlschlägt, erfahren Sie unter Event-Validierung und Fehlerbehebung.

Event Was Braze automatisch tut
ecommerce.order_placed Erhöht Gesamtumsatz um total_value und Gesamtbestellungen um 1 im Nutzerprofil.
ecommerce.order_cancelled Verringert Gesamtbestellungen um 1.
ecommerce.order_refunded Verringert Gesamtumsatz um total_value und erhöht Gesamterstattungswert.
ecommerce.cart_updated Erstellt oder aktualisiert das Warenkorb-Mapping-Objekt im Nutzerprofil (vollständige Warenkorb-Payloads oder inkrementelle Warenkorb-Aktualisierungen mit optionalem action: add, remove oder replace). Der Warenkorb läuft nach 30 Tagen ohne Aktualisierung ab.
ecommerce.product_viewed Keine Änderungen am Nutzerprofil. Verfügbar für Segmentierung, Triggering und BrazeAITM-Features (wie Artikelempfehlungen).
ecommerce.checkout_started Keine Änderungen am Nutzerprofil. Verfügbar für Segmentierung und Triggering (z. B. abgebrochene Checkout-Flows).

Implementierungsdetails

Datenpunkte und Abrechnung

E-Commerce-Events verbrauchen keine Datenpunkte. Sie können sie ohne Auswirkungen auf Ihre Datenpunkt-Nutzung protokollieren.

Begrenzung der Event-Größe

Event-Eigenschaften, die an /users/track gesendet werden, sind auf 102.400 Bytes (100 KB) pro Event begrenzt. Für getriggerte Campaign- und Canvas-Nachrichten haben die trigger_properties, die an /campaigns/trigger/send und /canvas/trigger/send gesendet werden, ein strengeres Standardlimit von 51.200 Bytes (50 KB).

Als Best Practice senden Sie nur die Produktinformationen, die Sie zum Triggern, Personalisieren oder Zuordnen des Events benötigen. Speichern Sie umfangreichere Produktdetails – wie Beschreibungen, vollständige Variantenlisten, Lagerbestände oder alternative Bilder – in Braze Catalogs. Referenzieren Sie diese Details beim Senden von Nachrichten über product_id oder variant_id. Verwenden Sie das metadata-Objekt gezielt für bestell- oder produktspezifischen Kontext, den das Messaging nutzen wird.

Währungsbehandlung

Braze konvertiert Nicht-USD-Währungswerte automatisch in USD unter Verwendung des Wechselkurses am Tag, an dem das Event gemeldet wird. Dieser konvertierte Wert wird in den Umsatz-Metriken angezeigt.

Source-Feld

Die Source-Eigenschaft ist ein erforderlicher String, der angibt, woher das Event stammt. Zum Beispiel shopify, in-store POS oder custom_api. Dies hilft Ihnen, Integrationsquellen zu unterscheiden, wenn Sie Daten in Currents-Exporten analysieren oder Validierungsprobleme debuggen.

Flexibilität der Metadaten

Sowohl die Metadaten-Objekte auf Event-Ebene als auch auf Produktebene akzeptieren beliebige Schlüssel-Wert-Paare, sodass Sie angepasste Dimensionen hinzufügen können, ohne das Kernschema zu ändern. Gängige Beispiele sind order_status_url, gift_wrapped, loyalty_points_earned oder warehouse_id. Diese Eigenschaften stehen in der Liquid-Personalisierung, in Currents-Exporten und in der Segmentierung über Segmenterweiterungen zur Verfügung.

Event-Validierung und Fehlerbehebung

Wenn Sie ein empfohlenes E-Commerce-Event über /users/track oder ein Braze SDK senden, validiert Braze den Payload während der Verarbeitung des empfohlenen Events anhand des JSON-Schemas des Events. Die Validierung läuft automatisch bei jedem Event, dessen Name exakt mit einem empfohlenen Event übereinstimmt (zum Beispiel ecommerce.order_placed oder ecommerce.cart_updated).

Was wir validieren

Für jedes Event, dessen Name mit einem empfohlenen E-Commerce-Event übereinstimmt, prüft Braze:

Prüfung Beispiel
Event-Name Muss exakt übereinstimmen. Zum Beispiel ist ecommerce.cart_updated korrekt – nicht ecommerce.Cart_Updated, cartupdated oder cart_updated.
Erforderliche Eigenschaften vorhanden order_placed erfordert order_id, total_value, currency, products und source.
Korrekte Datentypen total_value muss eine Zahl sein; currency muss ein String sein; products muss ein Array sein.
Keine zusätzlichen Top-Level-Eigenschaften Angepasste Felder unter „properties“ führen zum Fehler. Verwenden Sie stattdessen das metadata-Objekt.
Wertbeschränkungen Geldbetragsfelder müssen ≥ 0 sein. currency muss ein gültiger ISO-4217-String sein.
Felder pro Produkt Jedes Element in products[] muss product_id, product_name, variant_id, quantity und price enthalten.

Warum wir validieren

E-Commerce-Events steuern Features, die auf konsistente, vorhersagbare Daten angewiesen sind – darunter Umsatz-Tracking, der {% shopping_cart %} Liquid-Tag, der Warenkorb-Abbruch-Trigger und Reporting. Wenn Payloads vom Schema abweichen, erzeugen diese Features stille Ungenauigkeiten (falsche Umsatzsummen, fehlende Warenkörbe, fehlerhafte Trigger). Die Validierung erzwingt den Vertrag im Voraus, damit nachgelagerte Features vorhersagbar funktionieren.

Wenn die Validierung erfolgreich ist

Das Event wird als empfohlenes E-Commerce-Event mit allen zugehörigen Nachverarbeitungsschritten verarbeitet. Unter Empfohlene E-Commerce-Events finden Sie die vollständige Liste der Verhaltensweisen, die durch jeden Event-Typ ausgelöst werden.

Ein erfolgreiches Event überprüfen

Nachdem Sie ein Event gesendet haben, können Sie mit einer der folgenden Methoden bestätigen, dass es akzeptiert und korrekt verarbeitet wurde:

  • Event-Nutzerprotokoll: Öffnen Sie das Profil der Nutzer:in im Dashboard und überprüfen Sie die Aktivität. Empfohlene Events werden mit ihrem vollständigen Eigenschafts-Payload angezeigt, sodass Sie bestätigen können, dass das Event angekommen ist und die Werte mit dem übereinstimmen, was Sie gesendet haben.
  • Bericht über angepasste Events: Gehen Sie zu Analytics > Custom Events Report, um aggregierte Zählungen jedes empfohlenen Events über die Zeit zu sehen. Dies ist nützlich, um zu bestätigen, dass der Produktions-Traffic wie erwartet fließt, wenn Ihre Integration live ist.
  • Testnutzer:innen: Markieren Sie eine Nutzer:in in Ihrem Entwicklungs-Workspace als Testnutzer:in und lösen Sie dann Events aus Ihrer Integration für diese Nutzer:in aus. Testnutzer:innen sind im Dashboard gekennzeichnet, sodass Sie das End-to-End-Verhalten leicht isolieren und überprüfen können.

Wenn die Validierung fehlschlägt

Das Event wird nicht als empfohlenes Event verarbeitet. Im Einzelnen:

  • Das Event wird vollständig verworfen. Ungültige empfohlene E-Commerce-Events landen nicht im Nutzerprofil, erscheinen nicht in Currents und stehen nicht für die Segmentierung zur Verfügung.
  • Nachgelagerte Features für empfohlene Events werden nicht ausgeführt, darunter:
    • Umsatz-Tracking (Umsatz-Reporting, berechnete Nutzerfelder wie total_revenue)
    • Warenkorb-Objekt-Aktualisierungen im Nutzerprofil
    • „Perform Cart Updated Event“- oder „Placed Order“-Trigger in Canvas und Campaigns

Wie Fehler gemeldet werden, hängt vom Aufnahmepfad ab:

  • REST API (/users/track): Jedes ungültige Event wird im Fehler-Array der Antwort gemeldet. Jeder Eintrag gibt an, welches Event fehlgeschlagen ist (Index) und warum (Typ). Das Top-Level-Feld „message“ zeigt weiterhin „success“ an, was nur bedeutet, dass Ihre Anfrage Braze erreicht hat – nicht, dass jedes Event gültig war. Prüfen Sie immer das Fehler-Array in der Antwort.
  • Braze SDKs: SDK-Aufrufe kehren sofort zurück, und die Validierung läuft im Hintergrund, sodass Fehler nicht an Ihre App zurückgesendet werden. Um über Validierungsfehler bei E-Commerce-Events informiert zu werden, achten Sie auf die Zusammenfassungs-E-Mail zu Fehlern (siehe Fehler finden).

Beispiel einer API-Fehlerantwort

Der /users/track-Endpunkt gibt Fehler auf Feldebene zurück, die angeben, welche Eigenschaften fehlgeschlagen sind und warum. Beachten Sie, dass das Top-Level-Feld message möglicherweise "success" zurückgibt, da das Event in die Pipeline aufgenommen wurde; das errors-Array gibt an, welche Felder die Schema-Validierung nicht bestanden haben. Im folgenden Beispiel sehen Sie eine Fehlerantwort.

1
2
3
4

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

Fehler werden außerdem intern klassifiziert und für die Zusammenfassungs-E-Mail zu Fehlern aggregiert:

Fehlertyp Bedeutung Beispiel
missing_property Ein erforderliches Feld fehlt. order_placed ohne order_id gesendet.
extra_property Ein Feld wurde hinzugefügt, das das Schema nicht definiert. Ein angepasstes gift_wrapped-Feld auf der obersten Ebene von properties statt innerhalb von metadata.
unexpected_data_type Ein Feld hat den falschen Typ. total_value: "29.99" (String) statt 29.99 (Zahl).

Fehler finden

Braze sendet Ihren Workspace-Admins eine Zusammenfassung der Validierungsfehler empfohlener Events per E-Mail, damit Sie Integrationsprobleme identifizieren und beheben können, ohne jedes Event manuell überwachen zu müssen.

Die Zusammenfassungs-E-Mail enthält:

  • Gesamtanzahl der Fehler: Fehlerzählungen für den Berichtszeitraum.
  • Fehler nach Event: Eine Aufschlüsselung, wie viele Events für jeden empfohlenen Event-Typ fehlgeschlagen sind (zum Beispiel ecommerce.cart_updated und ecommerce.order_placed). Nutzen Sie dies, um zu identifizieren, welche Events in Ihrer Integration zuerst Aufmerksamkeit benötigen.
  • Fehler nach Quelle: Eine Aufteilung zwischen API und SDK, damit Sie feststellen können, welche Integration die Fehler verursacht.

Wenn Sie diese E-Mails nicht erhalten oder die Empfängerliste überprüfen möchten, wenden Sie sich an Ihr Braze-Konto-Team.

Fehler diagnostizieren und beheben

Wenn Sie eine Zusammenfassungs-E-Mail zu Fehlern erhalten:

  1. Identifizieren Sie das fehlgeschlagene Event und die Quelle. Die E-Mail trennt Fehler nach Event-Name und Integrationsquelle (sdk versus rest_api), sodass Sie feststellen können, welche Integration die Korrektur benötigt. Wenn Sie mehrere Quellen haben, die dasselbe Event senden (zum Beispiel Ihr Storefront-SDK und ein Backend-Webhook, die beide cart_updated senden), behandeln Sie diese unabhängig voneinander.
  2. Vergleichen Sie Ihren Payload mit dem Schema unter Event-Schemas. Die meisten Fehler fallen in eines von drei Mustern:
    • missing_property: Ein erforderliches Feld fehlt. Lösung: Fügen Sie das erforderliche Feld hinzu.
    • extra_property: Ein angepasstes Feld befindet sich auf der obersten Ebene von properties. Lösung: Verschieben Sie das angepasste Feld in metadata (Event-Ebene) oder products[].metadata (pro Produkt).
    • unexpected_data_type: Ein Wert hat den falschen Typ (zum Beispiel total_value als String gesendet). Lösung: Konvertieren Sie den Wert vor dem Senden.
  3. Testen Sie den korrigierten Payload in einem Entwicklungs-Workspace, bevor Sie ihn in die Produktion ausrollen. Senden Sie ein bekanntes Test-Event für eine Testnutzer:in und überprüfen Sie dann das erwartete Verhalten des empfohlenen Events im Profil dieser Nutzer:in (zum Beispiel ob das Warenkorb-Objekt aktualisiert wird, der Umsatz steigt oder der Warenkorb-Abbruch-Trigger ausgelöst wird).
  4. Überwachen Sie die nächste Fehler-E-Mail, um zu bestätigen, dass die Fehleranzahl für dieses Event, diese Quelle und diesen Typ auf null sinkt.

Die vollständigen Eigenschaftsanforderungen pro Event finden Sie unter Event-Schemas.
New Stuff!