Registrar eventos de comercio electrónico
Aprende a registrar eventos recomendados de comercio electrónico a través de los SDK de Android, Swift y Web de Braze usando clases de eventos tipadas y
logEcommerceEvent. Para consultar los esquemas de propiedades del evento, las características de la plataforma y la validación de ingesta, consulta Eventos recomendados y Validación de eventos y solución de problemas.

Para los SDK envolventes que no aparecen en la lista, usa en su lugar el método nativo de Android o Swift correspondiente.
Esquemas de eventos
Los seis eventos recomendados de comercio electrónico comparten un esquema a nivel de pedido en todas las plataformas. Utiliza las siguientes tablas de propiedades cuando crees la carga útil de cada evento. Para consultar el esquema canónico con el comportamiento de validación completo y ejemplos de la REST API, consulta Eventos recomendados. Para conocer características de la plataforma como la segmentación, las plantillas de Canvas y los informes, consulta Cómo utilizar los eventos de comercio electrónico.
Desencadena este evento cuando un usuario vea la página de detalles de un producto.
Propiedades del evento
| Nombre de la propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
product_id |
Cadena | Sí | Identificador único del producto (por ejemplo, SKU o ID del artículo). |
product_name |
Cadena | Sí | Nombre visible del producto. |
variant_id |
Cadena | Sí | Identificador de la variante del producto (por ejemplo, shirt_medium_blue). |
image_url |
Cadena | No | URL de la imagen del producto. |
product_url |
Cadena | No | URL de la página del producto para obtener más detalles. |
price |
Flotante | Sí | Precio unitario de la variante en el momento de la visualización. |
currency |
Cadena | Sí | Código ISO 4217 de tres letras (por ejemplo, USD o EUR). |
source |
Cadena | Sí | Origen del evento (por ejemplo, web, ios o android). |
type |
Matriz de cadenas | No | Obligatorio para utilizar las características de desencadenamiento por catálogo de Braze para alertas de reposición de existencias y bajada de precio. Valores aceptados: "price_drop", "back_in_stock". |
catalog_name |
Cadena | No | El catálogo al que pertenece una suscripción de reposición de existencias o bajada de precio creada a partir de este evento. Si se omite, se utiliza el catálogo alternativo del espacio de trabajo. Debe ser una propiedad de nivel superior; se ignora un catalog_name anidado dentro de metadata. |
metadata |
Objeto | No | Pares clave-valor flexibles (por ejemplo, category o brand). |
Desencadena este evento cada vez que cambie el contenido del carrito de un usuario. Utiliza la sustitución completa del carrito (omite action o establécelo en replace) o las actualizaciones incrementales (add o remove).
Propiedades del evento
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
cart_id |
Cadena | Sí | Identificador único del carrito. Se comparte entre los eventos de carrito, pago y pedido para el mapeado del carrito del usuario. Para conocer las reglas de reutilización después del pago o de la realización del pedido, consulta ID del carrito después del pago o del pedido. |
action |
Cadena | No | add (aumenta la cantidad o añade una línea), remove (reduce la cantidad; la línea se elimina al llegar a 0) o replace (sustitución completa del carrito, igual que omitir action). |
total_value |
Flotante | Condicional | Obligatorio cuando action se omite o es replace, y se almacena como el total del carrito. Opcional cuando action es add o remove.Cuando action es add o remove, el valor no se almacena en el carrito y no borra un total almacenado previamente. Cuando un carrito se actualiza solo con add o remove, no se almacena ningún total_value y la etiqueta {% shopping_cart %} suma el price de cada producto multiplicado por su quantity. |
subtotal_value |
Flotante | No | Valor subtotal del carrito (después de descuentos, antes de impuestos y envío). No se almacena en el carrito ni está disponible a través de la etiqueta de Liquid {% shopping_cart %}. |
tax |
Flotante | No | Total de impuestos aplicados al carrito. No se almacena en el carrito ni está disponible a través de la etiqueta de Liquid {% shopping_cart %}. |
shipping |
Flotante | No | Coste total de envío del carrito. No se almacena en el carrito ni está disponible a través de la etiqueta de Liquid {% shopping_cart %}. |
currency |
Cadena | Sí | Código ISO 4217 de tres letras. |
products |
Matriz | Sí | Líneas de artículos de esta actualización. Consulta la tabla de propiedades del producto. |
source |
Cadena | Sí | Origen del evento. |
metadata |
Objeto | No | Pares clave-valor flexibles para datos adicionales a nivel de evento. |
Propiedades del producto (products[])
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
product_id |
Cadena | Sí | Identificador único del producto. |
product_name |
Cadena | Sí | Nombre visible del producto. |
variant_id |
Cadena | Sí | Identificador de la variante. |
image_url |
Cadena | No | URL de la imagen del producto. |
product_url |
Cadena | No | URL de la página del producto. |
quantity |
Entero | Sí | En la sustitución completa, las unidades de esta línea en el carrito. En add o remove, cuántas unidades se añaden o se eliminan. |
price |
Flotante | Sí | Precio unitario de la variante. |
metadata |
Objeto | No | Pares clave-valor flexibles (por ejemplo, color o size). |
Desencadena este evento cuando el usuario inicie el flujo de pago.
Propiedades del evento
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
checkout_id |
Cadena | Sí | Identificador único de la sesión de pago. |
cart_id |
Cadena | No | Identificador del carrito. Se comparte entre los eventos de carrito, pago y pedido para el mapeado del carrito del usuario. |
total_value |
Flotante | Sí | Valor monetario total del pago. |
subtotal_value |
Flotante | No | Valor subtotal (después de descuentos, antes de impuestos y envío). |
tax |
Flotante | No | Total de impuestos aplicados al pago. |
shipping |
Flotante | No | Coste total de envío. |
currency |
Cadena | Sí | Código ISO 4217 de tres letras. |
products |
Matriz | Sí | Artículos que se están pagando. Consulta la tabla de propiedades del producto. |
source |
Cadena | Sí | Origen del evento. |
metadata |
Objeto | No | Pares clave-valor flexibles. Subpropiedad reconocida: checkout_url (Cadena). |
Propiedades del producto (products[])
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
product_id |
Cadena | Sí | Identificador único del producto. |
product_name |
Cadena | Sí | Nombre visible del producto. |
variant_id |
Cadena | Sí | Identificador de la variante. |
image_url |
Cadena | No | URL de la imagen del producto. |
product_url |
Cadena | No | URL de la página del producto. |
quantity |
Entero | Sí | Número de unidades en el carrito. |
price |
Flotante | Sí | Precio unitario de la variante. |
metadata |
Objeto | No | Pares clave-valor flexibles (por ejemplo, color o size). |
Desencadena este evento cuando un pedido se complete correctamente o se confirme el pago.
Propiedades del evento
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
order_id |
Cadena | Sí | Identificador único del pedido. |
cart_id |
Cadena | No | Identificador del carrito. Se comparte entre los eventos de carrito, pago y pedido para el mapeado del carrito del usuario. |
total_value |
Flotante | Sí | Valor monetario total del pedido. |
subtotal_value |
Flotante | No | Valor subtotal (después de descuentos, antes de impuestos y envío). |
tax |
Flotante | No | Total de impuestos aplicados al pedido. |
shipping |
Flotante | No | Coste total de envío. |
currency |
Cadena | Sí | Código ISO 4217 de tres letras. |
total_discounts |
Flotante | No | Importe total de los descuentos aplicados al pedido. |
discounts |
Matriz | No | Lista detallada de los descuentos aplicados. Cada objeto de descuento admite code (Cadena), amount (Flotante) y type (Cadena). |
products |
Matriz | Sí | Artículos del pedido. Consulta la tabla de propiedades del producto. |
source |
Cadena | Sí | Origen del evento. |
metadata |
Objeto | No | Pares clave-valor flexibles. Subpropiedad reconocida: order_status_url (Cadena). |
Propiedades del producto (products[])
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
product_id |
Cadena | Sí | Identificador único del producto. |
product_name |
Cadena | Sí | Nombre visible del producto. |
variant_id |
Cadena | Sí | Identificador de la variante. |
image_url |
Cadena | No | URL de la imagen del producto. |
product_url |
Cadena | No | URL de la página del producto. |
quantity |
Entero | Sí | Número de unidades en el pedido. |
price |
Flotante | Sí | Precio unitario de la variante. |
metadata |
Objeto | No | Pares clave-valor flexibles (por ejemplo, color o size). |
Desencadena este evento cuando se cancele un pedido.
Propiedades del evento
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
order_id |
Cadena | Sí | Identificador único del pedido. |
total_value |
Flotante | Sí | Valor monetario total del pedido que se cancela. Envía el importe absoluto (mayor o igual que 0); Braze se encarga de la reducción. |
subtotal_value |
Flotante | No | Valor subtotal (después de descuentos, antes de impuestos y envío). |
tax |
Flotante | No | Total de impuestos aplicados al pedido. |
shipping |
Flotante | No | Coste total de envío. |
currency |
Cadena | Sí | Código ISO 4217 de tres letras. |
total_discounts |
Flotante | No | Importe total de los descuentos aplicados al pedido. |
discounts |
Matriz | No | Lista detallada de los descuentos aplicados. |
cancel_reason |
Cadena | Sí | Motivo por el que se canceló el pedido. |
products |
Matriz | Sí | Artículos del pedido cancelado. Consulta la tabla de propiedades del producto. |
source |
Cadena | Sí | Origen del evento. |
metadata |
Objeto | No | Pares clave-valor flexibles. Subpropiedad reconocida: order_status_url (Cadena). |
Propiedades del producto (products[])
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
product_id |
Cadena | Sí | Identificador único del producto. |
product_name |
Cadena | Sí | Nombre visible del producto. |
variant_id |
Cadena | Sí | Identificador de la variante. |
image_url |
Cadena | No | URL de la imagen del producto. |
product_url |
Cadena | No | URL de la página del producto. |
quantity |
Entero | Sí | Número de unidades en el pedido. |
price |
Flotante | Sí | Precio unitario de la variante. |
metadata |
Objeto | No | Pares clave-valor flexibles (por ejemplo, color o size). |
Desencadena este evento cuando se emita un reembolso total o parcial. En los reembolsos parciales, establece total_value solo en el importe reembolsado, no en el total del pedido original.
Propiedades del evento
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
order_id |
Cadena | Sí | Identificador único del pedido original. |
total_value |
Flotante | Sí | Valor monetario total del reembolso. Envía el importe absoluto (mayor o igual que 0); Braze se encarga del ajuste de ingresos. |
currency |
Cadena | Sí | Código ISO 4217 de tres letras. |
total_discounts |
Flotante | No | Importe total de los descuentos aplicados originalmente. |
discounts |
Matriz | No | Lista detallada de los descuentos. |
products |
Matriz | Sí | Artículos que se reembolsan. Consulta la tabla de propiedades del producto. |
source |
Cadena | Sí | Origen del evento. |
metadata |
Objeto | No | Pares clave-valor flexibles. Subpropiedad reconocida: order_status_url (Cadena). |
Propiedades del producto (products[])
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
product_id |
Cadena | Sí | Identificador único del producto. |
product_name |
Cadena | Sí | Nombre visible del producto. |
variant_id |
Cadena | Sí | Identificador de la variante. |
image_url |
Cadena | No | URL de la imagen del producto. |
product_url |
Cadena | No | URL de la página del producto. |
quantity |
Entero | Sí | Número de unidades reembolsadas. |
price |
Flotante | Sí | Precio unitario de la variante. |
metadata |
Objeto | No | Pares clave-valor flexibles (por ejemplo, color o size). |
Android
El SDK de Android 42.3.0+ proporciona clases tipadas de eventos de comercio electrónico. Estas clases validan los datos del lado del cliente al construir el evento y los serializan automáticamente a snake_case cuando llamas a Braze.logEcommerceEvent.
| Clase de Android | Nombre del evento | Notas |
|---|---|---|
ProductViewedEvent |
ecommerce.product_viewed |
Aplana los campos del producto al nivel superior de properties (sin array products). Admite los parámetros opcionales type (43.0.0+) y catalogName para los desencadenadores de catálogo de reposición de existencias y bajada de precio. En versiones anteriores, usa logCustomEvent o la REST API para enviar esas propiedades. |
CartUpdatedEvent |
ecommerce.cart_updated |
Usa CartUpdatedAction (ADD, REMOVE, REPLACE) para la propiedad action. |
CheckoutStartedEvent |
ecommerce.checkout_started |
|
OrderPlacedEvent |
ecommerce.order_placed |
Admite cartId, totalDiscounts y discounts opcionales. |

ecommerce.order_cancelled y ecommerce.order_refunded no están disponibles como clases tipadas del SDK de Android. Regístralos con logCustomEvent o la REST API.
Bloques de construcción compartidos
EcommerceProduct: elementos de línea para eventos de carrito, pago y pedido.- Obligatorios:
productId,productName,variantId,price,quantity(Longno negativo) - Opcionales:
imageUrl,productUrl,metadata
- Obligatorios:
BrazeProperties:metadataa nivel de evento o de producto. Las claves deben ser cadenas no vacías de al menos 255 caracteres y no pueden empezar con el signo de dólar ($).
Validación del lado del cliente
Si la carga útil no es válida, se lanza IllegalArgumentException al construir la clase del evento, por lo que el evento nunca se pone en cola. Reglas comunes:
| Campo o regla | Validación |
|---|---|
IDs y nombres de cadena (product_id, product_name, variant_id, cart_id, checkout_id, order_id, source, URLs opcionales) |
No vacíos, hasta 255 caracteres |
price, total_value, total_discounts |
Debe ser mayor o igual a 0 |
currency |
Código ISO 4217 válido (el SDK elimina los espacios y lo convierte a mayúsculas) |
products (eventos de carrito, pago y pedido) |
Al menos un EcommerceProduct |
quantity (por producto) |
Entero no negativo |
En el momento del envío, si las propiedades serializadas superan el límite de tamaño del SDK, logEcommerceEvent registra un error y no envía el evento.
Ejemplos de código
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)
Establece action con CartUpdatedAction:
| Valor | Valor en la transmisión | Descripción |
|---|---|---|
CartUpdatedAction.ADD |
add |
Aumenta la cantidad o agrega una línea. |
CartUpdatedAction.REMOVE |
remove |
Disminuye la cantidad; elimina la línea cuando llega a 0. |
CartUpdatedAction.REPLACE |
replace |
Reemplaza el carrito completo (predeterminado). |
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 no proporciona una clase tipada del SDK para este evento. Usa logCustomEvent con una carga útil que coincida con el esquema del evento 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 no proporciona una clase tipada del SDK para este evento. Usa logCustomEvent con una carga útil que coincida con el esquema del evento 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);
Establece action con CartUpdatedAction:
| Valor | Valor en la transmisión | Descripción |
|---|---|---|
CartUpdatedAction.ADD |
add |
Aumenta la cantidad o agrega una línea. |
CartUpdatedAction.REMOVE |
remove |
Disminuye la cantidad; elimina la línea cuando llega a 0. |
CartUpdatedAction.REPLACE |
replace |
Reemplaza el carrito completo (predeterminado). |
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 no proporciona una clase tipada del SDK para este evento. Usa logCustomEvent con una carga útil que coincida con el esquema del evento 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 no proporciona una clase tipada del SDK para este evento. Usa logCustomEvent con una carga útil que coincida con el esquema del evento 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
El SDK de Swift proporciona clases de eventos de comercio electrónico tipadas (ProductViewedEvent, CartUpdatedEvent, CheckoutStartedEvent y OrderPlacedEvent) que construyes y pasas a logEcommerceEvent. Usa ProductLineItem para los productos en los eventos de carrito, pago y pedido. Cada inicializador puede lanzar una excepción, así que envuélvelo en try? y registra el evento solo cuando la construcción se complete correctamente.
Esto está disponible en la versión 15.0.0 del SDK de Swift y posteriores.
ecommerce.order_cancelled y ecommerce.order_refunded no están disponibles como clases tipadas del SDK de Swift. Regístralos con logCustomEvent.
Ejemplos de código
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 no proporciona una clase tipada del SDK para este evento. Usa logCustomEvent con una carga útil que coincida con el esquema del evento 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 no proporciona una clase tipada del SDK para este evento. Usa logCustomEvent con una carga útil que coincida con el esquema del evento 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
En el SDK Web 6.8.0+, llama a logEcommerceEvent con un evento name y properties. En versiones heredadas del SDK, llama a logCustomEvent con el nombre del evento y un objeto de propiedades. ecommerce.order_cancelled y ecommerce.order_refunded usan logCustomEvent.
Ejemplos de código
En versiones más recientes del SDK, llama a 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"
}
}
});
En versiones heredadas del SDK, llama a 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"
}
});
En versiones más recientes del SDK, llama a 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": {}
}
});
En versiones heredadas del SDK, llama a 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": {}
});
En versiones más recientes del SDK, llama a 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"
}
}
});
En versiones heredadas del SDK, llama a 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"
}
});
En versiones más recientes del SDK, llama a 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"]
}
}
});
En versiones heredadas del SDK, llama a 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 usas Google Tag Manager (GTM), utiliza el tipo de etiqueta Log eCommerce Event (New) en la etiqueta Braze Actions en lugar de llamar a logEcommerceEvent() en el código de tu sitio. La etiqueta lee tu capa de datos de comercio electrónico en formato GA4 y admite los eventos ecommerce.product_viewed, ecommerce.cart_updated, ecommerce.checkout_started y ecommerce.order_placed. También admite metadatos de eventos y productos. Para registrar ecommerce.order_cancelled o ecommerce.order_refunded, utiliza una etiqueta Custom HTML que llame a braze.logCustomEvent().
Para conocer los pasos de configuración, el mapeado de campos y la solución de problemas, consulta Registrar eventos de comercio electrónico con GTM.
Registro manual con logCustomEvent
Para registrar manualmente un evento recomendado, llama a logCustomEvent con el nombre exacto del evento (por ejemplo, ecommerce.product_viewed) y una carga útil BrazeProperties o JSONObject construida manualmente. El SDK no valida los esquemas de eventos recomendados en las llamadas manuales. Braze valida estas cargas útiles durante la ingesta:
- Las cargas útiles válidas se procesan como eventos recomendados con posprocesamiento completo.
- Las cargas útiles no válidas (campos obligatorios faltantes, tipos incorrectos, propiedades adicionales de nivel superior) se descartan después de la ingesta. Los fallos aparecen en el registro de procesamiento del SDK del espacio de trabajo y en el correo electrónico de resumen de fallos.
Usa logEcommerceEvent siempre que sea posible para detectar datos no válidos antes de que salgan de la aplicación. Para el uso general de logCustomEvent, consulta Registrar eventos personalizados.