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:

Limitaçõ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.
• 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

• create
• update
• delete

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

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

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

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

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

Captura de datas como propriedades do objeto

Para capturar datas como propriedades do objeto, 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. O valor para essas 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 fazer referência às propriedades do objeto de atributo personalizado salvas na solicitação anterior da API 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. Especifique o nome do objeto (e a posição no vetor, se estiver fazendo referência a 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”

Segmentação

É possível criar segmentos com base em atributos personalizados aninhados para direcionar ainda mais seus usuários. Para fazer isso, filtre seu segmento com base no objeto de atributo personalizado e, em seguida, especifique a jornada para o nome da propriedade e o valor associado que deseja segmentar. Se não tiver certeza de como é essa jornada, você pode gerar um esquema e usar o explorador de objetos aninhados para que a Braze preencha essa jornada para você.

Depois de adicionar uma jornada à sua propriedade, selecione Validar para verificar se o valor no campo de jornada é válido.

Para segmentar com atributos personalizados aninhados, selecione o filtro Nested Custom Attributes para exibir um menu suspenso no qual você pode selecionar um atributo personalizado aninhado específico.

Ao trabalhar com segmentação de atributos personalizados aninhados, você terá acesso a um novo comparador agrupado por tipo de dados. Por exemplo, como play_analytics.count é um número, você pode selecionar um comparador na categoria Número.

Filtragem de tipos de dados de tempo

Ao filtrar um atributo personalizado de tempo aninhado, você pode optar por filtrar com operadores nas categorias Dia do ano ou Hora ao comparar o valor da data.

Se você selecionar um operador na categoria Dia do ano, somente o mês e o dia serão verificados para comparação, em vez do registro de data e hora completo do valor do atributo personalizado aninhado. A seleção de um operador na categoria Hora comparará o registro de data e hora completo, incluindo o ano.

Segmentação multicritério

Use a Segmentação multicritério para criar um segmento que corresponda a vários critérios em um único objeto. Isso qualifica o usuário para o segmento se ele tiver pelo menos um vetor de objeto que corresponda a todos os critérios especificados. Por exemplo, os usuários só corresponderão a esse segmento se a chave não estiver em branco e se o número for maior que 0.

Você também pode usar o recurso Copiar Liquid para segmento para gerar o código Liquid para esse segmento e usá-lo em uma mensagem. Por exemplo, digamos que você tenha um vetor de objetos de conta e um segmento que direciona os clientes com contas ativas tributáveis. Para fazer com que os clientes contribuam para a meta da conta associada a uma de suas contas ativas e tributáveis, você deverá criar uma mensagem para incentivá-los.

Quando você selecionar Copiar Liquid para o segmento, a Braze gerará automaticamente o código Liquid que retorna um vetor de objeto contendo apenas contas ativas e tributáveis.

1
2
3
4
5
6
7
{% assign segmented_nested_objects = '' | split: '' %}
{% assign obj_array = {{custom_attribute.${accounts}}} %}
{% for obj in obj_array %}
  {% if obj["account_type"] == 'taxable' and obj["active"] == true %}
    {% assign segmented_nested_objects = obj_array | slice: forloop.index0 | concat: segmented_nested_objects | reverse %}
  {% endif %}
{% endfor %}

A partir daí, você pode usar segmented_nested_objects e personalizar sua mensagem. Neste exemplo, queremos pegar uma meta da primeira conta ativa tributável e personalizá-la:

1
Get to your {{segmented_nested_objects[0].goal}} goal faster, make a deposit using our new fast deposit feature!

Isso retorna a seguinte mensagem para seu cliente: “Get to your retirement goal faster, make a deposit using our new fast deposit feature!”

Gerar um esquema usando o explorador de objetos aninhados

Você pode gerar um esquema para seus objetos para criar filtros de segmento sem precisar memorizar jornadas de objetos aninhados. Para fazer isso, siga as etapas abaixo.

Etapa 1: Gerar um esquema

Para este exemplo, suponha que tenhamos um vetor de objetos accounts que acabamos de enviar à Braze:

1
2
3
4
5
6
7
8
{"accounts": [
  {"type": "taxable",
  "balance": 22500,
  "active": true},
  {"type": "non-taxable",
  "balance": 0,
  "active": true}
]}

No dashboard da Braze, acesse Configurações de dados > Atributos personalizados.

Procure seu objeto ou vetor de objetos. Na coluna Nome do atributo, selecione Gerar esquema.

Depois que o esquema for gerado, um novo botão plus será exibido no lugar do botão Gerar esquema. Você pode clicar nele para ver o que a Braze sabe sobre esse atributo personalizado aninhado.

Durante a geração do esquema, a Braze analisa os dados anteriores enviados e cria uma representação ideal dos seus dados para esse atributo. A Braze também analisa e adiciona um tipo de dados para seus valores aninhados. Isso é feito por meio da amostragem dos dados anteriores enviados à Braze para o atributo aninhado em questão.

Para o nosso vetor de objetos accounts, você pode ver que, dentro do vetor de objetos, há um objeto que contém o seguinte:

• Um tipo booleano com uma chave active (independentemente de a conta estar ativa ou não)
• Um tipo de número com uma chave balance (valor do saldo na conta)
• Um tipo de string com uma chave type (conta não tributável ou tributável)

Agora que analisamos e criamos uma representação dos dados, vamos criar um segmento.

Etapa 2: Criar um segmento

Vamos direcionar os clientes que têm um saldo inferior a 100 para enviar a eles uma mensagem incentivando-os a fazer um depósito.

Crie um segmento e adicione o filtro Nested Custom Attribute e, em seguida, pesquise e selecione seu objeto ou vetor de objetos. Aqui adicionamos o vetor de objetos accounts.

Selecione o botão plus no campo de jornada. Isso exibirá uma representação do seu objeto ou vetor de objetos. Você pode selecionar qualquer um dos itens listados e a Braze os inserirá no campo de jornada para você. Neste exemplo, precisamos obter o saldo. Selecione o saldo e a jornada (nesse caso, [].balance) será preenchida automaticamente no campo de jornada.

Você pode selecionar Validar para verificar se o conteúdo do campo de jornada é válido e, em seguida, criar o restante do filtro conforme necessário. Aqui, especificamos que o saldo deve ser menor que 100.

É isso! Você acabou de criar um segmento usando um atributo personalizado aninhado, tudo sem precisar saber como os dados estão estruturados. O explorador de objetos aninhados da Braze gerou uma representação visual dos seus dados e permitiu que você explorasse e selecionasse exatamente o que precisava para criar um segmento.

Disparar alterações em atributos personalizados aninhados

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

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

Personalização

Usando o modal Adicionar personalização, você também pode inserir atributos personalizados aninhados no envio de mensagens. Selecione Nested Custom Attributes 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 local do bairro com base nas preferências do usuário.

Regenerar esquemas

Depois que um esquema é gerado, ele pode ser regenerado uma vez a cada 24 horas. Esta seção descreve como regenerar o esquema. Para informações mais detalhadas sobre esquemas, consulte a seção deste artigo sobre como gerar um esquema.

Para regenerar o esquema do seu atributo personalizado aninhado:

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

A opção de regenerar o esquema será desativada se tiverem se passado menos de 24 horas desde a última regeneração. A regeneração do esquema só detectará novos objetos e não excluirá os objetos que existem atualmente no esquema.

Se os dados não aparecerem como esperado após a regeneração do esquema, o atributo pode não estar sendo ingerido com frequência suficiente. Os dados de usuários são amostrados com base nos 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.

Comportamento de segmentação com vetores de objetos

Quando você usa vários filtros 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 segmento 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 segmento 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 segmento.

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

Pontos de dados

Qualquer chave enviada consome um ponto de dados. Por exemplo, esse objeto inicializado no perfil do 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
        }
      }
    }
  ]
}