Atributos personalizados aninhados

Esta página aborda atributos personalizados aninhados, que permitem definir um conjunto de atributos como propriedade de outro atributo. Em outras palavras, ao definir um objeto de atributo personalizado, você 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

• Atributos personalizados aninhados são destinados a atributos personalizados enviados pelo SDK ou pela API da Braze.
• 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 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 específicas de parceiros oferecem suporte a esse recurso.
• Atributos personalizados aninhados não podem ser usados como filtro ao fazer uma chamada de API de 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);

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.

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

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.

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 Nome do atributo do seu atributo, selecione para gerenciar o esquema.
4. Um modal será exibido. Selecione Regenerar esquema.

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.

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 campanha baseada em ação, você pode adicionar uma nova ação-gatilho para Alterar valor do atributo personalizado 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 Atributo personalizado aninhado 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 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
        }
      }
    }
  ]
}