Skip to content

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.

O que é um objeto de compra?

Um objeto de compra é um objeto que é passado pela API quando uma compra é realizada. Cada objeto de compra está localizado dentro de um array de compras, sendo cada objeto uma compra individual feita por um usuário específico em um momento específico. O objeto de compra tem diversos campos que permitem ao backend da Braze armazenar e usar essas informações para personalização, coleta de dados e customização.

Corpo do objeto

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  // 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)
}

ID do produto de compra

Dentro do objeto de compra, o product_id é um identificador para a compra (como Product Name ou Product Category):

  • A Braze permite que você armazene 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 do produto ou a categoria do produto (em vez de SKUs), com a intenção de agrupar todos os itens registrados por esse product_id.

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

Registrar compras no nível do pedido

Se você quiser registrar compras no nível do pedido em vez do nível do produto, pode usar o nome do pedido 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 SDK para web:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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

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 usando Liquid, permitindo também a segmentação com base nessas propriedades.

Convenções de nomenclatura

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

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

Exemplo de objeto de compra

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

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

Usando o exemplo fornecido, podemos ver que alguém comprou uma mochila com as propriedades: cor, monograma, duração do checkout, tamanho e marca. Em seguida, podemos criar segmentos com essas propriedades usando propriedades de eventos de compra ou enviar mensagens personalizadas por meio de um canal usando Liquid. Por exemplo, “Olá Ana F., obrigado por comprar aquela mochila vermelha média por R$ 40,00! Obrigado por comprar na Backpack Locker!”

Se quiser salvar, armazenar e rastrear propriedades para segmentar, será necessário configurá-las como atributos personalizados. Isso pode ser feito usando extensões de segmento, que permitem o direcionamento de usuários com base em eventos personalizados ou comportamento de compra armazenado durante toda a vida útil desse perfil de usuário.
New Stuff!