Vetor de objetos
Esta página aborda como usar um vetor de objetos para agrupar atributos relacionados. Por exemplo, você pode ter um grupo de objetos de animais de estimação, objetos de música e objetos de conta que pertencem a um único usuário. Esses vetores de objetos podem ser usados para personalizar o envio de mensagens com Liquid ou criar segmentos de público se algum elemento de um objeto corresponder aos critérios.
Tipos de dados suportados
Os seguintes tipos de dados são suportados:
| Tipo de dados | Descrição |
|---|---|
| Número | Um valor numérico, como 1 ou 5.5. |
| String | Um valor de texto, como "Hello" ou "The Hobbit". |
| booleano | Um valor que é avaliado como true ou false. |
| Array | Uma lista de valores, como ["red", "blue", "green"]. |
| Horário |
Um valor de timestamp usado para comparações de data e hora. Ao filtrar um atributo personalizado de tempo aninhado, você pode escolher:
|
| Objeto | Um valor estruturado com pares de chave-valor, como {"author": "Tolkien"}. |
| Array de objetos |
Uma lista de objetos, como [{"title": "The Hobbit"}, {"title": "Dune"}].
Para saber mais, consulte
Arrays de objetos.
|
Considerações
- Os vetores de objetos destinam-se a atributos personalizados enviados por meio da API. Não há suporte para fazer upload de CSV. Isso ocorre porque as vírgulas no arquivo CSV serão interpretadas como separadores de coluna, e as vírgulas nos valores causarão erros de análise.
- Os vetores de objetos não têm limite para o número de itens, mas têm um tamanho máximo de 100 KB. Se uma atualização (como
$addou$update) fizer o vetor exceder esse limite, a Braze descarta a atualização e o atributo permanece inalterado. A requisição da API ainda retorna uma resposta de sucesso. Para manter o vetor dentro do limite e permitir a adição de novos itens, use$removepara excluir itens do vetor primeiro. - Nem todos os parceiros da Braze suportam vetores de objetos. Consulte a documentação do parceiro para confirmar se a integração suporta esse recurso.
A atualização ou remoção de itens em um vetor exige a identificação do item por chave e valor, portanto, considere incluir um identificador exclusivo para cada item do vetor. A exclusividade tem escopo apenas para o vetor e é útil se você quiser atualizar e remover objetos específicos do vetor. Isso não é imposto pela Braze.
Quando um atributo personalizado aninhado na sua requisição contém valores inválidos (como formatos de hora inválidos ou valores null), a Braze descarta todas as atualizações de atributos personalizados aninhados da requisição durante o processamento. Isso se aplica a todas as estruturas aninhadas dentro desse atributo específico. Verifique se todos os valores dentro dos atributos personalizados aninhados são válidos antes de enviar. Para saber mais, consulte Criar e atualizar usuários.
Para saber mais sobre o uso de vetores de objetos para objetos de atributos de usuário, consulte Objeto de atributos de usuário.
Exemplo de API
A seguir, um exemplo de /users/track com um vetor pets. Para capturar as propriedades dos animais de estimação, envie uma requisição de API que liste pets como um vetor de objetos. Observe que cada objeto recebeu um id único que pode ser referenciado posteriormente ao fazer atualizações.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"attributes": [
{
"external_id": "user_id",
"pets": [
{
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Gus"
},
{
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Gerald"
}
]
}
]
}
Adicione outro item ao vetor usando o operador $add. O exemplo a seguir mostra a adição de mais três objetos de animais de estimação ao vetor pets do usuário.
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
{
"attributes": [
{
"external_id": "user_id",
"pets": {
"$add": [
{
"id": 3,
"type": "dog",
"breed": "corgi",
"name": "Doug"
},
{
"id": 4,
"type": "fish",
"breed": "salmon",
"name": "Larry"
},
{
"id": 5,
"type": "bird",
"breed": "parakeet",
"name": "Mary"
}
]
}
}
]
}
Atualize valores de objetos específicos dentro de um vetor usando o parâmetro _merge_objects e o operador $update. Semelhante às atualizações de objetos simples de atributos personalizados aninhados, isso realiza um merge profundo.
Observe que $update não pode ser usado para remover uma propriedade aninhada de um objeto dentro de um vetor. Para isso, você precisará remover o item inteiro do vetor e depois adicionar o objeto sem essa chave específica (usando uma combinação de $remove e $add).
O exemplo a seguir mostra a atualização da propriedade breed para goldfish no objeto com id igual a 4. Este exemplo de requisição também atualiza o objeto com id igual a 5 com um novo name de Annette. Como o parâmetro _merge_objects está definido como true, todos os outros campos desses dois objetos permanecem inalterados.
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
{
"attributes": [
{
"external_id": "user_id",
"_merge_objects": true,
"pets": {
"$update": [
{
"$identifier_key": "id",
"$identifier_value": 4,
"$new_object": {
"breed": "goldfish"
}
},
{
"$identifier_key": "id",
"$identifier_value": 5,
"$new_object": {
"name": "Annette"
}
}
]
}
}
]
}
Você deve definir _merge_objects como true, caso contrário seus objetos serão sobrescritos. _merge_objects é false por padrão.
Remova objetos de um vetor usando o operador $remove em combinação com uma chave correspondente ($identifier_key) e valor ($identifier_value).
O exemplo a seguir mostra a remoção de qualquer objeto no vetor pets que tenha um id com valor 1, um id com valor 2 e um type com valor dog. Se houver múltiplos objetos com o valor de type igual a dog, todos os objetos correspondentes serão removidos.
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
{
"attributes": [
{
"external_id": "user_id",
"pets": {
"$remove": [
// Remove by ID
{
"$identifier_key": "id",
"$identifier_value": 1
},
{
"$identifier_key": "id",
"$identifier_value": 2
},
// Remove any dog
{
"$identifier_key": "type",
"$identifier_value": "dog"
}
]
}
}
]
}
Ordem de processamento
Quando uma única requisição /users/track inclui operações $add, $remove e $update para o mesmo atributo de vetor, a Braze as processa nesta ordem:
$add$remove$update
Como $add é executado antes de $remove, você não pode usar um $remove seguido de $add como mecanismo de upsert em uma única requisição. O $add é processado primeiro e, em seguida, o $remove exclui o item. Para fazer upsert, envie o $remove em uma requisição separada antes do $add.
Timestamps
Ao incluir campos como timestamps em um vetor de objetos, use o formato $time em vez de strings simples ou inteiros de época Unix.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"attributes": [
{
"external_id": "user123",
"purchases": [
{
"item_name": "T-shirt",
"price": 19.99,
"purchase_time": {
"$time": "2020-05-28"
}
}
]
}
]
}
Para saber mais, consulte Atributos personalizados aninhados.
Exemplo de SDK
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
val json = JSONArray()
.put(JSONObject()
.put("id", 1)
.put("type", "dog")
.put("breed", "beagle")
.put("name", "Gus"))
.put(JSONObject()
.put("id", 2)
.put("type", "cat")
.put("breed", "calico")
.put("name", "Gerald")
)
braze.getCurrentUser { user ->
user.setCustomUserAttribute("pets", json)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
val json = JSONObject()
.put("\$add", JSONArray()
.put(JSONObject()
.put("id", 3)
.put("type", "dog")
.put("breed", "corgi")
.put("name", "Doug"))
.put(JSONObject()
.put("id", 4)
.put("type", "fish")
.put("breed", "salmon")
.put("name", "Larry"))
.put(JSONObject()
.put("id", 5)
.put("type", "bird")
.put("breed", "parakeet")
.put("name", "Mary")
)
)
braze.getCurrentUser { user ->
user.setCustomUserAttribute("pets", json, true)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
val json = JSONObject()
.put("\$update", JSONArray()
.put(JSONObject()
.put("\$identifier_key", "id")
.put("\$identifier_value", 4)
.put("\$new_object", JSONObject()
.put("breed", "goldfish")
)
)
.put(JSONObject()
.put("\$identifier_key", "id")
.put("\$identifier_value", 5)
.put("\$new_object", JSONObject()
.put("name", "Annette")
)
)
)
braze.getCurrentUser { user ->
user.setCustomUserAttribute("pets", json, true)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
val json = JSONObject()
.put("\$remove", JSONArray()
.put(JSONObject()
.put("\$identifier_key", "id")
.put("\$identifier_value", 1)
)
.put(JSONObject()
.put("\$identifier_key", "id")
.put("\$identifier_value", 2)
)
.put(JSONObject()
.put("\$identifier_key", "type")
.put("\$identifier_value", "dog")
)
)
braze.getCurrentUser { user ->
user.setCustomUserAttribute("pets", json, true)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
let json: [[String: Any?]] = [
[
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Gus"
],
[
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Gerald"
]
]
braze.user.setCustomAttribute(key: "pets", array: json)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
let json: [String: Any?] = [
"$add": [
[
"id": 3,
"type": "dog",
"breed": "corgi",
"name": "Doug"
],
[
"id": 4,
"type": "fish",
"breed": "salmon",
"name": "Larry"
],
[
"id": 5,
"type": "bird",
"breed": "parakeet",
"name": "Mary"
]
]
]
braze.user.setCustomAttribute(key: "pets", dictionary: json, merge: true)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
let json: [String: Any?] = [
"$update": [
[
"$identifier_key": "id",
"$identifier_value": 4,
"$new_object": [
"breed": "goldfish"
]
],
[
"$identifier_key": "id",
"$identifier_value": 5,
"$new_object": [
"name": "Annette"
]
]
]
]
braze.user.setCustomAttribute(key: "pets", dictionary: json, merge: true)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
let json: [String: Any?] = [
"$remove": [
[
"$identifier_key": "id",
"$identifier_value": 1,
],
[
"$identifier_key": "id",
"$identifier_value": 2,
],
[
"$identifier_key": "type",
"$identifier_value": "dog",
]
]
]
braze.user.setCustomAttribute(key: "pets", dictionary: json, merge: true)
Atributos personalizados aninhados não são compatíveis com o AppboyKit.
1
2
3
4
5
6
7
8
9
10
11
12
13
import * as braze from "@braze/web-sdk";
const json = [{
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Gus"
}, {
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Gerald"
}];
braze.getUser().setCustomUserAttribute("pets", json);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import * as braze from "@braze/web-sdk";
const json = {
"$add": [{
"id": 3,
"type": "dog",
"breed": "corgi",
"name": "Doug",
}, {
"id": 4,
"type": "fish",
"breed": "salmon",
"name": "Larry",
}, {
"id": 5,
"type": "bird",
"breed": "parakeet",
"name": "Mary",
}]
};
braze.getUser().setCustomUserAttribute("pets", json, true);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import * as braze from "@braze/web-sdk";
const json = {
"$update": [
{
"$identifier_key": "id",
"$identifier_value": 4,
"$new_object": {
"breed": "goldfish"
}
},
{
"$identifier_key": "id",
"$identifier_value": 5,
"$new_object": {
"name": "Annette"
}
}
]
};
braze.getUser().setCustomUserAttribute("pets", json, true);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import * as braze from "@braze/web-sdk";
const json = {
"$remove": [
{
"$identifier_key": "id",
"$identifier_value": 1,
},
{
"$identifier_key": "id",
"$identifier_value": 2,
},
{
"$identifier_key": "type",
"$identifier_value": "dog",
}
]
};
braze.getUser().setCustomUserAttribute("pets", json, true);
Templates com Liquid
Você pode usar esse vetor pets para personalizar uma mensagem. O exemplo de template Liquid a seguir mostra como referenciar as propriedades do objeto de atributo personalizado salvas na requisição de API anterior e usá-las no envio de mensagens.
1
2
3
4
5
{% assign pets = {{custom_attribute.${pets}}} %}
{% for pet in pets %}
I have a {{pet.type}} named {{pet.name}}! They are a {{pet.breed}}.
{% endfor %}
Nesse cenário, você pode usar Liquid para percorrer o vetor pets e imprimir uma frase para cada animal de estimação. Atribua uma variável ao atributo personalizado pets e use a notação de ponto para acessar propriedades de um objeto. Especifique o nome do objeto, seguido de um ponto ., seguido do nome da propriedade.
Segmentação
Ao segmentar usuários com base em vetores de objetos, um usuário se qualificará para o Segment se qualquer objeto no vetor corresponder aos critérios.
Crie um novo Segment e selecione Nested Custom Attribute como seu filtro. Em seguida, pesquise e selecione o nome do seu vetor de objetos.
Use a notação de ponto para especificar qual campo no vetor de objetos você deseja usar. Comece o campo de texto com um par vazio de colchetes [] para indicar à Braze que você está buscando dentro de um vetor de objetos. Depois, adicione um ponto ., seguido do nome do campo que deseja usar.
Por exemplo, se você quiser filtrar um vetor de objetos top_3_movies com base no campo type, insira [].type e escolha os filmes para filtrar, como Fantasy Movie.
Níveis de aninhamento
Você pode criar um Segment com até um nível de aninhamento de vetor (vetor dentro de outro vetor). Por exemplo, considerando os atributos a seguir, você pode criar um Segment para pets[].name contém Gus, mas não pode criar um Segment para pets[].nicknames[] contém Gugu.
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
{
"attributes": [
{
"external_id": "user_id",
"pets": [
{
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Gus",
"nicknames": [
"Gugu",
"Gusto"
]
},
{
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Gerald",
"nicknames": [
"GeGe",
"Gerry"
]
}
]
}
]
}
Pontos de dados
Os pontos de dados são registrados de forma diferente dependendo se você cria, atualiza ou remove uma propriedade.
Criar um novo vetor registra um ponto de dados para cada atributo em um objeto. Este exemplo custa oito pontos de dados — cada objeto de animal de estimação tem quatro atributos e há dois objetos.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"attributes": [
{
"external_id": "user_id",
"pets": [
{
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Gus"
},
{
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Gerald"
}
]
}
]
}
Atualizar um vetor existente registra um ponto de dados para cada propriedade adicionada. Este exemplo custa dois pontos de dados, pois atualiza apenas uma propriedade em cada um dos dois objetos.
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
{
"attributes": [
{
"external_id": "user_id",
"_merge_objects": true,
"pets": {
"$update": [
{
"$identifier_key": "id",
"$identifier_value": 4,
"$new_object": {
"breed": "goldfish"
}
},
{
"$identifier_key": "id",
"$identifier_value": 5,
"$new_object": {
"name": "Annette"
}
}
]
}
}
]
}
Remover um objeto de um vetor registra um ponto de dados para cada critério de remoção enviado. Este exemplo custa três pontos de dados, mesmo que você possa estar removendo múltiplos cachorros com essa instrução.
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
{
"attributes": [
{
"external_id": "user_id",
"pets": {
"$remove": [
// Remove by ID
{
"$identifier_key": "id",
"$identifier_value": 1
},
{
"$identifier_key": "id",
"$identifier_value": 2
},
// Remove any dog
{
"$identifier_key": "type",
"$identifier_value": "dog"
}
]
}
}
]
}