Passer au contenu

Enregistrer des événements eCommerce

Découvrez comment enregistrer des événements eCommerce recommandés via les SDK Android, Swift et Web de Braze à l’aide de classes d’événements typées et de logEcommerceEvent. Pour les schémas de propriétés d’événement, les fonctionnalités propres à chaque plateforme et la validation à l’ingestion, consultez Événements recommandés et Validation des événements et résolution des problèmes.

Schémas d’événements

Les six événements eCommerce recommandés partagent un schéma au niveau de la commande sur toutes les plateformes. Utilisez les tableaux de propriétés suivants pour créer le payload de chaque événement. Pour le schéma de référence avec le comportement de validation complet et des exemples REST API, consultez Événements recommandés. Pour les fonctionnalités de la plateforme comme la segmentation, les modèles de Canvas et les rapports, consultez Comment utiliser les événements eCommerce.

Déclenchez cet événement lorsqu’un utilisateur consulte la page détaillée d’un produit.

Propriétés de l’événement

Nom de la propriété Type de données Obligatoire Description
product_id Chaîne de caractères Oui Identifiant unique du produit (par exemple, unité de gestion des stocks ou ID d’article).
product_name Chaîne de caractères Oui Nom d’affichage du produit.
variant_id Chaîne de caractères Oui Identifiant de la variante du produit (par exemple, shirt_medium_blue).
image_url Chaîne de caractères Non URL de l’image du produit.
product_url Chaîne de caractères Non URL de la page du produit pour plus de détails.
price Float Oui Prix unitaire de la variante au moment de la consultation.
currency Chaîne de caractères Oui Code ISO 4217 à trois lettres (par exemple, USD ou EUR).
source Chaîne de caractères Oui Source d’origine de l’événement (par exemple, web, ios ou android).
type Tableau de chaînes de caractères Non Obligatoire pour utiliser les fonctionnalités de déclencheur de catalogue de Braze pour les alertes de retour en stock et de baisse de prix. Valeurs acceptées : "price_drop", "back_in_stock".
catalog_name Chaîne de caractères Non Le catalogue auquel appartient un abonnement de retour en stock ou de baisse de prix créé à partir de cet événement. S’il est omis, le catalogue de secours de l’espace de travail est utilisé. Doit être une propriété de premier niveau ; un catalog_name imbriqué dans metadata est ignoré.
metadata Objet Non Paires clé-valeur flexibles (par exemple, category ou brand).

Déclenchez cet événement chaque fois que le contenu du panier d’un utilisateur change. Utilisez le remplacement complet du panier (omettez action ou définissez-la sur replace) ou des mises à jour incrémentielles (add ou remove).

Propriétés de l’événement

Propriété Type de données Obligatoire Description
cart_id Chaîne de caractères Oui Identifiant unique du panier. Partagé entre les événements de panier, de paiement et de commande pour le mappage du panier de l’utilisateur. Pour les règles de réutilisation après le paiement ou la passation de commande, consultez ID du panier après le paiement ou la commande.
action Chaîne de caractères Non add (augmente la quantité ou ajoute une ligne), remove (diminue la quantité ; la ligne est supprimée à 0) ou replace (remplacement complet du panier, équivalent à l’omission de action).
total_value Float Conditionnel Obligatoire lorsque action est omise ou vaut replace, et enregistrée comme total du panier. Facultative lorsque action vaut add ou remove.

Lorsque action vaut add ou remove, la valeur n’est pas enregistrée sur le panier et n’efface pas un total enregistré précédemment. Lorsqu’un panier est mis à jour uniquement avec add ou remove, aucune total_value n’est enregistrée et l’étiquette {% shopping_cart %} additionne le price de chaque produit multiplié par sa quantity.
subtotal_value Float Non Sous-total du panier (après remise, avant taxes et frais de livraison). Non enregistré sur le panier et non disponible via l’étiquette Liquid {% shopping_cart %}.
tax Float Non Montant total des taxes appliquées au panier. Non enregistré sur le panier et non disponible via l’étiquette Liquid {% shopping_cart %}.
shipping Float Non Coût total de livraison du panier. Non enregistré sur le panier et non disponible via l’étiquette Liquid {% shopping_cart %}.
currency Chaîne de caractères Oui Code ISO 4217 à trois lettres.
products Tableau Oui Lignes d’articles de cette mise à jour. Consultez le tableau des propriétés de produit.
source Chaîne de caractères Oui Source d’origine de l’événement.
metadata Objet Non Paires clé-valeur flexibles pour des données supplémentaires au niveau de l’événement.

Propriétés de produit (products[])

Propriété Type de données Obligatoire Description
product_id Chaîne de caractères Oui Identifiant unique du produit.
product_name Chaîne de caractères Oui Nom d’affichage du produit.
variant_id Chaîne de caractères Oui Identifiant de la variante.
image_url Chaîne de caractères Non URL de l’image du produit.
product_url Chaîne de caractères Non URL de la page du produit.
quantity Entier Oui Pour un remplacement complet, nombre d’unités de cette ligne dans le panier. Pour add ou remove, nombre d’unités à ajouter ou à retirer.
price Float Oui Prix unitaire de la variante.
metadata Objet Non Paires clé-valeur flexibles (par exemple, color ou size).

Déclenchez cet événement lorsque l’utilisateur lance le processus de paiement.

Propriétés de l’événement

Propriété Type de données Obligatoire Description
checkout_id Chaîne de caractères Oui Identifiant unique de la session de paiement.
cart_id Chaîne de caractères Non Identifiant du panier. Partagé entre les événements de panier, de paiement et de commande pour le mappage du panier de l’utilisateur.
total_value Float Oui Valeur monétaire totale du paiement.
subtotal_value Float Non Sous-total (après remise, avant taxes et frais de livraison).
tax Float Non Montant total des taxes appliquées au paiement.
shipping Float Non Coût total de livraison.
currency Chaîne de caractères Oui Code ISO 4217 à trois lettres.
products Tableau Oui Articles en cours de paiement. Consultez le tableau des propriétés de produit.
source Chaîne de caractères Oui Source d’origine de l’événement.
metadata Objet Non Paires clé-valeur flexibles. Sous-propriété reconnue : checkout_url (chaîne de caractères).

Propriétés de produit (products[])

Propriété Type de données Obligatoire Description
product_id Chaîne de caractères Oui Identifiant unique du produit.
product_name Chaîne de caractères Oui Nom d’affichage du produit.
variant_id Chaîne de caractères Oui Identifiant de la variante.
image_url Chaîne de caractères Non URL de l’image du produit.
product_url Chaîne de caractères Non URL de la page du produit.
quantity Entier Oui Nombre d’unités dans le panier.
price Float Oui Prix unitaire de la variante.
metadata Objet Non Paires clé-valeur flexibles (par exemple, color ou size).

Déclenchez cet événement lorsqu’une commande est finalisée avec succès ou que le paiement est confirmé.

Propriétés de l’événement

Propriété Type de données Obligatoire Description
order_id Chaîne de caractères Oui Identifiant unique de la commande.
cart_id Chaîne de caractères Non Identifiant du panier. Partagé entre les événements de panier, de paiement et de commande pour le mappage du panier de l’utilisateur.
total_value Float Oui Valeur monétaire totale de la commande.
subtotal_value Float Non Sous-total (après remise, avant taxes et frais de livraison).
tax Float Non Montant total des taxes appliquées à la commande.
shipping Float Non Coût total de livraison.
currency Chaîne de caractères Oui Code ISO 4217 à trois lettres.
total_discounts Float Non Montant total des remises appliquées à la commande.
discounts Tableau Non Liste détaillée des remises appliquées. Chaque objet de remise prend en charge code (chaîne de caractères), amount (float) et type (chaîne de caractères).
products Tableau Oui Articles de la commande. Consultez le tableau des propriétés de produit.
source Chaîne de caractères Oui Source d’origine de l’événement.
metadata Objet Non Paires clé-valeur flexibles. Sous-propriété reconnue : order_status_url (chaîne de caractères).

Propriétés de produit (products[])

Propriété Type de données Obligatoire Description
product_id Chaîne de caractères Oui Identifiant unique du produit.
product_name Chaîne de caractères Oui Nom d’affichage du produit.
variant_id Chaîne de caractères Oui Identifiant de la variante.
image_url Chaîne de caractères Non URL de l’image du produit.
product_url Chaîne de caractères Non URL de la page du produit.
quantity Entier Oui Nombre d’unités dans la commande.
price Float Oui Prix unitaire de la variante.
metadata Objet Non Paires clé-valeur flexibles (par exemple, color ou size).

Déclenchez cet événement lorsqu’une commande est annulée.

Propriétés de l’événement

Propriété Type de données Obligatoire Description
order_id Chaîne de caractères Oui Identifiant unique de la commande.
total_value Float Oui Valeur monétaire totale de la commande annulée. Envoyez le montant absolu (supérieur ou égal à 0) ; Braze gère la déduction.
subtotal_value Float Non Sous-total (après remise, avant taxes et frais de livraison).
tax Float Non Montant total des taxes appliquées à la commande.
shipping Float Non Coût total de livraison.
currency Chaîne de caractères Oui Code ISO 4217 à trois lettres.
total_discounts Float Non Montant total des remises appliquées à la commande.
discounts Tableau Non Liste détaillée des remises appliquées.
cancel_reason Chaîne de caractères Oui Motif de l’annulation de la commande.
products Tableau Oui Articles de la commande annulée. Consultez le tableau des propriétés de produit.
source Chaîne de caractères Oui Source d’origine de l’événement.
metadata Objet Non Paires clé-valeur flexibles. Sous-propriété reconnue : order_status_url (chaîne de caractères).

Propriétés de produit (products[])

Propriété Type de données Obligatoire Description
product_id Chaîne de caractères Oui Identifiant unique du produit.
product_name Chaîne de caractères Oui Nom d’affichage du produit.
variant_id Chaîne de caractères Oui Identifiant de la variante.
image_url Chaîne de caractères Non URL de l’image du produit.
product_url Chaîne de caractères Non URL de la page du produit.
quantity Entier Oui Nombre d’unités dans la commande.
price Float Oui Prix unitaire de la variante.
metadata Objet Non Paires clé-valeur flexibles (par exemple, color ou size).

Déclenchez cet événement lorsqu’un remboursement total ou partiel est émis. Pour les remboursements partiels, définissez total_value sur le seul montant remboursé, et non sur le total initial de la commande.

Propriétés de l’événement

Propriété Type de données Obligatoire Description
order_id Chaîne de caractères Oui Identifiant unique de la commande d’origine.
total_value Float Oui Valeur monétaire totale du remboursement. Envoyez le montant absolu (supérieur ou égal à 0) ; Braze gère l’ajustement du chiffre d’affaires.
currency Chaîne de caractères Oui Code ISO 4217 à trois lettres.
total_discounts Float Non Montant total des remises appliquées initialement.
discounts Tableau Non Liste détaillée des remises.
products Tableau Oui Articles remboursés. Consultez le tableau des propriétés de produit.
source Chaîne de caractères Oui Source d’origine de l’événement.
metadata Objet Non Paires clé-valeur flexibles. Sous-propriété reconnue : order_status_url (chaîne de caractères).

Propriétés de produit (products[])

Propriété Type de données Obligatoire Description
product_id Chaîne de caractères Oui Identifiant unique du produit.
product_name Chaîne de caractères Oui Nom d’affichage du produit.
variant_id Chaîne de caractères Oui Identifiant de la variante.
image_url Chaîne de caractères Non URL de l’image du produit.
product_url Chaîne de caractères Non URL de la page du produit.
quantity Entier Oui Nombre d’unités remboursées.
price Float Oui Prix unitaire de la variante.
metadata Objet Non Paires clé-valeur flexibles (par exemple, color ou size).

Android

Le SDK Android 42.3.0+ fournit des classes d’événements eCommerce typées. Elles sont validées côté client dès leur construction et sérialisées automatiquement en snake_case lorsque vous appelez Braze.logEcommerceEvent.

Classe Android Nom de l’événement Notes
ProductViewedEvent ecommerce.product_viewed Aplatit les champs du produit au niveau supérieur de properties (pas de tableau products). Prend en charge les paramètres facultatifs type (43.0.0+) et catalogName pour les déclencheurs de catalogue de retour en stock et de baisse de prix. Sur les versions antérieures, utilisez logCustomEvent ou la REST API pour envoyer ces propriétés.
CartUpdatedEvent ecommerce.cart_updated Utilisez CartUpdatedAction (ADD, REMOVE, REPLACE) pour la propriété action.
CheckoutStartedEvent ecommerce.checkout_started  
OrderPlacedEvent ecommerce.order_placed Prend en charge les paramètres facultatifs cartId, totalDiscounts et discounts.

Blocs de construction partagés

  • EcommerceProduct : éléments de ligne pour les événements de panier, de paiement et de commande.
    • Requis : productId, productName, variantId, price, quantity (Long non négatif)
    • Facultatif : imageUrl, productUrl, metadata
  • BrazeProperties : metadata au niveau de l’événement ou du produit. Les clés doivent être des chaînes de caractères non vides d’au moins 255 caractères, sans signe dollar ($) en début de chaîne.

Validation côté client

Les payloads invalides lèvent une IllegalArgumentException dès que vous construisez la classe d’événement : l’événement n’est donc jamais mis en file d’attente. Règles courantes :

Champ ou règle Validation
ID et noms de type chaîne (product_id, product_name, variant_id, cart_id, checkout_id, order_id, source, URL facultatives) Non vide, jusqu’à 255 caractères
price, total_value, total_discounts Doit être supérieur ou égal à 0
currency Code ISO 4217 valide (nettoyé et converti en majuscules par le SDK)
products (événements de panier, de paiement et de commande) Au moins un EcommerceProduct
quantity (par produit) Entier non négatif

Au moment de l’envoi, si les propriétés sérialisées dépassent la limite de taille du SDK, logEcommerceEvent enregistre une erreur et n’envoie pas l’événement.

Exemples de code

import com.braze.Braze
import com.braze.models.outgoing.BrazeProperties
import com.braze.models.recommended.ecommerce.ProductViewedEvent

val metadata = BrazeProperties()
  .addProperty("category", "Apparel")

val productViewedEvent = ProductViewedEvent(
  productId = "PROD101",
  productName = "Silk Scarf",
  variantId = "SCARF_RED_SILK",
  price = 150.00,
  currency = "EUR",
  source = "https://braze-fashion.eu",
  imageUrl = "https://braze-fashion.eu/images/scarf_red.jpg",
  productUrl = "https://braze-fashion.eu/products/scarf",
  metadata = metadata,
  type = listOf("price_drop", "back_in_stock"),
  catalogName = "scarves",
)

Braze.getInstance(context).logEcommerceEvent(productViewedEvent)

Définissez action à l’aide de CartUpdatedAction :

Valeur Valeur transmise Description
CartUpdatedAction.ADD add Augmenter la quantité ou ajouter une ligne.
CartUpdatedAction.REMOVE remove Diminuer la quantité ; supprimer la ligne à 0.
CartUpdatedAction.REPLACE replace Remplacer l’intégralité du panier (par défaut).
import com.braze.Braze
import com.braze.models.recommended.ecommerce.CartUpdatedAction
import com.braze.models.recommended.ecommerce.CartUpdatedEvent
import com.braze.models.recommended.ecommerce.EcommerceProduct

val product = EcommerceProduct(
  productId = "SKU-RUN-4821",
  productName = "Ultraboost Running Shoe",
  variantId = "UB-BLK-11",
  price = 189.99,
  quantity = 1,
)

val cartUpdatedEvent = CartUpdatedEvent(
  cartId = "cart_abc123",
  currency = "USD",
  source = "android",
  totalValue = 189.99,
  products = listOf(product),
  action = CartUpdatedAction.ADD,
)

Braze.getInstance(context).logEcommerceEvent(cartUpdatedEvent)
import com.braze.Braze
import com.braze.models.outgoing.BrazeProperties
import com.braze.models.recommended.ecommerce.CheckoutStartedEvent
import com.braze.models.recommended.ecommerce.EcommerceProduct

val products = listOf(
  EcommerceProduct(
    productId = "SKU-RUN-4821",
    productName = "Ultraboost Running Shoe",
    variantId = "UB-BLK-11",
    price = 189.99,
    quantity = 1,
  ),
)

val checkoutStartedEvent = CheckoutStartedEvent(
  checkoutId = "chk_88291",
  currency = "USD",
  source = "android",
  totalValue = 234.96,
  products = products,
  cartId = "cart_abc123",
  metadata = BrazeProperties().addProperty("checkout_url", "https://www.example.com/checkout/chk_88291"),
)

Braze.getInstance(context).logEcommerceEvent(checkoutStartedEvent)
import com.braze.Braze
import com.braze.models.outgoing.BrazeProperties
import com.braze.models.recommended.ecommerce.EcommerceProduct
import com.braze.models.recommended.ecommerce.OrderPlacedEvent

val products = listOf(
  EcommerceProduct(
    productId = "SKU-RUN-4821",
    productName = "Ultraboost Running Shoe",
    variantId = "UB-BLK-11",
    price = 189.99,
    quantity = 1,
  ),
)

val orderPlacedEvent = OrderPlacedEvent(
  orderId = "ord_77821",
  currency = "USD",
  source = "android",
  totalValue = 224.96,
  products = products,
  cartId = "cart_abc123",
  totalDiscounts = 10.0,
  discounts = listOf(
    mapOf("code" to "SPRING10", "amount" to 10.0, "type" to "percentage"),
  ),
  metadata = BrazeProperties().addProperty("order_status_url", "https://www.example.com/orders/ord_77821/status"),
)

Braze.getInstance(context).logEcommerceEvent(orderPlacedEvent)

Braze ne fournit pas de classe SDK typée pour cet événement. Utilisez logCustomEvent avec un payload correspondant au schéma de l’événement ecommerce.order_cancelled.

import com.braze.Braze
import com.braze.models.outgoing.BrazeProperties
import org.json.JSONArray
import org.json.JSONObject

val properties = BrazeProperties(
  JSONObject()
    .put("order_id", "ord_77821")
    .put("total_value", 224.96)
    .put("currency", "USD")
    .put("cancel_reason", "customer_request")
    .put("source", "android")
    .put(
      "products",
      JSONArray().put(
        JSONObject()
          .put("product_id", "SKU-RUN-4821")
          .put("product_name", "Ultraboost Running Shoe")
          .put("variant_id", "UB-BLK-11")
          .put("quantity", 1)
          .put("price", 189.99),
      ),
    ),
)

Braze.getInstance(context).logCustomEvent("ecommerce.order_cancelled", properties)

Braze ne fournit pas de classe SDK typée pour cet événement. Utilisez logCustomEvent avec un payload correspondant au schéma de l’événement ecommerce.order_refunded.

import com.braze.Braze
import com.braze.models.outgoing.BrazeProperties
import org.json.JSONArray
import org.json.JSONObject

val properties = BrazeProperties(
  JSONObject()
    .put("order_id", "ord_77821")
    .put("total_value", 189.99)
    .put("currency", "USD")
    .put("source", "android")
    .put(
      "products",
      JSONArray().put(
        JSONObject()
          .put("product_id", "SKU-RUN-4821")
          .put("product_name", "Ultraboost Running Shoe")
          .put("variant_id", "UB-BLK-11")
          .put("quantity", 1)
          .put("price", 189.99),
      ),
    ),
)

Braze.getInstance(context).logCustomEvent("ecommerce.order_refunded", properties)
import com.braze.Braze;
import com.braze.models.outgoing.BrazeProperties;
import com.braze.models.recommended.ecommerce.ProductViewedEvent;

BrazeProperties metadata = new BrazeProperties()
    .addProperty("category", "Apparel");

ProductViewedEvent productViewedEvent = new ProductViewedEvent(
    /* productId */ "PROD101",
    /* productName */ "Silk Scarf",
    /* variantId */ "SCARF_RED_SILK",
    /* price */ 150.00,
    /* currency */ "EUR",
    /* source */ "https://braze-fashion.eu",
    /* imageUrl */ "https://braze-fashion.eu/images/scarf_red.jpg",
    /* productUrl */ "https://braze-fashion.eu/products/scarf",
    /* metadata */ metadata,
    /* type */ Arrays.asList("price_drop", "back_in_stock"),
    /* catalogName */ "scarves"
);

Braze.getInstance(context).logEcommerceEvent(productViewedEvent);

Définissez action à l’aide de CartUpdatedAction :

Valeur Valeur transmise Description
CartUpdatedAction.ADD add Augmenter la quantité ou ajouter une ligne.
CartUpdatedAction.REMOVE remove Diminuer la quantité ; supprimer la ligne à 0.
CartUpdatedAction.REPLACE replace Remplacer l’intégralité du panier (par défaut).
import com.braze.Braze;
import com.braze.models.recommended.ecommerce.CartUpdatedAction;
import com.braze.models.recommended.ecommerce.CartUpdatedEvent;
import com.braze.models.recommended.ecommerce.EcommerceProduct;
import java.util.Collections;

EcommerceProduct product = new EcommerceProduct(
    /* productId */ "SKU-RUN-4821",
    /* productName */ "Ultraboost Running Shoe",
    /* variantId */ "UB-BLK-11",
    /* price */ 189.99,
    /* quantity */ 1
);

CartUpdatedEvent cartUpdatedEvent = new CartUpdatedEvent(
    /* cartId */ "cart_abc123",
    /* currency */ "USD",
    /* source */ "android",
    /* totalValue */ 189.99,
    /* products */ Collections.singletonList(product),
    /* metadata */ null,
    /* action */ CartUpdatedAction.ADD
);

Braze.getInstance(context).logEcommerceEvent(cartUpdatedEvent);
import com.braze.Braze;
import com.braze.models.outgoing.BrazeProperties;
import com.braze.models.recommended.ecommerce.CheckoutStartedEvent;
import com.braze.models.recommended.ecommerce.EcommerceProduct;
import java.util.Collections;

EcommerceProduct product = new EcommerceProduct(
    /* productId */ "SKU-RUN-4821",
    /* productName */ "Ultraboost Running Shoe",
    /* variantId */ "UB-BLK-11",
    /* price */ 189.99,
    /* quantity */ 1
);

BrazeProperties metadata = new BrazeProperties()
    .addProperty("checkout_url", "https://www.example.com/checkout/chk_88291");

CheckoutStartedEvent checkoutStartedEvent = new CheckoutStartedEvent(
    /* checkoutId */ "chk_88291",
    /* currency */ "USD",
    /* source */ "android",
    /* totalValue */ 234.96,
    /* products */ Collections.singletonList(product),
    /* cartId */ "cart_abc123",
    /* metadata */ metadata
);

Braze.getInstance(context).logEcommerceEvent(checkoutStartedEvent);
import com.braze.Braze;
import com.braze.models.outgoing.BrazeProperties;
import com.braze.models.recommended.ecommerce.EcommerceProduct;
import com.braze.models.recommended.ecommerce.OrderPlacedEvent;
import java.util.Collections;

EcommerceProduct product = new EcommerceProduct(
    /* productId */ "SKU-RUN-4821",
    /* productName */ "Ultraboost Running Shoe",
    /* variantId */ "UB-BLK-11",
    /* price */ 189.99,
    /* quantity */ 1
);

BrazeProperties metadata = new BrazeProperties()
    .addProperty("order_status_url", "https://www.example.com/orders/ord_77821/status");

OrderPlacedEvent orderPlacedEvent = new OrderPlacedEvent(
    /* orderId */ "ord_77821",
    /* currency */ "USD",
    /* source */ "android",
    /* totalValue */ 224.96,
    /* products */ Collections.singletonList(product),
    /* cartId */ "cart_abc123",
    /* totalDiscounts */ 10.0,
    /* discounts */ null,
    /* metadata */ metadata
);

Braze.getInstance(context).logEcommerceEvent(orderPlacedEvent);

Braze ne fournit pas de classe SDK typée pour cet événement. Utilisez logCustomEvent avec un payload correspondant au schéma de l’événement ecommerce.order_cancelled.

import com.braze.Braze;
import com.braze.models.outgoing.BrazeProperties;
import org.json.JSONArray;
import org.json.JSONObject;

Braze.getInstance(context).logCustomEvent(
    "ecommerce.order_cancelled",
    new BrazeProperties(new JSONObject()
        .put("order_id", "ord_77821")
        .put("total_value", 224.96)
        .put("currency", "USD")
        .put("cancel_reason", "customer_request")
        .put("source", "android")
        .put("products", new JSONArray()
            .put(new JSONObject()
                .put("product_id", "SKU-RUN-4821")
                .put("product_name", "Ultraboost Running Shoe")
                .put("variant_id", "UB-BLK-11")
                .put("quantity", 1)
                .put("price", 189.99)))));

Braze ne fournit pas de classe SDK typée pour cet événement. Utilisez logCustomEvent avec un payload correspondant au schéma de l’événement ecommerce.order_refunded.

import com.braze.Braze;
import com.braze.models.outgoing.BrazeProperties;
import org.json.JSONArray;
import org.json.JSONObject;

Braze.getInstance(context).logCustomEvent(
    "ecommerce.order_refunded",
    new BrazeProperties(new JSONObject()
        .put("order_id", "ord_77821")
        .put("total_value", 189.99)
        .put("currency", "USD")
        .put("source", "android")
        .put("products", new JSONArray()
            .put(new JSONObject()
                .put("product_id", "SKU-RUN-4821")
                .put("product_name", "Ultraboost Running Shoe")
                .put("variant_id", "UB-BLK-11")
                .put("quantity", 1)
                .put("price", 189.99)))));

iOS

Le SDK Swift fournit des classes d’événements eCommerce typées — ProductViewedEvent, CartUpdatedEvent, CheckoutStartedEvent et OrderPlacedEvent — que vous construisez puis transmettez à logEcommerceEvent. Utilisez ProductLineItem pour les produits des événements de panier, de paiement et de commande. Chaque initialiseur peut lever une exception : encapsulez-le donc dans try? et n’enregistrez l’événement que si la construction réussit. Cette fonctionnalité est disponible à partir de la version 15.0.0 du SDK Swift.

ecommerce.order_cancelled et ecommerce.order_refunded ne sont pas disponibles en tant que classes typées du SDK Swift. Enregistrez-les avec logCustomEvent.

Exemples de code

if let productViewedEvent = try? Braze.Ecommerce.ProductViewedEvent(
    productId: "4111176",
    productName: "Torchie runners",
    variantId: "4111176700",
    imageUrl: "https://braze-apparel.com/images/products/large/torchie-runners.jpg",
    productUrl: "https://braze-apparel.com/footwear-categories/sneakers/braze-orange-torchie-runners/",
    price: 85,
    currency: "GBP",
    source: "https://braze-apparel.com/",
    metadata: [
        "color": "ORANGE",
        "size": "6",
        "brand": "Braze"
    ],
    type: ["price_drop", "back_in_stock"],
    catalogName: "footwear"
) {
    AppDelegate.braze?.logEcommerceEvent(productViewedEvent)
}
if let productLine = try? Braze.Ecommerce.ProductLineItem(
    productId: "8266836345064",
    productName: "Classic T-Shirt",
    variantId: "44610569208040",
    imageUrl: "https://braze-apparel.com/images/tshirt-blue-medium.jpg",
    productUrl: "https://braze-apparel.com/products/classic-tshirt?variant=44610569208040",
    quantity: 2,
    price: 99.99,
    metadata: [
        "sku": "TSH-BLU-M",
        "color": "BLUE",
        "size": "Medium",
        "brand": "Braze"
    ]
), let cartUpdatedEvent = try? Braze.Ecommerce.CartUpdatedEvent(
    cartId: "cart_12345",
    totalValue: 199.98,
    currency: "USD",
    products: [productLine],
    source: "https://braze-apparel.com",
    metadata: [:]
) {
    AppDelegate.braze?.logEcommerceEvent(cartUpdatedEvent)
}
if let productLine = try? Braze.Ecommerce.ProductLineItem(
    productId: "632910392",
    productName: "Wireless Headphones",
    variantId: "808950810",
    quantity: 1,
    price: 199.98,
    metadata: [
        "sku": "WH-BLK-PRO",
        "color": "Black",
        "brand": "BrazeAudio"
    ]
), let checkoutStartedEvent = try? Braze.Ecommerce.CheckoutStartedEvent(
    checkoutId: "checkout_abc123",
    cartId: "cart_12345",
    totalValue: 199.98,
    currency: "USD",
    products: [productLine],
    source: "https://braze-audio.com",
    metadata: [
        "checkout_url": "https://checkout.braze-audio.com/abc123"
    ]
) {
    AppDelegate.braze?.logEcommerceEvent(checkoutStartedEvent)
}
if let productLine = try? Braze.Ecommerce.ProductLineItem(
    productId: "632910392",
    productName: "Wireless Headphones",
    variantId: "808950810",
    quantity: 1,
    price: 199.98,
    metadata: [
        "sku": "WH-BLK-PRO",
        "color": "Black",
        "brand": "BrazeAudio"
    ]
), let orderPlacedEvent = try? Braze.Ecommerce.OrderPlacedEvent(
    orderId: "order_67890",
    cartId: "cart_12345",
    totalValue: 189.98,
    currency: "USD",
    totalDiscounts: 10.00,
    discounts: [.structured(code: "SAVE10", amount: 10.00, type: "fixed")],
    products: [productLine],
    source: "https://braze-audio.com",
    metadata: [
        "order_status_url": "https://braze-audio.com/orders/67890/status",
        "order_number": "ORD-2024-001234",
        "tags": ["electronics", "audio"],
        "referring_site": "https://www.e-referrals.com",
        "payment_gateway_names": ["tap2pay", "dotcash"]
    ]
) {
    AppDelegate.braze?.logEcommerceEvent(orderPlacedEvent)
}

Braze ne fournit pas de classe SDK typée pour cet événement. Utilisez logCustomEvent avec un payload correspondant au schéma de l’événement ecommerce.order_cancelled.

let discounts: [[String: Any]] = [
    [
        "code": "SAVE10",
        "amount": 10.00
    ]
]

let products: [[String: Any]] = [
    [
        "product_id": "632910392",
        "product_name": "Wireless Headphones",
        "variant_id": "808950810",
        "quantity": 1,
        "price": 199.98,
        "metadata": [
            "sku": "WH-BLK-PRO",
            "color": "Black",
            "brand": "BrazeAudio"
        ]
    ]
]

let properties: [String: Any] = [
    "order_id": "order_67890",
    "cancel_reason": "customer changed mind",
    "total_value": 189.98,
    "subtotal_value": 169.98,
    "tax": 14.40,
    "shipping": 5.60,
    "currency": "USD",
    "total_discounts": 10.00,
    "discounts": discounts,
    "products": products,
    "source": "https://braze-audio.com",
    "metadata": [
        "order_status_url": "https://braze-audio.com/orders/67890/status",
        "order_number": "ORD-2024-001234",
        "tags": ["cancelled", "customer_request"]
    ]
]

AppDelegate.braze?.logCustomEvent(name: "ecommerce.order_cancelled", properties: properties)

Braze ne fournit pas de classe SDK typée pour cet événement. Utilisez logCustomEvent avec un payload correspondant au schéma de l’événement ecommerce.order_refunded.

let discounts: [[String: Any]] = [
    [
        "code": "SAVE5",
        "amount": 5.00
    ]
]

let products: [[String: Any]] = [
    [
        "product_id": "632910392",
        "product_name": "Wireless Headphones",
        "variant_id": "808950810",
        "quantity": 1,
        "price": 99.99,
        "metadata": [
            "sku": "WH-BLK-PRO",
            "color": "Black",
            "brand": "BrazeAudio"
        ]
    ]
]

let properties: [String: Any] = [
    "order_id": "order_67890",
    "total_value": 99.99,
    "currency": "USD",
    "total_discounts": 5.00,
    "discounts": discounts,
    "products": products,
    "source": "https://braze-audio.com",
    "metadata": [
        "order_status_url": "https://braze-audio.com/orders/67890/status",
        "order_note": "Customer requested refund due to defective item",
        "order_number": "ORD-2024-001234",
        "tags": ["refund", "defective"]
    ]
]

AppDelegate.braze?.logCustomEvent(name: "ecommerce.order_refunded", properties: properties)

Web

Avec le SDK Web 6.8.0+, appelez logEcommerceEvent en indiquant un name d’événement et des properties. Avec les anciennes versions du SDK, appelez logCustomEvent en indiquant le nom de l’événement et un objet de propriétés. Les événements ecommerce.order_cancelled et ecommerce.order_refunded utilisent logCustomEvent.

Exemples de code

Avec les versions récentes du SDK, appelez logEcommerceEvent() :

braze.logEcommerceEvent({
    "name": "ecommerce.product_viewed",
    "properties": {
        "product_id": "4111176",
        "product_name": "Torchie runners",
        "variant_id": "4111176700",
        "image_url": "https://braze-apparel.com/images/products/large/torchie-runners.jpg",
        "product_url": "https://braze-apparel.com/footwear-categories/sneakers/braze-orange-torchie-runners/",
        "price": 85,
        "currency": "GBP",
        "source": "https://braze-apparel.com/",
        "type": ["price_drop", "back_in_stock"],
        "catalog_name": "footwear",
        "metadata": {
            "color": "ORANGE",
            "size": "6",
            "brand": "Braze"
        }
    }
});

Avec les anciennes versions du SDK, appelez logCustomEvent() :

braze.logCustomEvent("ecommerce.product_viewed", {
    "product_id": "4111176",
    "product_name": "Torchie runners",
    "variant_id": "4111176700",
    "image_url": "https://braze-apparel.com/images/products/large/torchie-runners.jpg",
    "product_url": "https://braze-apparel.com/footwear-categories/sneakers/braze-orange-torchie-runners/",
    "price": 85,
    "currency": "GBP",
    "source": "https://braze-apparel.com/",
    "metadata": {
        "color": "ORANGE",
        "size": "6",
        "brand": "Braze"
    }
});

Avec les versions récentes du SDK, appelez logEcommerceEvent() :

braze.logEcommerceEvent({
    "name": "ecommerce.cart_updated",
    "properties": {
        "cart_id": "cart_12345",
        "currency": "USD",
        "total_value": 199.98,
        "products": [
            {
                "product_id": "8266836345064",
                "product_name": "Classic T-Shirt",
                "variant_id": "44610569208040",
                "image_url": "https://braze-apparel.com/images/tshirt-blue-medium.jpg",
                "product_url": "https://braze-apparel.com/products/classic-tshirt?variant=44610569208040",
                "quantity": 2,
                "price": 99.99,
                "metadata": {
                    "sku": "TSH-BLU-M",
                    "color": "BLUE",
                    "size": "Medium",
                    "brand": "Braze"
                }
            }
        ],
        "source": "https://braze-apparel.com",
        "metadata": {}
    }
});

Avec les anciennes versions du SDK, appelez logCustomEvent() :

braze.logCustomEvent("ecommerce.cart_updated", {
    "cart_id": "cart_12345",
    "currency": "USD",
    "total_value": 199.98,
    "subtotal_value": 179.98,
    "tax": 15.00,
    "shipping": 5.00,
    "products": [
        {
            "product_id": "8266836345064",
            "product_name": "Classic T-Shirt",
            "variant_id": "44610569208040",
            "image_url": "https://braze-apparel.com/images/tshirt-blue-medium.jpg",
            "product_url": "https://braze-apparel.com/products/classic-tshirt?variant=44610569208040",
            "quantity": 2,
            "price": 99.99,
            "metadata": {
                "sku": "TSH-BLU-M",
                "color": "BLUE",
                "size": "Medium",
                "brand": "Braze"
            }
        }
    ],
    "source": "https://braze-apparel.com",
    "metadata": {}
});

Avec les versions récentes du SDK, appelez logEcommerceEvent() :

braze.logEcommerceEvent({
    "name": "ecommerce.checkout_started",
    "properties": {
        "checkout_id": "checkout_abc123",
        "cart_id": "cart_12345",
        "total_value": 199.98,
        "currency": "USD",
        "products": [
            {
                "product_id": "632910392",
                "product_name": "Wireless Headphones",
                "variant_id": "808950810",
                "quantity": 1,
                "price": 199.98,
                "metadata": {
                    "sku": "WH-BLK-PRO",
                    "color": "Black",
                    "brand": "BrazeAudio"
                }
            }
        ],
        "source": "https://braze-audio.com",
        "metadata": {
            "checkout_url": "https://checkout.braze-audio.com/abc123"
        }
    }
});

Avec les anciennes versions du SDK, appelez logCustomEvent() :

braze.logCustomEvent("ecommerce.checkout_started", {
    "checkout_id": "checkout_abc123",
    "cart_id": "cart_12345",
    "total_value": 199.98,
    "subtotal_value": 179.98,
    "tax": 15.00,
    "shipping": 5.00,
    "currency": "USD",
    "products": [
        {
            "product_id": "632910392",
            "product_name": "Wireless Headphones",
            "variant_id": "808950810",
            "quantity": 1,
            "price": 199.98,
            "metadata": {
                "sku": "WH-BLK-PRO",
                "color": "Black",
                "brand": "BrazeAudio"
            }
        }
    ],
    "source": "https://braze-audio.com",
    "metadata": {
        "checkout_url": "https://checkout.braze-audio.com/abc123"
    }
});

Avec les versions récentes du SDK, appelez logEcommerceEvent() :

braze.logEcommerceEvent({
    "name": "ecommerce.order_placed",
    "properties": {
        "order_id": "order_67890",
        "cart_id": "cart_12345",
        "total_value": 189.98,
        "currency": "USD",
        "total_discounts": 10.00,
        "discounts": [
            {
                "code": "SAVE10",
                "amount": 10.00
            }
        ],
        "products": [
            {
                "product_id": "632910392",
                "product_name": "Wireless Headphones",
                "variant_id": "808950810",
                "quantity": 1,
                "price": 199.98,
                "metadata": {
                    "sku": "WH-BLK-PRO",
                    "color": "Black",
                    "brand": "BrazeAudio"
                }
            }
        ],
        "source": "https://braze-audio.com",
        "metadata": {
            "order_status_url": "https://braze-audio.com/orders/67890/status",
            "order_number": "ORD-2024-001234",
            "tags": ["electronics", "audio"],
            "referring_site": "https://www.e-referrals.com",
            "payment_gateway_names": ["tap2pay", "dotcash"]
        }
    }
});

Avec les anciennes versions du SDK, appelez logCustomEvent() :

braze.logCustomEvent("ecommerce.order_placed", {
    "order_id": "order_67890",
    "cart_id": "cart_12345",
    "total_value": 189.98,
    "subtotal_value": 169.98,
    "tax": 14.40,
    "shipping": 5.60,
    "currency": "USD",
    "total_discounts": 10.00,
    "discounts": [
        {
            "code": "SAVE10",
            "amount": 10.00
        }
    ],
    "products": [
        {
            "product_id": "632910392",
            "product_name": "Wireless Headphones",
            "variant_id": "808950810",
            "quantity": 1,
            "price": 199.98,
            "metadata": {
                "sku": "WH-BLK-PRO",
                "color": "Black",
                "brand": "BrazeAudio"
            }
        }
    ],
    "source": "https://braze-audio.com",
    "metadata": {
        "order_status_url": "https://braze-audio.com/orders/67890/status",
        "order_number": "ORD-2024-001234",
        "tags": ["electronics", "audio"],
        "referring_site": "https://www.e-referrals.com",
        "payment_gateway_names": ["tap2pay", "dotcash"]
    }
});
braze.logCustomEvent("ecommerce.order_cancelled", {
    "order_id": "order_67890",
    "cancel_reason": "customer changed mind",
    "total_value": 189.98,
    "subtotal_value": 169.98,
    "tax": 14.40,
    "shipping": 5.60,
    "currency": "USD",
    "total_discounts": 10.00,
    "discounts": [
        {
            "code": "SAVE10",
            "amount": 10.00
        }
    ],
    "products": [
        {
            "product_id": "632910392",
            "product_name": "Wireless Headphones",
            "variant_id": "808950810",
            "quantity": 1,
            "price": 199.98,
            "metadata": {
                "sku": "WH-BLK-PRO",
                "color": "Black",
                "brand": "BrazeAudio"
            }
        }
    ],
    "source": "https://braze-audio.com",
    "metadata": {
        "order_status_url": "https://braze-audio.com/orders/67890/status",
        "order_number": "ORD-2024-001234",
        "tags": ["cancelled", "customer_request"]
    }
});
braze.logCustomEvent("ecommerce.order_refunded", {
    "order_id": "order_67890",
    "total_value": 99.99,
    "currency": "USD",
    "total_discounts": 5.00,
    "discounts": [
        {
            "code": "SAVE5",
            "amount": 5.00
        }
    ],
    "products": [
        {
            "product_id": "632910392",
            "product_name": "Wireless Headphones",
            "variant_id": "808950810",
            "quantity": 1,
            "price": 99.99,
            "metadata": {
                "sku": "WH-BLK-PRO",
                "color": "Black",
                "brand": "BrazeAudio"
            }
        }
    ],
    "source": "https://braze-audio.com",
    "metadata": {
        "order_status_url": "https://braze-audio.com/orders/67890/status",
        "order_note": "Customer requested refund due to defective item",
        "order_number": "ORD-2024-001234",
        "tags": ["refund", "defective"]
    }
});

Google Tag Manager

Si vous utilisez Google Tag Manager (GTM), sélectionnez le type de tag Log eCommerce Event (New) dans le tag Braze Actions au lieu d’appeler logEcommerceEvent() dans le code de votre site. Ce tag lit votre couche de données eCommerce au format GA4 et prend en charge les événements ecommerce.product_viewed, ecommerce.cart_updated, ecommerce.checkout_started et ecommerce.order_placed. Il prend également en charge les métadonnées d’événement et de produit. Pour enregistrer ecommerce.order_cancelled ou ecommerce.order_refunded, utilisez un tag Custom HTML qui appelle braze.logCustomEvent().

Pour connaître les étapes de configuration, le mappage des champs et la résolution des problèmes, consultez Enregistrer des événements eCommerce avec GTM.

Enregistrement manuel avec logCustomEvent

Pour enregistrer manuellement un événement recommandé, appelez logCustomEvent avec le nom exact de l’événement (par exemple, ecommerce.product_viewed) et un payload BrazeProperties ou JSONObject construit manuellement. Le SDK ne valide pas les schémas d’événements recommandés pour les appels manuels. Braze valide ces payloads lors de l’ingestion :

  • Les payloads valides sont traités comme des événements recommandés avec un post-traitement complet.
  • Les payloads invalides (champs requis manquants, types incorrects, propriétés de niveau supérieur supplémentaires) sont rejetés après l’ingestion. Les échecs apparaissent dans le journal de traitement SDK de l’espace de travail et dans l’e-mail récapitulatif des échecs.

Utilisez logEcommerceEvent autant que possible afin de détecter les données invalides avant qu’elles ne quittent l’application. Pour l’utilisation générale de logCustomEvent, consultez Enregistrer des événements personnalisés.

New Stuff!