Atributos personalizados aninhados

Esta página aborda os atributos personalizados aninhados, que permitem definir um conjunto de atributos como uma propriedade de outro atributo. Em outras palavras, quando você define um objeto de atributo personalizado, pode definir um conjunto de atributos adicionais para esse objeto.

Sobre atributos aninhados

Atributos aninhados permitem que você construa segmentos mais ricos e personalize mensagens com dados de um único objeto de atributo personalizado.

No exemplo a seguir, o atributo personalizado favorite_book contém os atributos aninhados title, author e publishing_date. Este objeto pode ser usado para segmentar usuários por autor, filtrar por data de publicação ou inserir o título do livro diretamente em uma mensagem:

1
2
3
4
5
"favorite_book": {
  "title": "The Hobbit",
  "author": "J.R.R. Tolkien",
  "publishing_date": "1937"
}

Tipos de dados suportados

Os seguintes tipos de dados são suportados:

Considerações

• Os atributos personalizados aninhados destinam-se a atributos personalizados enviados por meio do Braze SDK ou da API.
• Os objetos têm um tamanho máximo de 100 KB. Se uma atualização fizer com que o objeto exceda 100 KB, a Braze descarta a atualização e o atributo permanece inalterado.
• Os nomes das chaves e os valores das strings têm um limite de tamanho de 255 caracteres.
• Os nomes das chaves não podem conter espaços.
• Períodos (.) e sinais de dólar ($) não são caracteres suportados em uma carga útil de API se você estiver tentando enviar um atributo personalizado aninhado para um perfil de usuário.
• Nem todos os parceiros da Braze suportam atributos personalizados aninhados. Consulte a documentação do parceiro para confirmar se integrações com parceiros específicos suportam esse recurso.
• Os atributos personalizados aninhados não podem ser usados como filtro ao fazer uma chamada à API do Connected Audience.

Exemplo de API

• criar
• atualizar
• excluir

A seguir, um exemplo de /users/track com um objeto “Most Played Song”. Para capturar as propriedades da música, enviaremos uma solicitação de API que lista most_played_song como um objeto, junto com um conjunto de propriedades do objeto.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "attributes": [
    {
      "external_id": "user_id",
      "most_played_song": {
        "song_name": "Solea",
        "artist_name": "Miles Davis",
        "album_name": "Sketches of Spain",
        "genre": "Jazz",
        "play_analytics": {
            "count": 1000,
            "top_10_listeners": true
        }
      }
    }
  ]
}

Para atualizar um objeto existente, envie um POST para users/track com o parâmetro _merge_objects na solicitação. Isso fará um deep merge da sua atualização com os dados existentes do objeto. O deep merge garante que todos os níveis de um objeto sejam mesclados em outro objeto, em vez de apenas o primeiro nível. Neste exemplo, já temos um objeto most_played_song na Braze e agora estamos adicionando um novo campo, year_released, ao objeto most_played_song.

1
2
3
4
5
6
7
8
9
10
11
{
  "attributes": [
    {
      "external_id": "user_id",
      "_merge_objects": true,
      "most_played_song": {
          "year_released": 1960
      }
    }
  ]
}

Após o recebimento dessa solicitação, o objeto de atributo personalizado ficará assim:

1
2
3
4
5
6
7
8
9
10
11
{"most_played_song": {
  "song_name": "Solea",
  "artist_name" : "Miles Davis",
  "album_name": "Sketches of Spain",
  "year_released": 1960,
  "genre": "Jazz",
  "play_analytics": {
     "count": 1000,
     "top_10_listeners": true
  }
}}

Aviso

Você deve definir _merge_objects como true, caso contrário seus objetos serão sobrescritos. _merge_objects é false por padrão.

Para excluir um objeto de atributo personalizado, envie um POST para users/track com o objeto de atributo personalizado definido como null.

1
2
3
4
5
6
7
8
{
  "attributes": [
    {
      "external_id": "user_id",
      "most_played_song": null
    }
  ]
}

Nota

Essa abordagem não pode ser usada para excluir uma chave aninhada dentro de um vetor de objetos.

Exemplo de SDK

• android sdk
• swift sdk
• web sdk

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
val json = JSONObject()
    .put("song_name", "Solea")
    .put("artist_name", "Miles Davis")
    .put("album_name", "Sketches of Spain")
    .put("genre", "Jazz")
    .put(
        "play_analytics",
        JSONObject()
            .put("count", 1000)
            .put("top_10_listeners", true)
    )

braze.getCurrentUser { user ->
    user.setCustomUserAttribute("most_played_song", json)
}

1
2
3
4
5
6
val json = JSONObject()
    .put("year_released", 1960)

braze.getCurrentUser { user ->
    user.setCustomUserAttribute("most_played_song", json, true)
}

1
2
3
braze.getCurrentUser { user ->
    user.unsetCustomUserAttribute("most_played_song")
}

1
2
3
4
5
6
7
8
9
10
11
12
let json: [String: Any?] = [
  "song_name": "Solea",
  "artist_name": "Miles Davis",
  "album_name": "Sketches of Spain",
  "genre": "Jazz",
  "play_analytics": [
    "count": 1000,
    "top_10_listeners": true,
  ],
]

braze.user.setCustomAttribute(key: "most_played_song", dictionary: json)

1
2
3
4
5
let json: [String: Any?] = [
  "year_released": 1960
]

braze.user.setCustomAttribute(key: "most_played_song", dictionary: json, merge: true)

1
braze.user.unsetCustomAttribute(key: "most_played_song")

1
2
3
4
5
6
7
8
9
10
11
12
import * as braze from "@braze/web-sdk";
const json = {
  "song_name": "Solea",
  "artist_name": "Miles Davis",
  "album_name": "Sketches of Spain",
  "genre": "Jazz",
  "play_analytics": {
    "count": 1000,
    "top_10_listeners": true
  }
};
braze.getUser().setCustomUserAttribute("most_played_song", json);

1
2
3
4
5
6
import * as braze from "@braze/web-sdk";
const json = {
  "year_released": 1960
};
braze.getUser().setCustomUserAttribute("most_played_song", json, true);

1
2
import * as braze from "@braze/web-sdk";
braze.getUser().setCustomUserAttribute("most_played_song", null);

Capturando datas como propriedades de objetos

Para capturar datas como propriedades de objetos, você deve usar a chave $time. No exemplo a seguir, um objeto “Important Dates” é usado para capturar o conjunto de propriedades do objeto, birthday e wedding_anniversary. Os valores dessas datas são objetos com uma chave $time, que não pode ser um valor nulo.

Nota

Se você não capturou datas como propriedades de objetos inicialmente, recomendamos reenviar esses dados usando a chave $time para todos os usuários. Caso contrário, isso pode resultar em segmentos incompletos ao usar o atributo $time. No entanto, se o valor de $time em um atributo personalizado aninhado não estiver formatado corretamente, o atributo personalizado aninhado inteiro não será atualizado.

1
2
3
4
5
6
7
8
9
10
11
{
  "attributes": [
    {
      "external_id": "time_with_nca_test",
      "important_dates": {
        "birthday": {"$time" : "1980-01-01"},
        "wedding_anniversary": {"$time" : "2020-05-28"}
      }
    }
  ]
}

Nota

Para atributos personalizados aninhados, se o ano for menor que 0 ou maior que 3000, a Braze não armazena esses valores no usuário.

Templates com Liquid

O exemplo de template Liquid a seguir 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.

Use a tag de personalização custom_attribute e a notação de ponto para acessar propriedades em um objeto. Especifique o nome do objeto (e a posição no vetor, se estiver referenciando um vetor de objetos), seguido de um ponto, seguido do nome da propriedade.

{{custom_attribute.${most_played_song}[0].artist_name}} — “Miles Davis”
{{custom_attribute.${most_played_song}[0].song_name}} — “Solea”
{{custom_attribute.${most_played_song}[0].play_analytics.count}} — “1000”

Personalização

Usando o modal Adicionar personalização, você também pode inserir atributos personalizados aninhados no seu envio de mensagens. Selecione Atributos personalizados aninhados como o tipo de personalização. Em seguida, selecione o atributo de nível superior e a chave do atributo.

Por exemplo, no modal de personalização abaixo, isso insere o atributo personalizado aninhado de um escritório de bairro local com base nas preferências do usuário.

Dica

Verifique se um esquema foi gerado caso você não veja a opção de inserir atributos personalizados aninhados.

Regenerar esquemas

Após um esquema ser gerado, ele pode ser regenerado uma vez a cada 24 horas. Esta seção descreve como regenerar seu esquema. Para informações mais detalhadas sobre esquemas, consulte Gerar um esquema usando o explorador de objetos aninhados.

Para regenerar o esquema do seu atributo personalizado aninhado:

1. Acesse Configurações de dados > Atributos personalizados.
2. Pesquise seu atributo personalizado aninhado.
3. Na coluna Attribute Name do seu atributo, selecione para gerenciar o esquema.
4. Um modal será exibido. Selecione Regenerate Schema.

A opção de regenerar esquema ficará desabilitada se tiverem se passado menos de 24 horas desde a última regeneração do esquema. Regenerar o esquema detectará apenas novos objetos e não excluirá objetos que já existem no esquema.

Importante

Para redefinir o esquema de um vetor de objetos com um objeto existente, você precisa criar um novo atributo personalizado. A regeneração do esquema não exclui objetos existentes.

Se os dados não aparecerem como esperado após regenerar o esquema, o atributo pode não estar sendo ingerido com frequência suficiente. Os dados de usuários são amostrados com base em dados anteriores enviados à Braze para o atributo aninhado em questão. Se o atributo não for ingerido com frequência suficiente, ele não será capturado para o esquema.

Disparar alterações em atributos personalizados aninhados

Você pode disparar ações quando um objeto de atributo personalizado aninhado é alterado. Essa opção não está disponível para alterações em vetores de objetos. Se você não vir a opção de visualizar o explorador de jornadas, verifique se você gerou um esquema.

Por exemplo, em uma Campaign baseada em ação, você pode adicionar uma nova ação-gatilho para Change Custom Attribute Value para direcionar usuários que alteraram suas preferências de escritório de bairro.

Comportamento de segmentação com vetores de objetos

Quando você usa múltiplos filtros de Nested Custom Attribute com lógica AND para segmentar em um vetor de objetos, cada filtro é avaliado independentemente em todos os itens do vetor. Um usuário se qualifica para o Segment se qualquer item no vetor satisfizer cada filtro individual — os filtros não precisam corresponder ao mesmo item.

Por exemplo, suponha que um usuário tenha o seguinte vetor:

1
2
3
4
5
6
{
  "orders": [
    {"product": "Shoes", "price": 80},
    {"product": "Hat", "price": 25}
  ]
}

Um Segment com os seguintes filtros AND:

• orders[].price é maior que 50
• orders[].price é menor que 30

Esse usuário se qualificaria porque o primeiro filtro corresponde ao item “Shoes” (80 > 50) e o segundo filtro corresponde ao item “Hat” (25 < 30). Mesmo que nenhum item individual satisfaça ambas as condições, o usuário ainda entra no Segment.

Se você precisar que todas as condições correspondam ao mesmo item dentro de um vetor, use segmentação multicritério na mesma jornada, ou reestruture seus dados para evitar correspondência entre itens diferentes.

Pontos de dados

Qualquer chave enviada consome um ponto de dados. Por exemplo, este objeto inicializado no perfil de usuário conta como sete (7) pontos de dados:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "attributes": [
    {
      "external_id": "user_id",
      "most_played_song": {
        "song_name": "Solea",
        "artist_name": "Miles Davis",
        "album_name": "Sketches of Spain",
        "year_released": 1960,
        "genre": "Jazz",
        "play_analytics": {
          "count": 1000,
          "top_10_listeners": true
        }
      }
    }
  ]
}

Nota

Atualizar um objeto de atributo personalizado para null também consome um ponto de dados.