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.

Digamos que você queira definir um atributo personalizado no perfil do usuário chamado favorite_book. Esse atributo personalizado pode ser definido como um objeto que tem os atributos aninhados title, author e publishing_date, da seguinte forma:

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

Esses dados aninhados permitem que você crie segmentos usando informações de um objeto de atributo personalizado e personalize suas mensagens usando um objeto de atributo personalizado e o Liquid.

Os objetos de atributos personalizados podem conter tipos de dados, como:

• Números
• Strings
• Booleanos
• Matrizes
• Horário
  • Ao filtrar um atributo personalizado de tempo aninhado, você pode optar por filtrar com base no “Dia do ano” ou na “Hora”. “Dia do Ano” verificará apenas o mês e o dia para comparação. “Time” comparará o registro de data e hora completo, incluindo o ano.
• Outros objetos
• Vetores de objetos

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.
• Nem todos os Braze Partners suportam atributos personalizados aninhados. Consulte a documentação do parceiro para confirmar se as integrações com parceiros específicos suportam esse recurso.
• Os atributos personalizados aninhados não podem ser usados como um filtro ao fazer uma chamada à API do Connected Audience.

Exemplo de API

• criar
• atualização
• excluir

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

• sdk para android
• swift sdk
• sdk da web

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 do Liquid

O exemplo de modelo do 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 (ponto final), 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ê poderá gerar um esquema e usar o explorador de objetos aninhados para que o Braze preencha essa jornada para você.

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

Para segmentar com atributos personalizados aninhados, selecione o filtro Atributos personalizados aninhados para expor 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 Tempo comparará o registro de data e hora completo, incluindo o ano.

Segmentação multicritério

Use o Multi-Criteria Segmentation 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, o Braze gerará automaticamente o código Liquid que retorna um vetor de objeto que contém 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 o site 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: “Alcance sua meta de aposentadoria mais rapidamente, faça um depósito usando nosso novo recurso de depósito rápido!”

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, execute as seguintes etapas.

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 da atribuição, selecione Gerar esquema.

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

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

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 de active (independentemente de a conta estar ativa ou não)
• Um tipo de número com uma chave de balance (valor do saldo na conta)
• Um tipo de string com uma chave de 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 que possamos 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 da jornada. Isso exibirá uma representação de seu objeto ou vetor de objetos. Você pode selecionar qualquer um dos itens listados e a Braze os inserirá no campo da jornada para você. Neste exemplo, precisamos obter o saldo. Selecione o saldo e a jornada (nesse caso, [].balance) é 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 aí! 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 no Braze gerou uma representação visual de 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 no bairro.

Personalização

Usando o modal Add Personalization, você também pode inserir atributos personalizados aninhados em 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 localização 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 gerar novamente o esquema. Para saber mais informações detalhadas sobre esquemas, consulte a seção deste artigo sobre como gerar um esquema.

Para gerar novamente o esquema de seu atributo personalizado aninhado:

1. Acesse Configurações de dados > Atributos personalizados.
2. Procure seu atributo personalizado aninhado.
3. Na coluna Nome da atribuição de seu atributo, selecione para gerenciar o esquema.
4. Será exibido um modal. Selecione Gerar esquema novamente.

A opção de regenerar o esquema será desativada se houver menos de 24 horas desde que o esquema foi regenerado pela última vez. 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, a atribuição pode não estar sendo ingerida com frequência suficiente. Os dados de usuários são amostrados em dados anteriores enviados ao Braze para a atribuição aninhada dada. Se a atribuição não for ingerida o suficiente, ela não será selecionada para o esquema.

Pontos de dados

Qualquer chave que seja atualizada 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
        }
      }
    }
  ]
}