Ir para o conteúdo

Eventos recomendados

Os eventos recomendados são construídos sobre um framework que envia eventos personalizados padronizados com esquemas JSON definidos. Quando você envia um evento recomendado, a Braze o valida em relação ao seu esquema na ingestão e aplica processamento especializado, como cálculos automáticos de campos ou gerenciamento de carrinho, que eventos personalizados genéricos não recebem. Para determinados conjuntos de eventos do setor, a Braze também oferece tratamento especial, como gatilhos dedicados baseados em ação para Campaigns e Canvas.

Eventos recomendados de eCommerce abrangem seis etapas na jornada de compra: product_viewed, cart_updated, checkout_started, order_placed, order_cancelled e order_refunded. Quando você envia esses eventos com sucesso, a Braze valida os dados e os disponibiliza para um conjunto crescente de recursos da plataforma.

Esses recursos incluem modelos de Canvas para fluxos de navegação abandonada, carrinho abandonado, checkout abandonado e confirmação de pedido; relatórios de eCommerce; e campos calculados no perfil do usuário para Receita Total, Pedidos Totais e Reembolsos Totais. Você também pode criar Segments usando filtragem de propriedades de produto aninhadas por meio de extensões de segmento, personalizar mensagens de carrinho abandonado com a Liquid tag {% shopping_cart %} e alimentar recursos de BrazeAITM como Eventos Preditivos, Churn Preditivo e recomendação de itens, além de outros recursos.

Como esses eventos seguem um esquema definido, cada recurso suportado pode ler os dados estruturados sem mapeamento personalizado de propriedades ou configuração por recurso da sua parte.

Como os eventos de eCommerce funcionam

Os eventos de eCommerce são eventos personalizados com nomes e esquemas de propriedades predefinidos. Você os envia usando o SDK da Braze, o endpoint /users/track da REST API ou a Ingestão de Dados na Nuvem (CDI), e a Braze valida cada evento em relação ao seu esquema na ingestão. Quando a validação é aprovada, a Braze aplica automaticamente o pós-processamento específico para aquele tipo de evento, como calcular campos de receita e gerenciar o estado do carrinho nos perfis de usuário.

Os eventos de eCommerce funcionam em todos os lugares onde outros eventos personalizados funcionam: gatilhos e filtros para eventos personalizados realizados, relatórios de eventos personalizados e muito mais. No entanto, a validação de esquema desbloqueia recursos adicionais, incluindo:

  • Ações-gatilho “Realiza pedido” em Campaigns, Canvas, jornadas de ação, gatilhos de mensagens no app e remoção de Content Cards
  • Campos calculados de eCommerce no perfil do usuário (Receita Total, Pedidos Totais, Reembolsos Totais)
  • Gerenciamento de estado do carrinho para fluxos de carrinho abandonado
  • Dados mais ricos para recursos de BrazeAITM como Eventos Preditivos, Churn Preditivo e recomendação de itens

Você também pode referenciar eventos de eCommerce pelo nome em qualquer lugar onde a plataforma suporte eventos personalizados. Por exemplo, você pode disparar uma Campaign baseada em ação com eventos ecommerce.product_viewed, criar um Segment filtrando por eventos ecommerce.checkout_started ou exportar eventos ecommerce.order_placed pelo Currents.

Nomenclatura de eventos

Os nomes dos eventos são exatos, diferenciam maiúsculas de minúsculas e são delimitados por ponto. Sempre use o formato canônico. Se um nome de evento não corresponder exatamente a um dos seis nomes canônicos, a Braze o trata como um evento personalizado padrão e nenhum pós-processamento de eCommerce ocorre.

Você não pode personalizar ou renomear eventos.

  • Correto: ecommerce.order_placed
  • Incorreto: order.placed, eCommerce_order_placed, Order_Placed

Esquemas de eventos

Os seis eventos recomendados de eCommerce correspondem a estágios da jornada de compra. Dispare cada evento no momento em que o usuário concluir a ação correspondente.

Diagrama da jornada do usuário por todos os seis eventos recomendados de eCommerce: product_viewed, cart_updated, checkout_started, order_placed, order_cancelled e order_refunded.

Dispare quando um usuário visualizar uma página de detalhes do produto. Esse evento é compatível com notificações de volta ao estoque e notificações de queda de preço de catálogos da Braze.

Implementação no lado do cliente

Use as APIs de eventos de eCommerce do SDK quando disponíveis. Para exemplos de implementação específicos por plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

Propriedades do evento

Nome da propriedade Tipo de dados Obrigatória Descrição
product_id String Sim Identificador exclusivo do produto (por exemplo, SKU ou ID do item).
product_name String Sim Nome de exibição do produto.
variant_id String Sim Identificador da variante do produto (por exemplo, shirt_medium_blue).
image_url String Não URL da imagem do produto.
product_url String Não URL da página do produto para mais detalhes.
price Float Sim Preço unitário da variante no momento da visualização.
currency String Sim Código de três letras ISO 4217 (por exemplo, USD ou EUR).
source String Sim Origem do evento (por exemplo, web, ios ou android).
type Array de strings Não Obrigatório para usar os recursos de gatilho de catálogo da Braze para alertas de volta ao estoque e queda de preço. Valores aceitos: "price_drop", "back_in_stock"
metadata Object Não Pares chave-valor flexíveis (por exemplo, category ou brand).

Exemplo da 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"
        }
      }
    }
  ]
}

Dispare toda vez que o conteúdo do carrinho de um usuário mudar.

Implementação no lado do cliente

Use as APIs de eventos de eCommerce do SDK quando disponíveis. Para exemplos de implementação específicos por plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

Você pode enviar este evento de duas formas:

  • Substituição total do carrinho: Omita action ou defina action como replace. Inclua o conjunto completo de itens de linha em products com quantidades absolutas (total de unidades por variante no carrinho). Você precisa incluir total_value.
  • Atualizações incrementais do carrinho: Defina action como add ou remove. Inclua apenas os itens de linha que mudaram. Cada quantity é o número de unidades a adicionar ou remover, não a quantidade total no carrinho. Para add, a Braze aumenta a quantidade da linha ou adiciona uma nova linha. Para remove, a Braze diminui a quantidade da linha e remove a linha quando a quantidade chega a 0. total_value é opcional para add e remove.

Para disparar mensagens a partir deste evento, use o gatilho Realizar evento de carrinho atualizado em Canvas e Campaigns. Esse gatilho inclui tratamento especial para impedir que o carrinho progrida pelo funil de compra.

Propriedades do evento

Propriedade Tipo de dados Obrigatória Descrição
cart_id String Sim Identificador exclusivo do carrinho. Compartilhado entre eventos de carrinho, checkout e pedido para o mapeamento de carrinho do usuário.
action String Não add (incrementar quantidade ou adicionar uma linha), remove (decrementar quantidade; linha removida em 0) ou replace (substituição total do carrinho, igual a omitir action).
total_value Float Condicional Obrigatória quando action é omitido ou replace. Opcional quando action é add ou remove.
subtotal_value Float Não Valor subtotal do carrinho (pós-desconto, pré-imposto/frete).
tax Float Não Imposto total aplicado ao carrinho.
shipping Float Não Custo total de frete do carrinho.
currency String Sim Código de três letras ISO 4217.
products Array Sim Itens de linha para esta atualização. Para substituição total (sem action ou replace), inclua o carrinho completo com quantidades absolutas. Para add ou remove, inclua apenas as linhas alteradas; veja propriedades do produto.
source String Sim Origem do evento.
metadata Object Não Pares chave-valor flexíveis para dados adicionais no nível do evento.

Propriedades do produto (products[])

Propriedade Tipo de dados Obrigatória Descrição
product_id String Sim Identificador exclusivo do produto.
product_name String Sim Nome de exibição do produto.
variant_id String Sim Identificador da variante.
image_url String Não URL da imagem do produto.
product_url String Não URL da página do produto.
quantity Integer Sim Para substituição total (sem action ou replace), unidades no carrinho para esta linha. Para add ou remove, quantas unidades adicionar ou remover.
price Float Sim Preço unitário da variante.
metadata Object Não Pares chave-valor flexíveis (por exemplo, color ou size).

Dispare quando o usuário iniciar o fluxo de checkout (por exemplo, selecionar “Finalizar compra” ou acessar a página de checkout).

Implementação no lado do cliente

Use as APIs de eventos de eCommerce do SDK quando disponíveis. Para exemplos de implementação específicos por plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

Propriedades do evento

Propriedade Tipo Obrigatória Descrição
checkout_id String Sim Identificador exclusivo da sessão de checkout.
cart_id String Não Identificador do carrinho. Compartilhado entre eventos de carrinho, checkout e pedido para o mapeamento de carrinho do usuário.
total_value Float Sim Valor monetário total do checkout.
subtotal_value Float Não Valor subtotal (pós-desconto, pré-imposto/frete).
tax Float Não Imposto total aplicado ao checkout.
shipping Float Não Custo total de frete.
currency String Sim Código de três letras ISO 4217.
products Array Sim Itens sendo finalizados. Veja a subtabela de propriedades do produto.
source String Sim Origem do evento.
metadata Object Não Pares chave-valor flexíveis. Subpropriedade reconhecida: checkout_url (String)

Propriedades do produto (products[])

Propriedade Tipo de dados Obrigatória Descrição
product_id String Sim Identificador exclusivo do produto.
product_name String Sim Nome de exibição do produto.
variant_id String Sim Identificador da variante.
image_url String Não URL da imagem do produto.
product_url String Não URL da página do produto.
quantity Integer Sim Número de unidades no carrinho.
price Float Sim Preço unitário da variante.
metadata Object Não Pares chave-valor flexíveis (por exemplo, cor, tamanho).

Exemplo da 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"
        }
      }
    }
  ]
}

Dispare quando um pedido for concluído com sucesso ou o pagamento for confirmado.

Implementação no lado do cliente

Use as APIs de eventos de eCommerce do SDK quando disponíveis. Para exemplos de implementação específicos por plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

Propriedades do evento

Propriedade Tipo de dados Obrigatória Descrição
order_id String Sim Identificador exclusivo do pedido.
cart_id String Não Identificador do carrinho. Compartilhado entre eventos de carrinho, checkout e pedido para o mapeamento de carrinho do usuário.
total_value Float Sim Valor monetário total do pedido.
subtotal_value Float Não Valor subtotal (pós-desconto, pré-imposto/frete).
tax Float Não Imposto total aplicado ao pedido.
shipping Float Não Custo total de frete.
currency String Sim Código de três letras ISO 4217.
total_discounts Float Não Valor total de descontos aplicados ao pedido.
discounts Array Não Lista detalhada de descontos aplicados.
products Array Sim Itens no pedido. Veja a subtabela de propriedades do produto.
source String Sim Origem do evento.
metadata Object Não Pares chave-valor flexíveis. Subpropriedade reconhecida: order_status_url (String)

Propriedades do produto (products[])

Propriedade Tipo de dados Obrigatória Descrição
product_id String Sim Identificador exclusivo do produto.
product_name String Sim Nome de exibição do produto.
variant_id String Sim Identificador da variante.
image_url String Não URL da imagem do produto.
product_url String Não URL da página do produto.
quantity Integer Sim Número de unidades no carrinho.
price Float Sim Preço unitário da variante.
metadata Object Não Pares chave-valor flexíveis (por exemplo, color ou size).

Exemplo da 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"
        }
      }
    }
  ]
}

Dispare quando um pedido for cancelado.

Implementação no lado do cliente

Use logCustomEvent. Para exemplos de implementação específicos por plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

Propriedades do evento

Propriedade Tipo Obrigatória Descrição
order_id String Sim Identificador exclusivo do pedido.
total_value Float Sim Valor monetário total do pedido sendo cancelado. Deve ser ≥ 0 — envie o valor absoluto; a Braze cuida do decremento.
subtotal_value Float Não Valor subtotal (pós-desconto, pré-imposto/frete).
tax Float Não Imposto total aplicado ao pedido.
shipping Float Não Custo total de frete.
currency String Sim Código de três letras ISO 4217.
total_discounts Float Não Valor total de descontos aplicados ao pedido.
discounts Array Não Lista detalhada de descontos aplicados.
cancel_reason String Sim Motivo do cancelamento do pedido.
products Array Sim Itens no pedido cancelado. Veja a subtabela de propriedades do produto.
source String Sim Origem do evento.
metadata Object Não Pares chave-valor flexíveis. Subpropriedade reconhecida: order_status_url (String)

Propriedades do produto (products[])

Propriedade Tipo de dados Obrigatória Descrição
product_id String Sim Identificador exclusivo do produto.
product_name String Sim Nome de exibição do produto.
variant_id String Sim Identificador da variante.
image_url String Não URL da imagem do produto.
product_url String Não URL da página do produto.
quantity Integer Sim Número de unidades no carrinho.
price Float Sim Preço unitário da variante.
metadata Object Não Pares chave-valor flexíveis (por exemplo, color ou size).

Exemplo da 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"
        }
      }
    }
  ]
}

Dispare quando um reembolso total ou parcial for emitido.

Implementação no lado do cliente

Use logCustomEvent. Para exemplos de implementação específicos por plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

Propriedades do evento

Propriedade Tipo de dados Obrigatória Descrição
order_id String Sim Identificador exclusivo do pedido original.
total_value Float Sim Valor monetário total do reembolso. Deve ser ≥ 0 — envie o valor absoluto; a Braze cuida do incremento de total_refunds.
currency String Sim Código de três letras ISO 4217.
total_discounts Float Não Valor total de descontos originalmente aplicados.
discounts Array Não Lista detalhada de descontos.
products Array Sim Itens sendo reembolsados. Veja a subtabela de propriedades do produto.
source String Sim Origem do evento.
metadata Object Não Pares chave-valor flexíveis. Subpropriedade reconhecida: order_status_url (String).

Propriedades do produto (products[])

Propriedade Tipo de dados Obrigatória Descrição
product_id String Sim Identificador exclusivo do produto.
product_name String Sim Nome de exibição do produto.
variant_id String Sim Identificador da variante.
image_url String Não URL da imagem do produto.
product_url String Não URL da página do produto.
quantity Integer Sim Número de unidades no carrinho.
price Float Sim Preço unitário da variante.
metadata Object Não Pares chave-valor flexíveis (por exemplo, color ou size).

Exemplos da 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"
        }
      }
    }
  ]
}

Pós-processamento de eventos de eCommerce

Quando você envia um evento de eCommerce, a Braze o valida em relação ao esquema esperado para aquele nome de evento.

A tabela a seguir resume o que a Braze faz automaticamente para cada evento quando a validação é aprovada. Para saber o que acontece quando a validação falha, consulte Validação de eventos e solução de problemas.

Evento O que a Braze faz automaticamente
ecommerce.order_placed Incrementa Receita Total por total_value e Pedidos Totais em 1 no perfil do usuário.
ecommerce.order_cancelled Decrementa Pedidos Totais em 1.
ecommerce.order_refunded Decrementa Receita Total por total_value e incrementa Valor Total de Reembolsos.
ecommerce.cart_updated Cria ou atualiza o objeto de mapeamento de carrinhos no perfil do usuário (cargas úteis de carrinho completas ou atualizações incrementais de carrinho com action opcional: add, remove ou replace). O carrinho expira após 30 dias sem atualização.
ecommerce.product_viewed Sem alterações no perfil do usuário. Disponível para segmentação, gatilhos e recursos de BrazeAITM (como recomendação de itens).
ecommerce.checkout_started Sem alterações no perfil do usuário. Disponível para segmentação e gatilhos (por exemplo, fluxos de checkout abandonado).

Detalhes de implementação

Pontos de dados e cobrança

Os eventos de eCommerce não consomem pontos de dados. Você pode registrá-los sem nenhum impacto no seu uso de pontos de dados.

Limite de tamanho do evento

As propriedades de evento enviadas para /users/track são limitadas a 102.400 bytes (100 KB) por evento. Para mensagens disparadas de Campaign e Canvas, as trigger_properties enviadas para /campaigns/trigger/send e /canvas/trigger/send têm um limite padrão mais restrito de 51.200 bytes (50 KB).

Como prática recomendada, envie apenas as informações de produto necessárias para disparar, personalizar ou atribuir o evento. Armazene detalhes mais completos do produto — como descrições, listas completas de variantes, estoque ou imagens alternativas — nos Catálogos da Braze. Faça referência a esses detalhes por product_id ou variant_id ao enviar mensagens. Use o objeto metadata de forma seletiva para contexto específico de pedido ou produto que o envio de mensagens utilizará.

Tratamento de moeda

A Braze converte automaticamente valores em moedas diferentes de USD para USD usando a taxa de câmbio da data em que o evento foi registrado. Esse valor convertido é o que aparece nas métricas de receita.

Campo source

A propriedade source é uma string obrigatória que identifica de onde o evento se originou. Por exemplo, shopify, in-store POS ou custom_api. Isso ajuda a distinguir fontes de integração ao analisar dados em exportações do Currents ou ao depurar problemas de validação.

Flexibilidade de metadata

Tanto o objeto metadata no nível do evento quanto no nível do produto aceitam pares arbitrários de chave-valor, permitindo que você adicione dimensões personalizadas sem modificar o esquema principal. Exemplos comuns incluem order_status_url, gift_wrapped, loyalty_points_earned ou warehouse_id. Essas propriedades estão disponíveis na personalização com Liquid, nas exportações do Currents e na segmentação por meio de extensões de segmento.

Validação de eventos e solução de problemas

Quando você envia um evento recomendado de eCommerce por meio de /users/track ou de qualquer SDK da Braze, a Braze valida a carga útil com base no esquema JSON do evento durante o processamento do evento recomendado. A validação é executada automaticamente em todos os eventos cujo nome corresponde exatamente a um evento recomendado (por exemplo, ecommerce.order_placed ou ecommerce.cart_updated).

O que é validado

Para cada evento cujo nome corresponde a um evento recomendado de eCommerce, a Braze verifica:

Verificação Exemplo
Nome do evento Deve ser exato. Por exemplo, ecommerce.cart_updated está correto — não ecommerce.Cart_Updated, cartupdated ou cart_updated.
Propriedades obrigatórias presentes order_placed exige order_id, total_value, currency, products e source.
Tipos de dados corretos total_value deve ser um número; currency deve ser uma string; products deve ser um array.
Sem propriedades extras no nível superior Campos personalizados em properties causam falha. Use o objeto metadata no lugar.
Restrições de valor Campos monetários devem ser ≥ 0. currency deve ser uma string ISO 4217 válida.
Campos por produto Cada item em products[] deve incluir product_id, product_name, variant_id, quantity e price.

Por que validamos

Eventos de eCommerce alimentam recursos que dependem de dados consistentes e previsíveis, incluindo rastreamento de receita, a tag Liquid {% shopping_cart %}, o disparo de carrinho abandonado e relatórios. Quando as cargas úteis divergem do esquema, esses recursos produzem imprecisões silenciosas (totais de receita incorretos, carrinhos ausentes, disparos quebrados). A validação aplica o contrato antecipadamente para que os recursos a jusante se comportem de forma previsível.

Quando a validação é bem-sucedida

O evento é processado como um evento recomendado de eCommerce com todo o pós-processamento associado. Consulte Eventos recomendados de eCommerce para a lista completa de comportamentos disparados por cada tipo de evento.

Verificar um evento bem-sucedido

Depois de enviar um evento, você pode confirmar que ele foi aceito e processado corretamente usando qualquer uma das opções a seguir:

  • Registro de usuários de eventos: Abra o perfil do usuário no dashboard e revise a atividade dele. Eventos recomendados aparecem com a carga útil completa das propriedades, então você pode confirmar que o evento foi registrado e que os valores correspondem ao que você enviou.
  • Relatório de eventos personalizados: Acesse Analytics > Custom Events Report para ver contagens agregadas de cada evento recomendado ao longo do tempo. Isso é útil para confirmar que o tráfego de produção está fluindo conforme esperado quando sua integração está ativa.
  • Usuários teste: Marque um usuário no seu espaço de trabalho de desenvolvimento como usuário teste e, em seguida, dispare eventos a partir da sua integração para esse usuário. Usuários teste são sinalizados no dashboard, facilitando isolar e inspecionar o comportamento de ponta a ponta.

Quando a validação falha

O evento não é processado como um evento recomendado. Especificamente:

  • O evento é descartado por completo. Eventos recomendados de eCommerce inválidos não são registrados no perfil do usuário, não aparecem no Currents e não ficam disponíveis para segmentação.
  • Recursos a jusante de eventos recomendados não são executados, incluindo:
    • Rastreamento de receita (relatórios de receita, campos calculados do usuário como total_revenue)
    • Atualizações do objeto de carrinho no perfil do usuário
    • Disparos de Update Cart ou Place Order em Canvas e Campaigns

A forma como os erros são reportados depende do caminho de ingestão:

  • REST API (/users/track): Cada evento inválido é reportado no array de erros da resposta. Cada entrada indica qual evento falhou (índice) e o motivo (tipo). O campo message no nível superior ainda mostra “success”, o que significa apenas que sua requisição chegou à Braze, e não que todos os eventos eram válidos. Sempre verifique se há um array de erros na resposta.
  • SDKs da Braze: Chamadas de SDK retornam imediatamente e a validação é executada em segundo plano, então os erros não são enviados de volta ao seu app. Para saber sobre falhas de validação de eventos de eCommerce, fique atento ao e-mail de resumo de falhas (veja Encontrar falhas).

Exemplo de resposta de erro da API

O endpoint /users/track retorna erros no nível do campo indicando quais propriedades falharam e o motivo. Observe que o message no nível superior pode retornar "success" porque o evento foi aceito no pipeline; o array errors informa quais campos falharam na validação do esquema. Veja o exemplo de resposta de erro a seguir.




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

As falhas também são classificadas internamente e agregadas para o e-mail de resumo de falhas:

Tipo de falha Significado Exemplo
missing_property Um campo obrigatório está ausente. order_placed enviado sem order_id.
extra_property Um campo foi adicionado que o esquema não define. Um campo personalizado gift_wrapped no nível superior de properties em vez de dentro de metadata.
unexpected_data_type Um campo está com o tipo errado. total_value: "29.99" (string) em vez de 29.99 (número).

Encontrar falhas

A Braze envia por e-mail aos administradores do seu espaço de trabalho um resumo das falhas de validação de eventos recomendados para que você possa identificar e corrigir problemas de integração sem monitorar manualmente cada evento.

O e-mail de resumo inclui:

  • Contagem total de erros: Contagens de erros para o período de relatório.
  • Erros por evento: Uma divisão de quantos eventos falharam para cada tipo de evento recomendado (por exemplo, ecommerce.cart_updated e ecommerce.order_placed). Use isso para identificar quais eventos na sua integração precisam de atenção primeiro.
  • Erros por origem: Uma divisão entre API e SDK, para que você possa identificar qual integração está gerando as falhas.

Se você não está recebendo esses e-mails ou quer verificar a lista de destinatários, entre em contato com a equipe de conta da Braze.

Diagnosticar e corrigir falhas

Quando você receber um e-mail de resumo de falhas:

  1. Identifique o evento com falha e a origem. O e-mail separa as falhas por nome de evento e origem de integração (sdk versus rest_api), para que você possa identificar qual integração precisa da correção. Se você tem múltiplas origens enviando o mesmo evento (por exemplo, o SDK da sua loja e um webhook de backend ambos enviando cart_updated), resolva-os independentemente.
  2. Compare sua carga útil com o esquema em Esquemas de eventos. A maioria das falhas se enquadra em um de três padrões:
    • missing_property: Um campo obrigatório está ausente. Para resolver, adicione o campo obrigatório.
    • extra_property: Um campo personalizado está no nível superior de properties. Para resolver, mova o campo personalizado para dentro de metadata (nível do evento) ou products[].metadata (por produto).
    • unexpected_data_type: Um valor está com o tipo errado (por exemplo, total_value enviado como string). Para resolver, converta o valor antes de enviar.
  3. Teste a carga útil corrigida em um espaço de trabalho de desenvolvimento antes de implementar em produção. Envie um evento de teste conhecido para um usuário teste e, em seguida, verifique o comportamento esperado do evento recomendado no perfil desse usuário (por exemplo, se o objeto de carrinho é atualizado, se a receita é incrementada ou se o disparo de carrinho abandonado é acionado).
  4. Monitore o próximo e-mail de falhas para confirmar que a contagem de falhas para esse evento, origem e tipo caiu para zero.

Para requisitos completos de propriedades por evento, consulte Esquemas de eventos.

Documentação da plataforma de engajamento do cliente Braze.

Recursos
Jurídico
Empresa
© 2026 Braze, Inc. Todos os direitos reservados.
Verificando o status do Braze
New Stuff!