Ir al contenido

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.

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.

Bloques de construcción compartidos

  • EcommerceProduct: elementos de línea para eventos de carrito, pago y pedido.
    • Obligatorios: productId, productName, variantId, price, quantity (Long no negativo)
    • Opcionales: imageUrl, productUrl, metadata
  • BrazeProperties: metadata a 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.

New Stuff!