Skip to content

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

Os atributos aninhados permitem criar segmentos mais detalhados e personalizar 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. Esse 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:

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:

  • Day of Year: Verifica apenas o mês e o dia para comparação, como 03-15.
  • Time: Compara o timestamp completo, incluindo o ano, como 2023-03-15T12:00:00Z.
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 atributos personalizados aninhados são destinados a atributos personalizados enviados por meio do SDK ou da API da Braze.
  • 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 de string têm um limite de 255 caracteres.
  • Os nomes das chaves não podem conter espaços.
  • Pontos (.) e cifrões ($) não são caracteres compatíveis 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 oferecem suporte a atributos personalizados aninhados. Consulte a documentação de parceiros para confirmar se integrações com parceiros específicos oferecem suporte a esse recurso.
  • Os atributos personalizados aninhados não podem ser usados como filtro ao fazer uma chamada de API de Connected Audience.
  • Por padrão, o filtro de Segment Atributos personalizados aninhados inclui atributos personalizados do tipo objeto, atributos de vetor de objetos e atributos personalizados do tipo vetor. Ao selecionar um atributo, o seletor de esquema de propriedade inclui caminhos de vetor (usando a notação []) para campos de vetor aninhados. Para ocultar atributos personalizados de vetor de nível superior desse filtro, entre em contato com o suporte da Braze.
  • Ao pré-visualizar mensagens no dashboard usando Preview as a Custom User, você pode inserir dados simulados apenas como string ou vetor de strings — objetos aninhados não são compatíveis. Para pré-visualizar uma mensagem que faz referência a atributos personalizados aninhados, selecione um usuário existente que já tenha o atributo aninhado em seu perfil. Para propriedades de eventos personalizados aninhados, você deve lançar uma campanha ativa direcionada a um usuário teste para verificar a renderização.

Exemplo de API

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

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

Exemplo de SDK

Os exemplos a seguir mostram como criar, atualizar por mesclagem e excluir o mesmo objeto de atributo personalizado aninhado (most_played_song) em cada SDK.

Criar

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

Atualizar

1
2
3
4
5
6

val json = JSONObject()
    .put("year_released", 1960)

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

Excluir

1
2
3

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

Criar

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)

Atualizar

1
2
3
4
5

let json: [String: Any?] = [
  "year_released": 1960
]

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

Excluir

1

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

Criar

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

Atualizar

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

Excluir

1
2

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

Criar

1
2
3
4
5
6
7
8
9
10
11
12

Dictionary<string, object> attributes = new Dictionary<string, object>();
attributes.Add("song_name", "Solea");
attributes.Add("artist_name", "Miles Davis");
attributes.Add("album_name", "Sketches of Spain");
attributes.Add("genre", "Jazz");

Dictionary<string, object> playAnalytics = new Dictionary<string, object>();
playAnalytics.Add("count", 1000);
playAnalytics.Add("top_10_listeners", true);
attributes.Add("play_analytics", playAnalytics);

AppboyBinding.SetCustomUserAttribute("most_played_song", attributes);

Atualizar

1
2
3
4

Dictionary<string, object> attributes = new Dictionary<string, object>();
attributes.Add("year_released", 1960);

AppboyBinding.SetCustomUserAttribute("most_played_song", attributes, true);

Excluir

1

AppboyBinding.UnsetCustomUserAttribute("most_played_song");

Capturando datas como propriedades de objeto

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

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

Modelos Liquid

O exemplo de modelo Liquid a seguir mostra como referenciar as propriedades do objeto de atributo personalizado salvas a partir da 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”

Para usar Liquid de atributos personalizados aninhados na sua mensagem:

  1. Acesse uma Campaign ou Canvas e abra a etapa de mensagem onde deseja adicionar personalização.
  2. No criador de mensagem, insira o snippet Liquid onde deseja que o valor apareça.
  3. Use Preview & Test com um usuário existente que já tenha o atributo personalizado aninhado no perfil para confirmar que o valor é renderizado conforme esperado.

Personalização

Você pode usar Add Personalization para inserir um atributo personalizado aninhado na sua mensagem.

Para abrir Add Personalization:

  1. Acesse uma Campaign ou Canvas e abra a etapa de mensagem onde deseja adicionar personalização.
  2. No criador de mensagem, selecione Personalization para abrir a barra lateral Add Personalization, onde você pode escolher opções de personalização.

Para configurar a personalização de atributos personalizados aninhados:

  1. Em Personalization Type, selecione Nested Custom Attributes.
  2. Em Top Level Attribute, selecione o caminho do atributo personalizado aninhado que deseja inserir. Por exemplo, selecione preferences.neighborhood_office.
  3. Opcional: Em Default value, insira um valor de fallback para usuários que não possuem um valor próprio para esse atributo.
  4. Revise o Liquid Snippet gerado para confirmar que ele corresponde ao caminho esperado.
  5. Selecione Insert.

Neste exemplo, a Braze insere o valor aninhado de preferences.neighborhood_office na sua mensagem. Os valores padrão são fallbacks que a sua mensagem inclui para usuários que não possuem um valor próprio para um atributo.

Gerar e regenerar esquemas

Para usar atributos personalizados aninhados em segmentação e personalização, você deve gerar um esquema para o atributo. Após um esquema ser gerado, ele pode ser regenerado conforme necessário. Para informações mais detalhadas sobre esquemas, consulte Gerar um esquema usando o explorador de objetos aninhados.

Gerar um esquema

Após criar um atributo personalizado aninhado e enviar dados para a Braze, você pode gerar o esquema:

  1. Acesse Data Settings > Custom Attributes.
  2. Pesquise seu atributo personalizado aninhado.
  3. Na coluna Attribute Name do seu atributo, selecione Generate Schema.

Após o esquema ser gerado, o ícone muda para um ícone de mais que você pode selecionar para visualizar e gerenciar o esquema.

Regenerar um esquema

Para regenerar o esquema do seu atributo personalizado aninhado:

  1. Acesse Data Settings > Custom Attributes.
  2. Pesquise seu atributo personalizado aninhado.
  3. Na coluna Attribute Name do seu atributo, selecione Manage schema para gerenciar o esquema.
  4. Um modal será exibido. Selecione Regenerate Schema.

Não é possível iniciar outra regeneração enquanto um trabalho de esquema já estiver em andamento (a opção fica indisponível enquanto o status for Generating). Apenas um trabalho de geração de esquema pode ser executado por vez por empresa. Regenerar o esquema detecta apenas novos objetos e não exclui objetos que já existem no esquema.

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 quando um objeto de atributo personalizado aninhado é alterado. Essa opção não está disponível para alterações em vetores de objeto. Se você não vir uma opção para visualizar o explorador de jornadas, verifique se você gerou um esquema.

Por exemplo, em uma campanha baseada em ação, você pode adicionar uma nova ação-gatilho para Alterar valor de atributo personalizado para direcionar usuários que alteraram suas preferências de escritório do bairro.

Para configurar esse disparador em uma campanha baseada em ação:

  1. Crie ou edite uma campanha e defina o tipo de entrega como Entrega baseada em ação.
  2. Nas configurações de disparador, selecione Alterar valor de atributo personalizado.
  3. Selecione o caminho do atributo personalizado aninhado que você deseja monitorar. Por exemplo, selecione preferences.neighborhood_office.
  4. Selecione a condição de disparador desejada, como qualquer novo valor.
  5. Termine de configurar a mensagem e o público da sua campanha e, em seguida, lance a campanha.

Solução de problemas

Valores de atributos personalizados aninhados não aplicados de forma consistente

Se você perceber que os valores de atributos personalizados aninhados não estão sendo adicionados aos perfis de usuário de forma consistente, o problema geralmente está relacionado a incompatibilidades de tipo de dados.

Para diagnosticar e resolver esse problema:

  1. Compare exemplos de usuários: Obtenha um exemplo de usuário bem-sucedido e um malsucedido em que o atributo personalizado aninhado deveria ter sido definido.
  2. Revise a estrutura de dados: Visualize e compare os valores do atributo personalizado em ambos os perfis:
    • As propriedades estão armazenadas em um objeto?
    • As propriedades estão armazenadas como um vetor de propriedades?
  3. Verifique o filtro de segmentação: Compare a estrutura de dados armazenada com a forma como o atributo personalizado aninhado é referenciado nos seus filtros de segmentação.
  4. Verifique o tipo de dados: Para identificar o tipo de dados de um atributo personalizado:
    • Acesse Configurações de dados > Atributos personalizados.
    • Pesquise o atributo personalizado de nível superior que contém o atributo aninhado que você deseja verificar.
    • Se a linha exibir Generate Schema, selecione essa opção para gerar o esquema primeiro.
    • Após o esquema ser gerado, selecione o ícone de mais na coluna Attribute Name para esse atributo.
    • No modal Edit schema, revise os atributos aninhados e seus valores correspondentes na coluna Data type.

Se você descobrir que o tipo de dados não corresponde ao formato pretendido nos perfis de usuário, remova o valor formatado incorretamente dos perfis de usuário afetados e reenvie o atributo no formato correto usando a solicitação de API ou o método do SDK apropriado.

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ê precisa que todas as condições correspondam ao mesmo item dentro de um vetor, use a segmentação multicritério no mesmo caminho, ou reestruture seus dados para evitar correspondência entre itens.

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
        }
      }
    }
  ]
}
New Stuff!