Zum Inhalt springen

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 Kauf-Journey 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 Zahl von Plattform-Features zur Verfügung.

Zu diesen Features gehören Canvas-Templates für Flows zu abgebrochenem Browsen, Warenkorb-Abbruch, abgebrochenem Checkout und Bestellbestätigung, E-Commerce-Reporting sowie berechnete Nutzerprofilfelder für Total Revenue, Total Orders und Total Refunds. Sie können außerdem Segmente mit verschachtelter Filterung nach Produkteigenschaften über Segmenterweiterungen erstellen, Nachrichten zum Warenkorb-Abbruch mit dem Liquid-Tag {% shopping_cart %} personalisieren und BrazeAITM-Funktionen wie Predictive Events, Predictive Churn und Artikelempfehlungen sowie weitere Funktionen mit Daten versorgen.

Da diese Events einem definierten Schema folgen, kann jedes unterstützte Feature die strukturierten Daten lesen – ganz ohne angepasste Abbildung von Eigenschaften oder Feature-spezifische Konfiguration auf Ihrer Seite.

So funktionieren E-Commerce-Events

E-Commerce-Events sind angepasste Events mit vordefinierten Namen und Eigenschaftsschemas. Sie senden sie über das Braze SDK, den REST-API-Endpunkt /users/track oder Cloud Data Ingestion (CDI), und Braze validiert jedes Event bei der Aufnahme anhand seines Schemas. Ist die Validierung erfolgreich, wendet Braze automatisch die für den jeweiligen Event-Typ spezifische Nachverarbeitung an, etwa die Berechnung von Umsatzfeldern und die Verwaltung des Warenkorbstatus in Nutzerprofilen.

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

  • Trigger-Aktionen vom Typ „Places order“ in Campaigns, Canvases, Aktionspfad-Schritten, Triggern für In-App-Nachrichten und beim Entfernen von Content-Cards
  • Berechnete E-Commerce-Nutzerprofilfelder (Total Revenue, Total Orders, Total Refunds)
  • Verwaltung des Warenkorbstatus für Flows zum Warenkorb-Abbruch
  • Umfangreichere Daten für BrazeAITM-Features wie Predictive Events, Predictive Churn und Artikelempfehlungen

Sie können E-Commerce-Events außerdem überall dort über ihren Namen referenzieren, wo die Plattform angepasste Events unterstützt. So können Sie beispielsweise eine aktionsbasierte Campaign mit ecommerce.product_viewed-Events triggern, ein Segment mit einem Filter auf ecommerce.checkout_started-Events erstellen oder ecommerce.order_placed-Events über Currents exportieren.

Benennung von Events

Event-Namen sind exakt, unterscheiden zwischen Groß- und Kleinschreibung und sind durch Punkte getrennt. Verwenden Sie immer das kanonische Format. Stimmt ein Event-Name nicht genau mit einem der sechs kanonischen Namen überein, behandelt Braze ihn als standardmäßiges angepasstes Event, und es findet keine E-Commerce-Nachverarbeitung statt.

Events können nicht angepasst oder umbenannt werden.

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

Event-Schemas

Die sechs empfohlenen E-Commerce-Events entsprechen den Phasen der Kauf-Journey. Lösen Sie jedes Event genau in dem Moment aus, in dem die Nutzer:innen die entsprechende Aktion abschließen.

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

Für das clientseitige Logging verwenden ecommerce.product_viewed, ecommerce.cart_updated, ecommerce.checkout_started und ecommerce.order_placed – sofern verfügbar – die E-Commerce-Event-APIs des SDK, während ecommerce.order_cancelled und ecommerce.order_refunded logCustomEvent verwenden.

Rückerstattungs- und Stornierungs-Events werden in der Regel von Ihrem Server über die Braze REST API gesendet, da sie meist vom Abschluss serverseitiger Logik abhängen, etwa Ihres Rückerstattungsprozesses. Plattformspezifische Implementierungsbeispiele finden Sie unter E-Commerce-Events über das Braze SDK protokollieren.

Lösen Sie dieses Event aus, wenn Nutzer:innen eine Produktdetailseite aufrufen. Dieses Event ist mit den Katalog-Features von Braze für Benachrichtigungen bei Wiederverfügbarkeit und Benachrichtigungen bei Preissenkungen kompatibel.

Clientseitige Implementierung

Verwenden Sie, sofern verfügbar, die E-Commerce-Event-APIs des SDK. 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 (zum Beispiel SKU oder Artikel-ID).
product_name String Ja Anzeigename des Produkts.
variant_id String Ja Bezeichner der Produktvariante (zum Beispiel shirt_medium_blue).
image_url String Nein URL des Produktbilds.
product_url String Nein URL zur Produktseite mit weiteren Details.
price Float Ja Stückpreis der Variante zum Zeitpunkt des Aufrufs.
currency String Ja Dreistelliger ISO-4217-Code (zum Beispiel USD oder EUR).
source String Ja Quelle, aus der das Event stammt (zum Beispiel web, ios oder android).
type String-Array Nein Erforderlich, um die Katalog-Trigger-Features von Braze für Benachrichtigungen bei Wiederverfügbarkeit und Preissenkungen zu nutzen. Zulässige Werte: "price_drop", "back_in_stock"
metadata Object Nein Flexible Schlüssel-Wert-Paare (zum Beispiel category oder brand).

REST-API-Beispiel




{
  "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 von Nutzer:innen ändert.

Clientseitige Implementierung

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

Sie können dieses Event auf zwei Arten senden:

  • Vollständiges Ersetzen des Warenkorbs: Lassen Sie action weg oder setzen Sie action auf replace. Geben Sie in products alle Positionen mit absoluten Mengen an (Gesamtzahl der Einheiten pro Variante im Warenkorb). Sie müssen total_value angeben.
  • Inkrementelle Warenkorb-Updates: Setzen Sie action auf add oder remove. Geben Sie nur die geänderten Positionen an. Jede quantity ist die Anzahl der hinzuzufügenden oder zu entfernenden Einheiten, nicht die Gesamtmenge im Warenkorb. Bei add erhöht Braze die Menge der Position oder fügt eine neue Position hinzu. Bei remove verringert Braze die Menge der Position und entfernt die Position, sobald die Menge 0 erreicht. total_value ist für add und remove optional.

Um Messaging über dieses Event zu triggern, verwenden Sie den Trigger Perform Cart Updated Event in Canvas und Campaigns. Dieser Trigger enthält eine spezielle Behandlung, die verhindert, dass der Warenkorb weiter durch den Shopping-Funnel fortschreitet.

Event-Eigenschaften

Eigenschaft Datentyp Erforderlich Beschreibung
cart_id String Ja Eindeutiger Bezeichner für den Warenkorb. Wird für die Warenkorb-Abbildung der Nutzer:innen von Warenkorb-, Checkout- und Bestell-Events gemeinsam genutzt.
action String Nein add (Menge erhöhen oder Position hinzufügen), remove (Menge verringern; Position wird bei 0 entfernt) oder replace (vollständiges Ersetzen des Warenkorbs, entspricht dem Weglassen von action).
total_value Float Bedingt Erforderlich, wenn action weggelassen wird oder replace ist. Optional, wenn action add oder remove ist.
subtotal_value Float Nein Zwischensumme des Warenkorbs (nach Rabatt, vor Steuern/Versand).
tax Float Nein Gesamtsteuer für den Warenkorb.
shipping Float Nein Gesamtversandkosten für den Warenkorb.
currency String Ja Dreistelliger ISO-4217-Code.
products Array Ja Positionen für dieses Update. Geben Sie beim vollständigen Ersetzen (kein action oder replace) den gesamten Warenkorb mit absoluten Mengen an. Geben Sie bei add oder remove nur die geänderten Positionen an; siehe Produkteigenschaften.
source String Ja Quelle, aus 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 Bezeichner der Variante.
image_url String Nein URL des Produktbilds.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Beim vollständigen Ersetzen (kein action oder replace) die Anzahl der Einheiten dieser Position im Warenkorb. Bei add oder remove die Anzahl der hinzuzufügenden oder zu entfernenden Einheiten.
price Float Ja Stückpreis der Variante.
metadata Object Nein Flexible Schlüssel-Wert-Paare (zum Beispiel color oder size).

Lösen Sie dieses Event aus, wenn Nutzer:innen den Checkout-Prozess starten (zum Beispiel „Checkout“ auswählen oder auf der Checkout-Seite landen).

Clientseitige Implementierung

Verwenden Sie, sofern verfügbar, die E-Commerce-Event-APIs des SDK. 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 Bezeichner des Warenkorbs. Wird für die Warenkorb-Abbildung der Nutzer:innen von Warenkorb-, Checkout- und Bestell-Events gemeinsam genutzt.
total_value Float Ja Gesamtwert des Checkouts.
subtotal_value Float Nein Zwischensumme (nach Rabatt, vor Steuern/Versand).
tax Float Nein Gesamtsteuer für den Checkout.
shipping Float Nein Gesamtversandkosten.
currency String Ja Dreistelliger ISO-4217-Code.
products Array Ja Artikel im Checkout. Siehe Untertabelle zu den Produkteigenschaften.
source String Ja Quelle, aus 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 Bezeichner der Variante.
image_url String Nein URL des Produktbilds.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Float Ja Stückpreis der Variante.
metadata Object Nein Flexible Schlüssel-Wert-Paare (z. B. Farbe, Größe).

REST-API-Beispiel




{
  "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 wurde.

Clientseitige Implementierung

Verwenden Sie, sofern verfügbar, die E-Commerce-Event-APIs des SDK. 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 Bezeichner des Warenkorbs. Wird für die Warenkorb-Abbildung der Nutzer:innen von Warenkorb-, Checkout- und Bestell-Events gemeinsam genutzt.
total_value Float Ja Gesamtwert der Bestellung.
subtotal_value Float Nein Zwischensumme (nach Rabatt, vor Steuern/Versand).
tax Float Nein Gesamtsteuer für die Bestellung.
shipping Float Nein Gesamtversandkosten.
currency String Ja Dreistelliger ISO-4217-Code.
total_discounts Float Nein Gesamtbetrag der auf die Bestellung angewendeten Rabatte.
discounts Array Nein Detaillierte Liste der angewendeten Rabatte.
products Array Ja Artikel in der Bestellung. Siehe Untertabelle zu den Produkteigenschaften.
source String Ja Quelle, aus 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 Bezeichner der Variante.
image_url String Nein URL des Produktbilds.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Float Ja Stückpreis der Variante.
metadata Object Nein Flexible Schlüssel-Wert-Paare (zum Beispiel color oder size).

REST-API-Beispiel




{
  "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 Float Ja Gesamtwert der stornierten Bestellung. Muss ≥ 0 sein – senden Sie den absoluten Betrag; Braze übernimmt die Verringerung.
subtotal_value Float Nein Zwischensumme (nach Rabatt, vor Steuern/Versand).
tax Float Nein Gesamtsteuer für die Bestellung.
shipping Float Nein Gesamtversandkosten.
currency String Ja Dreistelliger ISO-4217-Code.
total_discounts Float 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 Untertabelle zu den Produkteigenschaften.
source String Ja Quelle, aus 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 Bezeichner der Variante.
image_url String Nein URL des Produktbilds.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Float Ja Stückpreis der Variante.
metadata Object Nein Flexible Schlüssel-Wert-Paare (zum Beispiel color oder size).

REST-API-Beispiel




{
  "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 Rückerstattung erfolgt.

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 Float Ja Gesamtwert der Rückerstattung. 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 Float Nein Gesamtbetrag der ursprünglich angewendeten Rabatte.
discounts Array Nein Detaillierte Liste der Rabatte.
products Array Ja Erstattete Artikel. Siehe Untertabelle zu den Produkteigenschaften.
source String Ja Quelle, aus 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 Bezeichner der Variante.
image_url String Nein URL des Produktbilds.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Float Ja Stückpreis der Variante.
metadata Object Nein Flexible Schlüssel-Wert-Paare (zum Beispiel color oder size).

REST-API-Beispiele




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

Nachverarbeitung von E-Commerce-Events

Wenn Sie ein E-Commerce-Event senden, validiert Braze es anhand des erwarteten Schemas für diesen Event-Namen.

Die folgende Tabelle fasst zusammen, was Braze bei erfolgreicher Validierung für jedes Event automatisch ausführt. Was bei einer fehlgeschlagenen Validierung passiert, erfahren Sie unter Event-Validierung und Fehlerbehebung.

Event Was Braze automatisch ausführt
ecommerce.order_placed Erhöht im Nutzerprofil Total Revenue um total_value und Total Orders um 1.
ecommerce.order_cancelled Verringert Total Orders um 1.
ecommerce.order_refunded Verringert Total Revenue um total_value und erhöht Total Refund Value.
ecommerce.cart_updated Erstellt oder aktualisiert das Abbildungsobjekt für Warenkörbe im Nutzerprofil (vollständige Warenkorb-Payloads oder inkrementelle Warenkorb-Updates mit optionalem action: add, remove oder replace). Der Warenkorb läuft nach 30 Tagen ohne Update 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 (zum Beispiel für Flows zu abgebrochenen Checkouts).

Details zur Implementierung

Datenpunkte und Abrechnung

E-Commerce-Events verbrauchen keine Datenpunkte. Sie können sie protokollieren, ohne dass sich dies auf Ihre Datenpunkt-Nutzung auswirkt.

Größenlimit für Events

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

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

Umgang mit Währungen

Braze rechnet Währungswerte, die nicht in USD angegeben sind, automatisch zum Wechselkurs des Tages, an dem das Event gemeldet wird, in USD um. Dieser umgerechnete Wert erscheint in den Umsatzmetriken.

Feld „Source“

Die Eigenschaft „source“ ist ein erforderlicher String, der angibt, woher das Event stammt, zum Beispiel shopify, in-store POS oder custom_api. So können Sie Integrationsquellen unterscheiden, wenn Sie Daten in Currents-Exporten analysieren oder Validierungsprobleme beheben.

Flexibilität bei Metadaten

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

Event-Validierung und Fehlerbehebung

Wenn Sie ein empfohlenes E-Commerce-Event über /users/track oder ein beliebiges 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 für jedes 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 Folgendes:

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 Eigenschaften auf oberster Ebene Angepasste Felder unter den Eigenschaften führen zu einem Fehler. Verwenden Sie stattdessen das Objekt metadata.
Wertbeschränkungen Geldbetragsfelder müssen ≥ 0 sein. currency muss ein gültiger ISO-4217-String sein.
Felder pro Produkt Jeder Artikel in products[] muss product_id, product_name, variant_id, quantity und price enthalten.

Warum wir validieren

E-Commerce-Events bilden die Grundlage für Features, die auf konsistente, vorhersehbare Daten angewiesen sind – darunter Umsatz-Tracking, der Liquid-Tag {% shopping_cart %}, der Trigger für Warenkorb-Abbrüche und das Reporting. Wenn Payloads vom Schema abweichen, liefern diese Features unbemerkt ungenaue Ergebnisse (falsche Umsatzsummen, fehlende Warenkörbe, defekte Trigger). Die Validierung setzt die Vorgaben von Anfang an durch, damit sich nachgelagerte Features vorhersehbar verhalten.

Wenn die Validierung erfolgreich ist

Das Event wird als empfohlenes E-Commerce-Event mit allen zugehörigen Nachverarbeitungsschritten verarbeitet. Eine vollständige Liste der Verhaltensweisen, die durch die einzelnen Event-Typen getriggert werden, finden Sie unter Empfohlene E-Commerce-Events.

Erfolgreiches Event überprüfen

Nachdem Sie ein Event gesendet haben, können Sie auf eine der folgenden Arten 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äten. 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 Ihren gesendeten Daten übereinstimmen.
  • Bericht über angepasste Events: Gehen Sie zu Analytics > Bericht über angepasste Events, um die aggregierten Zahlen der einzelnen empfohlenen Events im Zeitverlauf zu sehen. Das ist hilfreich, um nach dem Livegang Ihrer Integration zu bestätigen, dass der Produktions-Traffic wie erwartet fließt.
  • Testnutzer:innen: Markieren Sie eine Nutzer:in in Ihrem Entwicklungs-Workspace als Testnutzer:in und triggern Sie dann Events aus Ihrer Integration für diese Nutzer:in. Testnutzer:innen sind im Dashboard gekennzeichnet, sodass Sie das End-to-End-Verhalten einfach isolieren und untersuchen 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)
    • Aktualisierungen des Warenkorb-Objekts im Nutzerprofil
    • Trigger für Warenkorb aktualisieren oder Bestellung aufgeben in Canvas und Campaigns

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

  • REST API (/users/track): Jedes ungültige Event wird im Array errors der Antwort gemeldet. Jeder Eintrag gibt an, welches Event fehlgeschlagen ist (index) und warum (type). Das Feld message auf oberster Ebene zeigt trotzdem „success“ an. Das bedeutet lediglich, dass Ihre Anfrage Braze erreicht hat, nicht dass jedes Event gültig war. Prüfen Sie die Antwort daher immer auf ein Array errors.
  • Braze SDKs: SDK-Aufrufe kehren sofort zurück und die Validierung läuft im Hintergrund, daher werden Fehler nicht an Ihre App zurückgesendet. Um über fehlgeschlagene Validierungen von E-Commerce-Events informiert zu werden, achten Sie auf die E-Mail mit der Fehlerzusammenfassung (siehe Fehler finden).

Beispiel für eine API-Fehlerantwort

Der Endpunkt /users/track gibt Fehler auf Feldebene zurück, die angeben, welche Eigenschaften fehlgeschlagen sind und warum. Beachten Sie, dass message auf oberster Ebene möglicherweise "success" zurückgibt, weil das Event in die Pipeline aufgenommen wurde. Das Array errors zeigt Ihnen, welche Felder die Schema-Validierung nicht bestanden haben. Ein Beispiel finden Sie in der folgenden Fehlerantwort.




{
 "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 E-Mail mit der Fehlerzusammenfassung aggregiert:

Fehlertyp Bedeutung Beispiel
missing_property Ein erforderliches Feld fehlt. order_placed wurde ohne order_id gesendet.
extra_property Es wurde ein Feld hinzugefügt, das im Schema nicht definiert ist. Ein angepasstes Feld gift_wrapped 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 den Admins Ihres Workspace per E-Mail eine Zusammenfassung der fehlgeschlagenen Validierungen empfohlener Events, damit Sie Integrationsprobleme erkennen und beheben können, ohne jedes Event manuell zu überwachen.

Die Zusammenfassungs-E-Mail enthält:

  • Gesamtzahl der Fehler: Fehleranzahl für den Berichtszeitraum.
  • Fehler nach Event: Eine Aufschlüsselung, wie viele Events für jeden Typ empfohlener Events fehlgeschlagen sind (zum Beispiel ecommerce.cart_updated und ecommerce.order_placed). So erkennen Sie, welche Events in Ihrer Integration zuerst Aufmerksamkeit benötigen.
  • Fehler nach Quelle: Eine Aufteilung zwischen API und SDK, damit Sie genau 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-Account-Team.

Fehler diagnostizieren und beheben

Wenn Sie eine E-Mail mit einer Fehlerzusammenfassung erhalten:

  1. Ermitteln Sie das fehlerhafte Event und die Quelle. Die E-Mail trennt Fehler nach Event-Name und Integrationsquelle (sdk oder rest_api), sodass Sie genau feststellen können, welche Integration korrigiert werden muss. Wenn mehrere Quellen 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 lassen sich einem von drei Mustern zuordnen:
    • missing_property: Ein erforderliches Feld fehlt. Fügen Sie das erforderliche Feld hinzu, um das Problem zu beheben.
    • extra_property: Ein angepasstes Feld befindet sich auf der obersten Ebene von properties. Verschieben Sie das angepasste Feld in metadata (auf Event-Ebene) oder products[].metadata (pro Produkt), um das Problem zu beheben.
    • unexpected_data_type: Ein Wert hat den falschen Typ (zum Beispiel wird total_value als String gesendet). Konvertieren Sie den Wert vor dem Senden, um das Problem zu beheben.
  3. Testen Sie den korrigierten Payload in einem Entwicklungs-Workspace, bevor Sie ihn in der Produktion einführen. 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, dass das Warenkorb-Objekt aktualisiert wird, der Umsatz steigt oder der Trigger für Warenkorb-Abbrüche ausgelöst wird).
  4. Beobachten 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 Anforderungen an Eigenschaften für jedes Event finden Sie unter Event-Schemas.

Dokumentation für die Braze-Kundenengagement-Plattform.

Ressourcen
Rechtliches
Unternehmen
© 2026 Braze, Inc. Alle Rechte vorbehalten.
Braze-Status wird geprüft
New Stuff!