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 compatíveis

Os seguintes tipos de dados são compatíveis:

Considerações

• Os arrays de objetos foram criados para atributos personalizados enviados pela API. Não há suporte para uploads de CSV. Isso acontece porque as vírgulas no arquivo CSV são interpretadas como separadores de coluna, e vírgulas nos valores causam erros de análise.
• Os arrays de objetos não têm limite de número de itens, mas têm um tamanho máximo de 100 KB. Se uma atualização (como $add ou $update) fizer o array ultrapassar esse limite, a Braze descarta a atualização e o atributo não é alterado. A solicitação da API ainda retorna uma resposta de sucesso. Para manter o array abaixo do limite e conseguir adicionar novos itens, use $remove para excluir itens do array primeiro.
• Nem todos os parceiros da Braze oferecem suporte a arrays de objetos. Consulte a documentação de parceiros para confirmar se a integração oferece suporte a esse recurso.

Para atualizar ou remover itens de um array, é preciso identificar o item por chave e valor. Então, considere incluir um identificador exclusivo para cada item do array. A exclusividade vale apenas dentro do array e é útil se você quiser atualizar e remover objetos específicos do seu array. A Braze não impõe essa regra.

Importante

Quando um atributo personalizado aninhado na sua solicitação contém valores inválidos (como formatos de hora inválidos ou valores null), a Braze descarta do processamento todas as atualizações de atributos personalizados aninhados na solicitação. Isso se aplica a todas as estruturas aninhadas dentro desse atributo específico. Verifique se todos os valores dos atributos personalizados aninhados são válidos antes de enviar. Para saber mais, consulte Criar e atualizar usuários.

Dica

Para saber mais sobre o uso de arrays de objetos em objetos de atributos do usuário, consulte Objeto de atributos do usuário.

Exemplo de API

Use estes exemplos ao enviar solicitações /users/track que criam ou atualizam atributos personalizados aninhados armazenados como arrays de objetos. A carga útil usa os operadores $add, $remove e $update. Assim, você pode alterar objetos específicos sem reconstruir o array inteiro a cada solicitação.

• criar
• adicionar
• atualizar
• remover

Veja a seguir um exemplo de /users/track com um array pets. Para capturar as propriedades dos pets, envie uma solicitação de API que liste pets como um array de objetos. Cada objeto recebeu um id exclusivo, que pode ser referenciado depois ao fazer atualizações.

Use este formato quando quiser criar o atributo pela primeira vez ou substituir o array inteiro por um novo conjunto base de 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": "Mochi"
        },
        {
          "id": 2,
          "type": "cat",
          "breed": "calico",
          "name": "Pixel"
        }
      ]
    }
  ]
}

Adicione outro item ao array usando o operador $add. O exemplo a seguir mostra a adição de mais três objetos de pet ao array pets do usuário.

Use $add quando precisar acrescentar um ou mais objetos novos e manter os objetos existentes 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
27
28
29

{
  "attributes": [
    {
      "external_id": "user_id",
      "pets": {
        "$add": [
          {
            "id": 3,
            "type": "dog",
            "breed": "corgi",
            "name": "Biscuit"
          },
          {
            "id": 4,
            "type": "fish",
            "breed": "salmon",
            "name": "Pepper"
          },
           {
            "id": 5,
            "type": "bird",
            "breed": "parakeet",
            "name": "Noodle"
          }
        ]
      }
    }
  ]
}

Atualize valores de objetos específicos dentro de um array usando o parâmetro _merge_objects e o operador $update. Assim como nas atualizações de outros objetos de atributos personalizados aninhados, essa operação faz uma mesclagem profunda.

Não é possível usar $update para remover uma propriedade aninhada de um objeto dentro de um array. Para isso, você precisa remover o item inteiro do array e depois adicionar o objeto sem essa chave específica (usando uma combinação de $remove e $add).

Use $update quando o objeto já existir e você quiser alterar um ou mais campos fazendo a correspondência por $identifier_key e $identifier_value.

O exemplo a seguir mostra a atualização da propriedade breed para goldfish no objeto com id igual a 4. Este exemplo de solicitaçã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 iguais.

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

Aviso

Você precisa definir _merge_objects como true, ou seus objetos serão substituídos. O padrão de _merge_objects é false.

Remova objetos de um array usando o operador $remove em combinação com uma chave ($identifier_key) e um valor ($identifier_value) correspondentes.

Use $remove quando quiser excluir todos os objetos que correspondem a um par de identificadores conhecido, como id = 2 ou type = dog.

O exemplo a seguir mostra a remoção de qualquer objeto no array pets que tenha um id com valor 1, um id com valor 2 e um type com valor dog. Se houver vários objetos com o valor dog em type, 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 solicitação /users/track inclui operações $add, $remove e $update para o mesmo atributo de array, a Braze as processa nesta ordem:

1. $add
2. $remove
3. $update

Essa ordem se aplica dentro de um único objeto de atualização de atributo em uma solicitação e determina o estado final do array depois que todas as operações são avaliadas.

Como $add é executado antes de $remove, não é possível usar um $remove seguido de $add como mecanismo de upsert em uma única solicitação. O $add é processado primeiro e, em seguida, o $remove exclui o item. Para fazer um upsert, envie o $remove em uma solicitação separada antes do $add.

Carimbos de data/hora

Ao incluir campos como carimbos de data/hora em um array 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"
          }
        }
      ]
    }
  ]
}

Dica

Para saber mais, consulte Atributos personalizados aninhados.

Exemplo de SDK

• android sdk
• swift sdk
• web sdk

• create
• add
• update
• delete

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", "Pixel")
    )

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", "Pepper"))
        .put(JSONObject()
            .put("id", 5)
            .put("type", "bird")
            .put("breed", "parakeet")
            .put("name", "Noodle")
        )
    )

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

• create
• add
• update
• delete

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": "Mochi"
  ],
  [
    "id": 2,
    "type": "cat",
    "breed": "calico",
    "name": "Pixel"
  ]
]

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": "Biscuit"
    ],
    [
      "id": 4,
      "type": "fish",
      "breed": "salmon",
      "name": "Pepper"
    ],
    [
      "id": 5,
      "type": "bird",
      "breed": "parakeet",
      "name": "Noodle"
    ]
  ]
]

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)

Importante

Atributos personalizados aninhados não são compatíveis com o AppboyKit.

• create
• add
• update
• delete

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": "Mochi"
}, {
  "id": 2,
  "type": "cat",
  "breed": "calico",
  "name": "Pixel"
}];
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":  "Pepper",
  }, {
    "id":  5,
    "type":  "bird",
    "breed":  "parakeet",
    "name":  "Noodle",
  }]
};
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);

Modelos em Liquid

Você pode usar esse array pets para personalizar uma mensagem. O exemplo de modelo em Liquid abaixo mostra como referenciar as propriedades do objeto de atributo personalizado salvas na solicitação de API anterior e usá-las no seu 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 array pets e imprimir uma frase para cada pet. Atribua uma variável ao atributo personalizado pets e use a notação de ponto para acessar as propriedades de um objeto. Para isso, informe o nome do objeto, seguido de um ponto . e, depois, o nome da propriedade.

Segmentação

Ao segmentar usuários com base em arrays de objetos, um usuário se qualifica para o Segment se qualquer objeto do array corresponder aos critérios.

Crie um novo Segment e selecione Nested Custom Attribute como filtro. Depois, pesquise e selecione o nome do seu array de objetos.

Use a notação de ponto para especificar qual campo do array de objetos você quer usar. Comece o campo de texto com um par de colchetes vazio [] para indicar à Braze que você está procurando dentro de um array de objetos. Em seguida, adicione um ponto . e depois o nome do campo que você quer usar.

Por exemplo, se você quiser filtrar um array de objetos top_3_movies com base no campo type, insira [].type e escolha os filmes que deseja filtrar, como Fantasy Movie.

Níveis de aninhamento

Você pode criar um Segment com até um nível de aninhamento de arrays (um array dentro de outro array). Por exemplo, com os atributos abaixo, você pode criar um Segment para pets[].name contém Mochi, 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": "Mochi",
          "nicknames": [
            "MoMo",
            "Mochi"
          ]
        },
        {
          "id": 2,
          "type": "cat",
          "breed": "calico",
          "name": "Pixel",
          "nicknames": [
            "PiPi",
            "Pixel"
          ]
        }
      ]
    }
  ]
}

Pontos de dados

Os pontos de dados são registrados de forma diferente se você cria, atualiza ou remove uma propriedade.

• criar
• atualizar
• remover

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": "Mochi"
        },
        {
          "id": 2,
          "type": "cat",
          "breed": "calico",
          "name": "Pixel"
        }
      ]
    }
  ]
}

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

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