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

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

Considerações

• Os atributos personalizados aninhados são destinados a atributos personalizados enviados pelo SDK ou pela 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.
• Nomes de chaves e valores de string têm um limite de 255 caracteres.
• Nomes de chaves não podem conter espaços.
• Pontos (.) e cifrões ($) não são caracteres suportados em uma carga útil da 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íficas oferecem suporte a esse recurso.
• Atributos personalizados aninhados não podem ser usados como filtro ao fazer uma chamada para a API 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 array. Quando você seleciona um atributo, o seletor de esquema de propriedades inclui caminhos de array (usando a notação []) para campos de array aninhados. Para ocultar atributos personalizados de array de nível superior desse filtro, entre em contato com o suporte da Braze.
• Ao visualizar a prévia de mensagens no dashboard usando Prévia como usuário personalizado, você só pode inserir dados fictícios como uma string ou um array de strings. Objetos aninhados não são suportados. Para visualizar a prévia de uma mensagem que faz referência a atributos personalizados aninhados, selecione um usuário existente que já tenha o atributo aninhado no perfil. Para propriedades de eventos personalizados aninhadas, você precisa lançar uma campanha ativa direcionada a um usuário teste para verificar a renderização.

Exemplo de API

• criar
• atualizar
• excluir

Veja a seguir um exemplo de /users/track com um objeto “Most Played Song” (Música mais tocada). 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á uma mesclagem profunda da sua atualização com os dados do objeto existente. A mesclagem profunda garante que todos os níveis de um objeto sejam mesclados em outro objeto, e não 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
      }
    }
  ]
}

Depois que essa solicitação for recebida, 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. Por padrão, _merge_objects é false.

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

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.

• android sdk
• swift sdk
• web sdk
• unity 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);

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

1
2
3
4

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

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

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 “Datas importantes” é 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.

Nota

Quando _merge_objects é true, um valor null sem $time exclui um campo de data aninhado existente do objeto. Se o campo ainda não existir, a Braze ignora o valor null e não cria o campo. A Braze não retorna um erro em nenhum dos casos.

Se você não capturou datas como propriedades de objeto 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, todo o atributo personalizado aninhado 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 em Liquid

O exemplo de template em Liquid a seguir mostra como referenciar as propriedades do objeto de atributo personalizado salvas na solicitação de API anterior e usá-las no envio de mensagens.

Use a tag de personalização custom_attribute e a notação de ponto para acessar as propriedades de um objeto. Informe o nome do objeto e, se for um vetor de objetos, a posição no vetor. Depois, adicione um ponto e o 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 em que você quer adicionar a personalização.
2. No criador de mensagem, insira o snippet Liquid onde o valor deve aparecer.
3. Use Prévia e teste com um usuário que já tenha o atributo personalizado aninhado no perfil para confirmar que o valor é renderizado como esperado.

Personalização

Você pode usar Adicionar personalização para inserir um atributo personalizado aninhado na sua mensagem.

Para abrir Adicionar personalização:

1. Acesse uma Campaign ou Canvas e abra a etapa de mensagem em que você quer adicionar a personalização.
2. No criador de mensagem, selecione Personalização para abrir a barra lateral Adicionar personalização. Nela, você pode escolher as opções de personalização.

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

1. Em Tipo de personalização, selecione Atributos personalizados aninhados.
2. Em Atributo de nível superior, selecione o caminho do atributo personalizado aninhado que você quer inserir. Por exemplo, selecione preferences.neighborhood_office.
3. Opcional: Em Valor padrão, insira um valor de fallback para usuários que não têm um valor próprio para esse atributo.
4. Revise o Snippet Liquid gerado para confirmar que ele corresponde ao caminho esperado.
5. Selecione Inserir.

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

Dica

Se a opção de inserir atributos personalizados aninhados não aparecer, verifique se um esquema foi gerado.

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.

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

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

Para configurar esse gatilho em uma Campaign baseada em ação:

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

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 outro malsucedido em que o atributo personalizado aninhado deveria ter sido definido.
2. Revise a estrutura de dados: Visualize e compare os valores dos atributos personalizados nos dois 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. Confirme 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 mostrar Gerar esquema, selecione essa opção para gerar o esquema primeiro.
   • Depois que o esquema for gerado, selecione o ícone de adição na coluna Nome do atributo desse atributo.
   • No modal Editar esquema, revise os atributos aninhados e os valores correspondentes na coluna Tipo de dados.

Se você descobrir que o tipo de dados não corresponde ao formato pretendido entre os 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 da segmentação com vetores de objetos

Quando você usa vários filtros de Atributo personalizado aninhado com lógica AND para segmentar um vetor de objetos, cada filtro é avaliado de forma independente em todos os itens do vetor. Um usuário se qualifica para o Segment se qualquer item do vetor atender a 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 atenda às duas condições sozinho, o usuário ainda entra no Segment.

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

Pontos de dados

Cada 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.