Ir para o conteúdo

Esta página foi traduzida automaticamente e pode conter imprecisões. Para relatar um erro de tradução, use o componente de feedback na parte inferior do sumário, à direita da página.

Objeto de compra

Este artigo explica os diferentes componentes de um objeto de compra, como usá-lo corretamente, as práticas recomendadas e exemplos para consulta.

Importante

O evento de compra legado está entrando em modo de manutenção. Clientes existentes da Braze podem continuar usando eventos de compra legados. Eles continuarão funcionando como esperado, mas novas funcionalidades serão desenvolvidas com base nos eventos recomendados de eCommerce daqui em diante. A Braze fornecerá aviso prévio bem antes de qualquer data de fim de vida ser definida. Novos clientes da Braze devem usar os eventos recomendados de eCommerce, pois os eventos de compra legados não estarão disponíveis.

O que é um objeto de compra?

Um objeto de compra é um objeto passado pela API quando uma compra é feita. Cada objeto de compra fica dentro de um array de compras, e cada objeto representa uma única compra feita por um determinado usuário em um determinado momento. O objeto de compra tem vários campos diferentes que permitem que o backend da Braze armazene e use essas informações para customização, coleta de dados e personalização.

Corpo do objeto

{
  // One of "external_id" or "user_alias" or "braze_id" or "email" or "phone" is required.
  "external_id" : (optional, string) External user ID,
  "user_alias" : (optional, User Alias Object) User alias object,
  "braze_id" : (optional, string) Braze user identifier,
  "email": (optional, string) User email address,
  "phone": (optional, string) User phone number,
  "app_id" : (optional, string) see App Identifier,
  // See the following product_id naming conventions for clarification.
  "product_id" : (required, string) identifier for the purchase, for example, Product Name or Product Category,
  "currency" : (required, string) ISO 4217 Alphabetic Currency Code,
  //Revenue from a purchase object is calculated as the product of quantity and price.
  "price" : (required, float) value in the base currency unit (for example, Dollars for USD, Yen for JPY),
  "quantity" : (optional, integer) the quantity purchased (defaults to 1, must be <= 100 -- currently, Braze treats a quantity _X_ as _X_ separate purchases with quantity 1),
  "time" : (required, datetime as string in ISO 8601) Time of purchase,
  // See the following purchase object explanation for clarification.
  "properties" : (optional, Properties Object) properties of the event,
  // Setting this flag to true puts the API in "Update Only" mode.
  // When using a "user_alias", "Update Only" mode is always true.
  "_update_existing_only" : (optional, boolean)
}

Nota

Compras com registros de data e hora no futuro passam a usar o horário atual por padrão. Isso garante que os eventos de compra sejam registrados com o horário correto.

Nota

Alguns pares de identificadores não podem ser usados juntos, e email tem precedência sobre phone quando ambos são informados. Para saber todos os detalhes, consulte Resolução de identificadores.

ID do produto de compra

No objeto de compra, o product_id é um identificador da compra (como Product Name ou Product Category):

A Braze permite armazenar até 5.000 product_ids no dashboard.
O product_id pode ter até 255 caracteres.

Convenções de nomenclatura

Na Braze, oferecemos algumas convenções gerais de nomenclatura para o product_id do objeto de compra. Ao escolher o product_id, a Braze sugere usar nomes simples, como o nome ou a categoria do produto (em vez de SKUs). A ideia é agrupar todos os itens registrados por esse product_id.

Isso facilita a identificação dos produtos para segmentação e disparo.

Registrar compras no nível do pedido

Se quiser registrar compras no nível do pedido em vez do nível do produto, você pode usar o nome ou a categoria do pedido como product_id (como Online Order ou Completed Order).

Por exemplo, para registrar compras no nível do pedido no Web SDK:

POST https://YOUR_REST_API_URL/users/track
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "purchases" : [
    {
      "external_id" : "user1",
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "Completed Order",
      "currency" : "USD",
      "price" : 219.98,
      "time" : "2013-07-16T19:20:30+01:00",
      "properties" : {
        "products" : [ { "name": "Monitor", "category": "Gaming", "product_amount": 19.99, },
        { "name": "Gaming Keyboard", "category": "Gaming ", "product_amount": 199.99, }
        ]
      }
    }
  ]
}

Objeto de propriedades de compra

As propriedades de compra foram criadas para filtragem e personalização com Liquid em mensagens disparadas pelos eventos de compra aos quais pertencem. Por padrão, elas não ficam salvas no perfil de usuário da Braze. Para usar valores de propriedades de compra na segmentação, consulte Segmentação por propriedades de evento. Esse recurso armazena os valores no perfil de usuário por uma janela de retrospectiva de até 30 dias.

The properties values must be an object up to 50 KB where the keys are the property names and the values are the property values. Property names must be strings, 255 characters or fewer, with no leading dollar signs ($).

Property values can be any of the following data types:

Data type	Description
Number	Integer or float
Boolean	Value `true` or `false`
Datetime	String in ISO 8601 or `yyyy-MM-dd'T'HH:mm:ss:SSSZ` format. Not supported within arrays.
String	255 characters or fewer
Array	Supported; datetimes are not supported within arrays.
Object	Ingested as strings (not nested objects). For nested data, use a string value (for example, JSON serialized).

The following keys are reserved and cannot be used as property names: time, product_id, quantity, event_name, price, and currency. Using a reserved key in the properties object returns the error “Invalid ‘properties’ field”.

Para uma referência consolidada dos tipos de dados em atributos personalizados, propriedades de evento e catálogos, consulte Tipos de dados.

Propriedades de compra

As propriedades de compra podem ser usadas para disparar mensagens e para personalização com Liquid. Elas também permitem segmentar com base nessas propriedades.

Nota

When you view segmentable purchase properties in Data Settings > Products, the list displays property keys (names such as “color” or “brand”), not the actual property values (such as “red” or “Nike”).

Convenções de nomenclatura

É importante notar que esse recurso é ativado por produto, não por compra. Por exemplo, se você tiver um alto volume de produtos distintos, mas todos tiverem as mesmas propriedades, a segmentação pode acabar sendo desnecessária.

Nesse caso, recomendamos usar nomes de produtos em nível de “grupo”, em vez de identificadores em nível de transação, ao definir as estruturas de dados. Por exemplo, uma empresa de passagens de trem deve ter produtos como “viagem única”, “viagem de ida e volta” e “várias cidades”, e não transações específicas, como “transação 123” ou “transação 046”. Outro exemplo: com o evento de compra “comida”, o ideal seria definir as propriedades como “bolo” e “sanduíche”.

Importante

Observe que os produtos podem ser adicionados pela REST API da Braze. Por exemplo, se você enviar uma chamada para o endpoint /users/track e incluir um novo ID de compra, a Braze cria automaticamente um produto na seção Configurações de dados > Produtos do dashboard.

Exemplo de objeto de compra

POST https://YOUR_REST_API_URL/users/track
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "purchases" : [
    {
      "external_id" : "user1",
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "backpack",
      "currency" : "USD",
      "price" : 40.00,
      "time" : "2013-07-16T19:20:30+01:00",
      "properties" : {
        "color" : "red",
        "monogram" : "ABC",
        "checkout_duration" : 180,
        "size" : "Large",
        "brand" : "Backpack Locker"
      }
    },
    {
      "external_id" : "user1",
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "pencil",
      "currency" : "USD",
      "price" : 2.00,
      "time" : "2013-07-17T19:20:20+01:00",
      "properties" : {
        "number" : 2,
        "sharpened" : true
      }
    },
    {
      "user_alias" : { "alias_name" : "device123", "alias_label" : "my_device_identifier"},
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "pen",
      "currency" : "USD",
      "price" : 2.50,
      "time" : "2013-07-17T19:20:20+01:00",
      "properties" : {
        "color" : "blue",
      }
    }
  ]
}

Objetos de compra, objetos de evento e webhooks

No exemplo acima, vemos que alguém comprou uma mochila com as propriedades cor, monograma, duração do checkout, tamanho e marca. Com isso, podemos criar Segments com essas propriedades usando propriedades de eventos de compra ou enviar mensagens personalizadas por um canal usando Liquid. Por exemplo: “Olá, Ana F.! Obrigado por comprar aquela mochila vermelha média por US$ 40,00! Obrigado por comprar na Backpack Locker!”

Se você quiser salvar, armazenar e rastrear propriedades para segmentar, será necessário configurá-las como atributos personalizados. Para isso, use as extensões de segmento, que permitem direcionar usuários com base em eventos personalizados ou no comportamento de compra armazenado durante toda a vida útil do perfil de usuário.

New Stuff!