Skip to content

Objeto de compra

Este artículo explica los distintos componentes de un objeto de compra, cómo utilizarlo correctamente, las mejores prácticas y ejemplos en los que inspirarse.

¿Qué es un objeto de compra?

Un objeto de compra es un objeto que se pasa a través de la API cuando se ha realizado una compra. Cada objeto de compra se encuentra dentro de un arreglo de compras, y cada objeto representa una compra individual realizada por un usuario en particular en un momento determinado. El objeto de compra tiene muchos campos diferentes que permiten al backend de Braze almacenar y utilizar esta información para personalización, recopilación de datos y personalización.

Cuerpo del 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 de producto de compra

Dentro del objeto de compra, el product_id es un identificador para la compra (como Product Name o Product Category):

  • Braze te permite almacenar hasta 5000 product_ids en el panel.
  • El product_id puede tener hasta 255 caracteres.

Convenciones de nomenclatura

En Braze, ofrecemos algunas convenciones generales de nomenclatura para el product_id del objeto de compra. Al elegir el product_id, Braze sugiere usar nombres sencillos como el nombre del producto o la categoría del producto (en lugar de SKUs) con la intención de agrupar todos los elementos registrados por este product_id.

Esto facilita la identificación de productos para la segmentación y el desencadenamiento.

Registrar compras a nivel de pedido

Si deseas registrar compras a nivel de pedido en lugar de a nivel de producto, puedes usar el nombre del pedido o la categoría del pedido como product_id (como Online Order o Completed Order).

Por ejemplo, para registrar compras a nivel de pedido en el SDK 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 propiedades 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 una referencia consolidada de los tipos de datos en atributos personalizados, propiedades del evento y catálogos, consulta Tipos de datos.

Propiedades de la compra

Las propiedades de la compra pueden utilizarse para desencadenar mensajes y para la personalización mediante Liquid, permitiéndote también segmentar en función de estas propiedades.

Convenciones de denominación

Es importante tener en cuenta que esta característica se activa por producto, no por compra. Por ejemplo, si tienes un gran volumen de productos distintos, pero todos tienen las mismas propiedades, la segmentación puede resultar innecesaria.

En este caso, recomendamos utilizar nombres de productos a «nivel de grupo» en lugar de identificadores a nivel de transacción al configurar las estructuras de datos. Por ejemplo, una empresa de billetes de tren debería tener productos para “viaje de ida”, “viaje de vuelta”, “multiciudad”, y no transacciones específicas como “transacción 123” o “transacción 046”. Como otro ejemplo, con el evento de compra «comida», lo mejor sería establecer las propiedades como «pastel» y «sándwich».

Ejemplo 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 y webhooks

Utilizando el ejemplo proporcionado, podemos ver que alguien compró una mochila con las propiedades: color, monograma, duración de la compra, tamaño y marca. A continuación, podemos crear segmentos con estas propiedades utilizando las propiedades del evento de compra o enviar mensajes personalizados a través de un canal utilizando Liquid. Por ejemplo: “Hola, Ann F., gracias por comprar esa mochila roja mediana por 40,00 $. ¡Gracias por comprar en Backpack Locker!”

Si quieres guardar, almacenar y hacer un seguimiento de las propiedades para segmentar, tienes que configurarlas como atributos personalizados. Esto puede hacerse utilizando Extensiones de segmento, que te permiten dirigirte a los usuarios basándote en un evento personalizado o en el comportamiento de compra almacenado durante toda la vida de ese perfil de usuario.
New Stuff!