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 Customer 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 Anzahl von Plattform-Features zur Verfügung.

Zu diesen Features gehören Canvas-Templates für abgebrochenes Stöbern, Warenkorb-Abbruch, abgebrochenen Checkout und Bestellbestätigungs-Flows; E-Commerce-Reporting; sowie berechnete Nutzerprofilfelder für Gesamtumsatz, Gesamtbestellungen und Gesamterstattungen. Sie können auch Segmente mit 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 Eigenschafts-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-Datenaufnahme (CDI), und Braze validiert jedes Event bei der Aufnahme gegen sein Schema. Wenn die Validierung erfolgreich ist, wendet Braze automatisch eine für den jeweiligen 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, Aktionspfade-Schritten, In-App-Nachrichten-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 punktgetrennt. Verwenden Sie immer das kanonische Format. Wenn ein Event-Name nicht exakt einem der sechs kanonischen Namen entspricht, behandelt Braze ihn als standardmäßiges angepasstes 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 die Phasen der Customer Journey ab. Lösen Sie jedes Event in dem Moment aus, in dem die Nutzerin oder der Nutzer die entsprechende Aktion abschließt.

Diagramm der Customer Journey über 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 ein:e Nutzer:in eine Produktdetailseite ansieht. Dieses Event ist kompatibel mit den Wieder-verfügbar-Benachrichtigungen und Preissenkungsbenachrichtigungen des Braze-Katalogs.

Clientseitige Implementierung

Verwenden Sie 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 (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 Produktbild-URL.
product_url String Nein URL zur Produktseite für weitere Details.
price Gleitkommazahl Ja Einzelpreis der Variante zum Zeitpunkt der Anzeige.
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 Braze-Katalog-Trigger-Features für Wieder-verfügbar- und Preissenkungs-Benachrichtigungen zu nutzen. Akzeptierte 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 einer Nutzerin oder eines Nutzers ändert.

Clientseitige Implementierung

Verwenden Sie 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 für add und remove optional.

Um Messaging von diesem Event aus zu triggern, verwenden Sie den Trigger Warenkorb-Aktualisierung durchführen in Canvas und Campaigns. Dieser Trigger enthält eine spezielle Behandlung, um den Warenkorb am Weitergang durch den Shopping-Funnel zu hindern.

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 die Warenkorb-Zuordnung der Nutzerin oder des Nutzers 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 Zwischensummenwert des Warenkorbs (nach Rabatt, vor Steuer/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 einschließen. Für add oder remove nur geänderte Positionen einschließen; 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 Variantenbezeichner.
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 Einzelpreis der Variante.
metadata Object Nein Flexible Schlüssel-Wert-Paare (zum Beispiel color oder size).

Lösen Sie dieses Event aus, wenn die Nutzerin oder der Nutzer den Checkout-Prozess startet (zum Beispiel „Zur Kasse“ auswählt oder auf der Checkout-Seite landet).

Clientseitige Implementierung

Verwenden Sie 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 die Warenkorb-Zuordnung der Nutzerin oder des Nutzers geteilt.
total_value Gleitkommazahl Ja Gesamtgeldwert des Checkouts.
subtotal_value Gleitkommazahl Nein Zwischensummenwert (nach Rabatt, vor Steuer/Versand).
tax Gleitkommazahl Nein Gesamtsteuer auf den Checkout.
shipping Gleitkommazahl Nein Gesamtversandkosten.
currency String Ja Dreistelliger ISO-4217-Code.
products Array Ja Artikel, die ausgecheckt werden. Siehe Produkteigenschaften-Untertabelle.
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 Variantenbezeichner.
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Gleitkommazahl Ja Einzelpreis 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 eine Zahlung bestätigt wird.

Clientseitige Implementierung

Verwenden Sie 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 die Warenkorb-Zuordnung der Nutzerin oder des Nutzers geteilt.
total_value Gleitkommazahl Ja Gesamtgeldwert der Bestellung.
subtotal_value Gleitkommazahl Nein Zwischensummenwert (nach Rabatt, vor Steuer/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, 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 Variantenbezeichner.
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Gleitkommazahl Ja Einzelpreis 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 Gleitkommazahl Ja Gesamtgeldwert der zu stornierenden Bestellung. Muss ≥ 0 sein – senden Sie den absoluten Betrag; Braze übernimmt die Verringerung.
subtotal_value Gleitkommazahl Nein Zwischensummenwert (nach Rabatt, vor Steuer/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, 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 Variantenbezeichner.
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Gleitkommazahl Ja Einzelpreis 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 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 Artikel, die erstattet werden. Siehe Produkteigenschaften-Untertabelle.
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 Variantenbezeichner.
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Gleitkommazahl Ja Einzelpreis 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 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. Informationen darüber, was bei fehlgeschlagener Validierung passiert, finden 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-Zuordnungsobjekt 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, Trigger und BrazeAITM-Features (wie Artikelempfehlungen).
ecommerce.checkout_started Keine Änderungen am Nutzerprofil. Verfügbar für Segmentierung und Trigger (zum Beispiel Flows für abgebrochenen Checkout).

Implementierungsdetails

Datenpunkte und Abrechnung

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

Event-Größenlimit

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-Katalogen. 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, wobei der Wechselkurs zum Datum der Event-Meldung verwendet wird. Dieser konvertierte Wert wird in den Umsatzmetriken 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.

Metadata-Flexibilität

Sowohl das Event-Level- als auch das Produkt-Level-Metadata-Objekt akzeptiert beliebige Schlüssel-Wert-Paare, sodass Sie angepasste Dimensionen hinzufügen können, ohne das Kernschema zu ändern. Häufige 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 beliebiges Braze SDK senden, validiert Braze die Payload während der Verarbeitung des empfohlenen Events gegen das JSON-Schema des Events. Die Validierung wird automatisch für jedes Event ausgeführt, 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 sein. 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 zu einem 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 betreiben Features, die auf konsistente, vorhersehbare 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 vorhersehbar funktionieren.

Wenn die Validierung erfolgreich ist

Das Event wird als empfohlenes E-Commerce-Event mit der gesamten zugehörigen Nachverarbeitung 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

Nach dem Senden eines Events können Sie bestätigen, dass es akzeptiert und korrekt verarbeitet wurde, indem Sie eine der folgenden Methoden verwenden:

  • Event-Nutzerprotokoll: Öffnen Sie das Profil der Nutzer:in im Dashboard und überprüfen Sie die Aktivität. Empfohlene Events werden mit ihrer 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ähler für jedes empfohlene Event ü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 gegen diese Nutzer:in aus. Testnutzer:innen sind im Dashboard gekennzeichnet, sodass Sie das End-to-End-Verhalten leicht isolieren und untersuchen können.

Wenn die Validierung fehlschlägt

Das Event wird nicht als empfohlenes Event verarbeitet. Konkret:

  • 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 Funktionen für empfohlene Events werden nicht ausgeführt, einschließlich:
    • Umsatz-Tracking (Umsatz-Reporting, berechnete Nutzerfelder wie total_revenue)
    • Warenkorb-Objekt-Updates im Nutzerprofil
    • Update Cart- oder Place 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 message-Feld auf oberster Ebene 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 geben 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 Fehlerübersichts-E-Mail (siehe Fehler finden).

Beispiel für eine API-Fehlerantwort

Der /users/track-Endpunkt gibt Fehler auf Feldebene zurück, die angeben, welche Eigenschaften fehlgeschlagen sind und warum. Beachten Sie, dass die message auf oberster Ebene "success" zurückgeben kann, weil das Event in die Pipeline aufgenommen wurde; das errors-Array gibt an, welche Felder die Schema-Validierung nicht bestanden haben. Sehen Sie das folgende Beispiel für eine Fehlerantwort.




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

Fehler werden auch intern klassifiziert und für die Fehlerübersichts-E-Mail 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 oberster 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 Workspace-Admins eine Zusammenfassung der Validierungsfehler für empfohlene 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: Fehleranzahlen 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 Aufschlüsselung 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-Account-Team.

Fehler diagnostizieren und beheben

Wenn Sie eine Fehlerübersichts-E-Mail 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 Ihre Payload mit dem Schema unter Event-Schemas. Die meisten Fehler fallen in eines von drei Mustern:
    • missing_property: Ein erforderliches Feld fehlt. Um dies zu lösen, fügen Sie das erforderliche Feld hinzu.
    • extra_property: Ein angepasstes Feld befindet sich auf der obersten Ebene von properties. Um dies zu lösen, 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). Um dies zu lösen, konvertieren Sie den Wert vor dem Senden.
  3. Testen Sie die korrigierte Payload in einem Entwicklungs-Workspace, bevor Sie sie 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.

Dokumentation für die Braze-Kundenengagement-Plattform.

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