Ir al contenido

Eventos recomendados

Los eventos recomendados se basan en un marco que envía eventos personalizados estandarizados con esquemas JSON definidos. Cuando envías un evento recomendado, Braze lo valida contra su esquema en la ingesta y aplica un procesamiento especializado, como cálculos automáticos de campos o gestión del carrito, que los eventos personalizados genéricos no reciben. Para ciertos conjuntos de eventos de la industria, Braze también admite un tratamiento especial, como acciones desencadenantes basadas en acciones dedicadas para Campaigns y Canvas.

Los eventos recomendados de comercio electrónico cubren seis pasos en el recorrido de compra: product_viewed, cart_updated, checkout_started, order_placed, order_cancelled y order_refunded. Cuando envías estos eventos correctamente, Braze valida los datos y los pone a disposición de un conjunto creciente de características de la plataforma.

Estas características incluyen plantillas de Canvas para flujos de navegación abandonada, carrito abandonado, pago abandonado y confirmación de pedido; informes de comercio electrónico; y campos calculados del perfil de usuario para Ingresos totales, Pedidos totales y Reembolsos totales. También puedes crear Segments usando el filtrado de propiedades de producto anidadas a través de extensiones de segmento, personalizar mensajes de carrito abandonado con la etiqueta de Liquid {% shopping_cart %}, y alimentar las capacidades de BrazeAITM como Predictive Events, Predictive Churn y recomendaciones de artículos, junto con otras capacidades.

Dado que estos eventos siguen un esquema definido, cada característica compatible puede leer los datos estructurados sin necesidad de mapeado de propiedades personalizado ni configuración por característica de tu parte.

Cómo funcionan los eventos de comercio electrónico

Los eventos de comercio electrónico son eventos personalizados con nombres y esquemas de propiedades predefinidos. Los envías usando el SDK de Braze, el endpoint de REST API /users/track o la ingesta de datos en la nube (CDI), y Braze valida cada evento contra su esquema en la ingesta. Cuando la validación pasa, Braze aplica automáticamente un posprocesamiento específico para ese tipo de evento, como calcular campos de ingresos y gestionar el estado del carrito en los perfiles de usuario.

Los eventos de comercio electrónico funcionan en todos los lugares donde funcionan otros eventos personalizados: desencadenantes y filtros para eventos personalizados realizados, informes de eventos personalizados y más. Sin embargo, su validación de esquema desbloquea capacidades adicionales, incluyendo:

  • Acciones desencadenantes “Realiza pedido” en Campaigns, Canvas, pasos de Rutas de Acción, desencadenantes de mensajes dentro de la aplicación y eliminación de Content Cards
  • Campos calculados de comercio electrónico del perfil de usuario (Ingresos totales, Pedidos totales, Reembolsos totales)
  • Gestión del estado del carrito para flujos de carrito abandonado
  • Datos más completos para las características de BrazeAITM como Predictive Events, Predictive Churn y recomendaciones de artículos

También puedes hacer referencia a los eventos de comercio electrónico por nombre en cualquier lugar donde la plataforma admita eventos personalizados. Por ejemplo, puedes desencadenar una Campaign basada en acciones con eventos ecommerce.product_viewed, crear un Segment filtrando por eventos ecommerce.checkout_started o exportar eventos ecommerce.order_placed a través de Currents.

Nomenclatura de eventos

Los nombres de los eventos son exactos, distinguen entre mayúsculas y minúsculas, y están delimitados por puntos. Usa siempre el formato canónico. Si un nombre de evento no coincide exactamente con uno de los seis nombres canónicos, Braze lo trata como un evento personalizado estándar y no se realiza ningún posprocesamiento de comercio electrónico.

No puedes personalizar ni renombrar eventos.

  • Correcto: ecommerce.order_placed
  • Incorrecto: order.placed, eCommerce_order_placed, Order_Placed

Esquemas de eventos

Los seis eventos recomendados de comercio electrónico corresponden a etapas del recorrido de compra. Dispara cada evento en el momento en que el usuario completa la acción correspondiente.

Diagrama del recorrido del usuario a través de los seis eventos recomendados de comercio electrónico: product_viewed, cart_updated, checkout_started, order_placed, order_cancelled y order_refunded.

Se desencadena cuando un usuario visualiza la página de detalle de un producto. Este evento es compatible con las notificaciones de reposición de stock y las notificaciones de bajada de precio del catálogo de Braze.

Implementación del lado del cliente

Usa las API de eventos de comercio electrónico del SDK cuando estén disponibles. Para ejemplos de implementación específicos por plataforma, consulta Registrar eventos de comercio electrónico a través del SDK de Braze.

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 de 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 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í Fuente de la que se origina el evento (por ejemplo, web, ios o android).
type Matriz de cadenas No Obligatorio para usar las características de desencadenantes de catálogo de Braze para alertas de reposición de stock y bajada de precio. Valores aceptados: "price_drop", "back_in_stock"
metadata Objeto No Pares clave-valor flexibles (por ejemplo, category o brand).

Ejemplo de REST API




{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.product_viewed",
      "time": "2026-04-28T14:22:11Z",
      "properties": {
        "product_id": "SKU-RUN-4821",
        "product_name": "Ultraboost Running Shoe",
        "variant_id": "UB-BLK-11",
        "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
        "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
        "price": 189.99,
        "currency": "USD",
        "source": "web",
        "type": ["price_drop", "back_in_stock"],
        "metadata": {
          "category": "Running Shoes",
          "brand": "Shoe Brand"
        }
      }
    }
  ]
}

Se desencadena cada vez que cambia el contenido del carrito de un usuario.

Implementación del lado del cliente

Usa las API de eventos de comercio electrónico del SDK cuando estén disponibles. Para ejemplos de implementación específicos por plataforma, consulta Registrar eventos de comercio electrónico a través del SDK de Braze.

Puedes enviar este evento de dos maneras:

  • Reemplazo completo del carrito: Omite action o establece action en replace. Incluye el conjunto completo de artículos en products con cantidades absolutas (unidades totales por variante en el carrito). Debes incluir total_value.
  • Actualizaciones incrementales del carrito: Establece action en add o remove. Incluye solo los artículos que cambiaron. Cada quantity es el número de unidades a agregar o eliminar, no la cantidad total en el carrito. Para add, Braze incrementa la cantidad de la línea o agrega una nueva línea. Para remove, Braze disminuye la cantidad de la línea y la elimina cuando la cantidad llega a 0. total_value es opcional para add y remove.

Para desencadenar mensajería a partir de este evento, usa el desencadenante Realizar evento de carrito actualizado en Canvas y Campaigns. Este desencadenante incluye un manejo especial para evitar que el carrito avance por el embudo de compra.

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.
action Cadena No add (incrementar cantidad o agregar una línea), remove (decrementar cantidad; la línea se elimina en 0) o replace (reemplazo completo del carrito, igual que omitir action).
total_value Flotante Condicional Obligatorio cuando se omite action o es replace. Opcional cuando action es add o remove.
subtotal_value Flotante No Valor del subtotal del carrito (después del descuento, antes de impuestos/envío).
tax Flotante No Impuesto total aplicado al carrito.
shipping Flotante No Costo total de envío del carrito.
currency Cadena Sí Código ISO 4217 de tres letras.
products Matriz Sí Artículos de esta actualización. Para reemplazo completo (sin action o replace), incluye el carrito completo con cantidades absolutas. Para add o remove, incluye solo las líneas modificadas; consulta las propiedades de producto.
source Cadena Sí Fuente de la que se origina el evento.
metadata Objeto No Pares clave-valor flexibles para datos adicionales a nivel de evento.

Propiedades de 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í Para reemplazo completo (sin action o replace), unidades en el carrito para esta línea. Para add o remove, cuántas unidades agregar o eliminar.
price Flotante Sí Precio unitario de la variante.
metadata Objeto No Pares clave-valor flexibles (por ejemplo, color o size).

Se desencadena cuando el usuario inicia el flujo de pago (por ejemplo, selecciona “Pagar” o llega a la página de pago).

Implementación del lado del cliente

Usa las API de eventos de comercio electrónico del SDK cuando estén disponibles. Para ejemplos de implementación específicos por plataforma, consulta Registrar eventos de comercio electrónico a través del SDK de Braze.

Propiedades del evento

Propiedad Tipo 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 del subtotal (después del descuento, antes de impuestos/envío).
tax Flotante No Impuesto total aplicado al pago.
shipping Flotante No Costo 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 subtabla de propiedades de producto.
source Cadena Sí Fuente de la que se origina el evento.
metadata Objeto No Pares clave-valor flexibles. Subpropiedad reconocida: checkout_url (cadena)

Propiedades de 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, tamaño).

Ejemplo de REST API




{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.checkout_started",
      "time": "2026-04-28T14:30:05Z",
      "properties": {
        "checkout_id": "chk_88291",
        "cart_id": "cart_abc123",
        "total_value": 234.96,
        "subtotal_value": 219.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
            "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "checkout_url": "https://www.example.com/checkout/chk_88291",
          "checkout_type": "express"
        }
      }
    }
  ]
}

Se desencadena cuando un pedido se completa correctamente o se confirma el pago.

Implementación del lado del cliente

Usa las API de eventos de comercio electrónico del SDK cuando estén disponibles. Para ejemplos de implementación específicos por plataforma, consulta Registrar eventos de comercio electrónico a través del SDK de Braze.

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 del subtotal (después del descuento, antes de impuestos/envío).
tax Flotante No Impuesto total aplicado al pedido.
shipping Flotante No Costo total de envío.
currency Cadena Sí Código ISO 4217 de tres letras.
total_discounts Flotante No Monto total de descuentos aplicados al pedido.
discounts Matriz No Lista detallada de descuentos aplicados.
products Matriz Sí Artículos del pedido. Consulta la subtabla de propiedades de producto.
source Cadena Sí Fuente de la que se origina el evento.
metadata Objeto No Pares clave-valor flexibles. Subpropiedad reconocida: order_status_url (cadena)

Propiedades de 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).

Ejemplo de REST API




{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_placed",
      "time": "2026-04-28T14:35:42Z",
      "properties": {
        "order_id": "ord_77821",
        "cart_id": "cart_abc123",
        "total_value": 224.96,
        "subtotal_value": 209.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "total_discounts": 10.0,
        "discounts": [
          {
            "code": "SPRING10",
            "amount": 10.0,
            "type": "percentage"
          }
        ],
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
            "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}

Se desencadena cuando se cancela un pedido.

Implementación del lado del cliente

Usa logCustomEvent. Para ejemplos de implementación específicos por plataforma, consulta Registrar eventos de comercio electrónico a través del SDK de Braze.

Propiedades del evento

Propiedad Tipo Obligatorio Descripción
order_id Cadena Sí Identificador único del pedido.
total_value Flotante Sí Valor monetario total del pedido que se cancela. Debe ser ≥ 0: envía el monto absoluto; Braze se encarga del decremento.
subtotal_value Flotante No Valor del subtotal (después del descuento, antes de impuestos/envío).
tax Flotante No Impuesto total aplicado al pedido.
shipping Flotante No Costo total de envío.
currency Cadena Sí Código ISO 4217 de tres letras.
total_discounts Flotante No Monto total de descuentos aplicados al pedido.
discounts Matriz No Lista detallada de descuentos aplicados.
cancel_reason Cadena Sí Motivo de la cancelación del pedido.
products Matriz Sí Artículos del pedido cancelado. Consulta la subtabla de propiedades de producto.
source Cadena Sí Fuente de la que se origina el evento.
metadata Objeto No Pares clave-valor flexibles. Subpropiedad reconocida: order_status_url (cadena)

Propiedades de 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).

Ejemplo de REST API




{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_cancelled",
      "time": "2026-04-28T16:10:00Z",
      "properties": {
        "order_id": "ord_77821",
        "total_value": 224.96,
        "subtotal_value": 209.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "total_discounts": 10.0,
        "cancel_reason": "customer_request",
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}

Se desencadena cuando se emite un reembolso total o parcial.

Implementación del lado del cliente

Usa logCustomEvent. Para ejemplos de implementación específicos por plataforma, consulta Registrar eventos de comercio electrónico a través del SDK de Braze.

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. Debe ser ≥ 0: envía el monto absoluto; Braze se encarga del incremento a total_refunds.
currency Cadena Sí Código ISO 4217 de tres letras.
total_discounts Flotante No Monto total de descuentos aplicados originalmente.
discounts Matriz No Lista detallada de descuentos.
products Matriz Sí Artículos que se reembolsan. Consulta la subtabla de propiedades de producto.
source Cadena Sí Fuente de la que se origina el evento.
metadata Objeto No Pares clave-valor flexibles. Subpropiedad reconocida: order_status_url (cadena).

Propiedades de 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).

Ejemplos de REST API




{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_refunded",
      "time": "2026-04-29T10:05:00Z",
      "properties": {
        "order_id": "ord_77821",
        "total_value": 189.99,
        "currency": "USD",
        "total_discounts": 0,
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11",
              "refund_reason": "size_mismatch"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}






{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_refunded",
      "time": "2026-05-02T11:08:30Z",
      "properties": {
        "order_id": "ORD-20260428-7891",
        "total_value": 29.98,
        "currency": "USD",
        "products": [
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "refund_method": "store_credit",
          "initiated_by": "customer"
        }
      }
    }
  ]
}

Posprocesamiento de eventos de comercio electrónico

Cuando envías un evento de comercio electrónico, Braze lo valida contra el esquema esperado para ese nombre de evento.

La siguiente tabla resume lo que Braze hace automáticamente para cada evento cuando la validación pasa. Para saber qué sucede cuando la validación falla, consulta Validación de eventos y solución de problemas.

Evento Lo que Braze hace automáticamente
ecommerce.order_placed Incrementa Ingresos totales en total_value y Pedidos totales en 1 en el perfil de usuario.
ecommerce.order_cancelled Decrementa Pedidos totales en 1.
ecommerce.order_refunded Decrementa Ingresos totales en total_value e incrementa Valor total de reembolsos.
ecommerce.cart_updated Crea o actualiza el objeto de mapeado de carritos en el perfil de usuario (cargas útiles de carrito completas o actualizaciones incrementales del carrito con action opcional: add, remove o replace). El carrito expira después de 30 días sin una actualización.
ecommerce.product_viewed Sin cambios en el perfil de usuario. Disponible para segmentación, desencadenantes y características de BrazeAITM (como recomendaciones de artículos).
ecommerce.checkout_started Sin cambios en el perfil de usuario. Disponible para segmentación y desencadenantes (por ejemplo, flujos de pago abandonado).

Detalles de implementación

Puntos de datos y facturación

Los eventos de comercio electrónico no consumen puntos de datos. Puedes registrarlos sin que haya impacto en tu uso de puntos de datos.

Límite de tamaño de eventos

Las propiedades de eventos enviadas a /users/track tienen un límite de 102.400 bytes (100 KB) por evento. Para los mensajes de Campaign y Canvas desencadenados, las trigger_properties enviadas a /campaigns/trigger/send y /canvas/trigger/send tienen un límite predeterminado más estricto de 51.200 bytes (50 KB).

Como práctica recomendada, envía solo la información de producto que necesites para desencadenar, personalizar o atribuir el evento. Almacena los detalles más completos del producto, como descripciones, listas completas de variantes, inventario o imágenes alternativas, en los catálogos de Braze. Haz referencia a estos detalles mediante product_id o variant_id al enviar mensajes. Utiliza el objeto metadata de forma selectiva para el contexto específico del pedido o producto que la mensajería vaya a usar.

Manejo de divisas

Braze convierte automáticamente los valores de divisas que no sean USD a USD utilizando el tipo de cambio de la fecha en que se reporta el evento. Este valor convertido es el que aparece en las métricas de ingresos.

Campo source

La propiedad source es una cadena obligatoria que identifica de dónde se originó el evento. Por ejemplo, shopify, in-store POS o custom_api. Esto te ayuda a distinguir las fuentes de integración al analizar datos en las exportaciones de Currents o al depurar problemas de validación.

Flexibilidad de metadata

Tanto el objeto de metadata a nivel de evento como el de nivel de producto aceptan pares clave-valor arbitrarios, de modo que puedes adjuntar dimensiones personalizadas sin modificar el esquema base. Algunos ejemplos comunes incluyen order_status_url, gift_wrapped, loyalty_points_earned o warehouse_id. Estas propiedades están disponibles en la personalización con Liquid, las exportaciones de Currents y la segmentación a través de las extensiones de segmento.

Validación de eventos y solución de problemas

Cuando envías un evento de comercio electrónico recomendado a través de /users/track o cualquier SDK de Braze, Braze valida la carga útil contra el esquema JSON del evento durante el procesamiento del evento recomendado. La validación se ejecuta automáticamente en cada evento cuyo nombre coincide exactamente con un evento recomendado (por ejemplo, ecommerce.order_placed o ecommerce.cart_updated).

Qué validamos

Para cada evento cuyo nombre coincide con un evento de comercio electrónico recomendado, Braze verifica:

Verificación Ejemplo
Nombre del evento Debe ser exacto. Por ejemplo, ecommerce.cart_updated es correcto, no ecommerce.Cart_Updated, cartupdated ni cart_updated.
Propiedades obligatorias presentes order_placed requiere order_id, total_value, currency, products y source.
Tipos de datos correctos total_value debe ser un número; currency debe ser una cadena; products debe ser una matriz.
Sin propiedades adicionales de nivel superior Los campos personalizados en properties provocan un fallo. Usa el objeto metadata en su lugar.
Restricciones de valores Los campos monetarios deben ser ≥ 0. currency debe ser una cadena ISO 4217 válida.
Campos por producto Cada elemento en products[] debe incluir product_id, product_name, variant_id, quantity y price.

Por qué validamos

Los eventos de comercio electrónico impulsan características que dependen de datos consistentes y predecibles, incluyendo el seguimiento de ingresos, la etiqueta de Liquid {% shopping_cart %}, el desencadenante de carrito abandonado y los informes. Cuando las cargas útiles se desvían del esquema, estas características producen imprecisiones silenciosas (totales de ingresos incorrectos, carritos faltantes, desencadenantes rotos). La validación aplica el contrato de antemano para que las características posteriores se comporten de manera predecible.

Cuando la validación es exitosa

El evento se procesa como un evento de comercio electrónico recomendado con todo el posprocesamiento asociado. Consulta Eventos de comercio electrónico recomendados para la lista completa de comportamientos desencadenados por cada tipo de evento.

Verificar un evento exitoso

Después de enviar un evento, puedes confirmar que fue aceptado y procesado correctamente usando cualquiera de los siguientes métodos:

  • Registro de usuarios del evento: abre el perfil del usuario en el panel y revisa su actividad. Los eventos recomendados aparecen con su carga útil completa de propiedades, para que puedas confirmar que el evento llegó y los valores coinciden con lo que enviaste.
  • Informe de eventos personalizados: ve a Analytics > Custom Events Report para ver los recuentos agregados de cada evento recomendado a lo largo del tiempo. Esto es útil para confirmar que el tráfico de producción fluye como se espera cuando tu integración está activa.
  • Usuarios de prueba: marca a un usuario en tu espacio de trabajo de desarrollo como usuario de prueba, luego desencadena eventos desde tu integración contra ese usuario. Los usuarios de prueba están marcados en el panel, lo que facilita aislar e inspeccionar el comportamiento de extremo a extremo.

Cuando la validación falla

El evento no se procesa como un evento recomendado. Específicamente:

  • El evento se descarta por completo. Los eventos de comercio electrónico recomendados no válidos no se registran en el perfil del usuario, no aparecen en Currents y no están disponibles para segmentación.
  • Las características posteriores de eventos recomendados no se ejecutan, incluyendo:
    • Seguimiento de ingresos (informes de ingresos, campos calculados de usuario como total_revenue)
    • Actualizaciones del objeto de carrito en el perfil del usuario
    • Desencadenantes de Update Cart o Place Order en Canvas y Campaigns

La forma en que se reportan los errores depende de la ruta de ingesta:

  • REST API (/users/track): Cada evento no válido se reporta en la matriz de errores de la respuesta. Cada entrada te indica qué evento falló (índice) y por qué (tipo). El campo de mensaje de nivel superior sigue diciendo “success”, lo que solo significa que tu solicitud llegó a Braze, no que cada evento fuera válido. Siempre verifica si hay una matriz de errores en la respuesta.
  • SDK de Braze: Las llamadas del SDK devuelven inmediatamente y la validación se ejecuta en segundo plano, por lo que los errores no se envían de vuelta a tu aplicación. Para conocer los fallos de validación de eventos de comercio electrónico, presta atención al correo electrónico de resumen de fallos (consulta Encontrar fallos).

Ejemplo de respuesta de error de API

El endpoint /users/track devuelve errores a nivel de campo que indican qué propiedades fallaron y por qué. Ten en cuenta que el message de nivel superior puede devolver "success" porque el evento fue aceptado en la canalización; la matriz errors te indica qué campos fallaron en la validación del esquema. Consulta el siguiente ejemplo de respuesta de error.




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

Los fallos también se clasifican internamente y se agregan para el correo electrónico de resumen de fallos:

Tipo de fallo Significado Ejemplo
missing_property Un campo obligatorio está ausente. order_placed enviado sin order_id.
extra_property Se añadió un campo que el esquema no define. Un campo personalizado gift_wrapped en el nivel superior de properties en lugar de dentro de metadata.
unexpected_data_type Un campo tiene el tipo incorrecto. total_value: "29.99" (cadena) en lugar de 29.99 (número).

Encontrar fallos

Braze envía por correo electrónico a los administradores de tu espacio de trabajo un resumen de los fallos de validación de eventos recomendados para que puedas identificar y corregir problemas de integración sin monitorear manualmente cada evento.

El correo electrónico de resumen incluye:

  • Recuento total de errores: Recuentos de errores para el período de reporte.
  • Errores por evento: Un desglose de cuántos eventos fallaron para cada tipo de evento recomendado (por ejemplo, ecommerce.cart_updated y ecommerce.order_placed). Usa esto para identificar qué eventos de tu integración necesitan atención primero.
  • Errores por origen: Una división entre API y SDK, para que puedas señalar qué integración está generando los fallos.

Si no estás recibiendo estos correos electrónicos o deseas verificar la lista de destinatarios, contacta a tu equipo de cuenta de Braze.

Diagnosticar y corregir fallos

Cuando recibas un correo electrónico de resumen de fallos:

  1. Identifica el evento que falla y su origen. El correo electrónico separa los fallos por nombre de evento y origen de integración (sdk versus rest_api), para que puedas señalar qué integración necesita la corrección. Si tienes múltiples orígenes enviando el mismo evento (por ejemplo, el SDK de tu tienda y un webhook de backend que envían ambos cart_updated), abórdalos de forma independiente.
  2. Compara tu carga útil con el esquema en Esquemas de eventos. La mayoría de los fallos caen en uno de tres patrones:
    • missing_property: un campo obligatorio está ausente. Para solucionarlo, agrega el campo obligatorio.
    • extra_property: un campo personalizado está en el nivel superior de properties. Para solucionarlo, mueve el campo personalizado dentro de metadata (a nivel de evento) o products[].metadata (por producto).
    • unexpected_data_type: un valor tiene el tipo incorrecto (por ejemplo, total_value enviado como cadena). Para solucionarlo, convierte el valor antes de enviarlo.
  3. Prueba la carga útil corregida en un espacio de trabajo de desarrollo antes de implementarla en producción. Envía un evento de prueba conocido para un usuario de prueba, luego verifica el comportamiento esperado del evento recomendado en el perfil de ese usuario (por ejemplo, que el objeto de carrito se actualice, los ingresos se incrementen o el desencadenante de carrito abandonado se active).
  4. Monitorea el siguiente correo electrónico de fallos para confirmar que el recuento de fallos para ese evento, origen y tipo baje a cero.

Para los requisitos completos de propiedades por evento, consulta Esquemas de eventos.

Documentación de la plataforma de interacción con el cliente de Braze.

Recursos
Legal
Empresa
© 2026 Braze, Inc. Todos los derechos reservados.
Verificación del estado de Braze
New Stuff!