Objetos aninhados em eventos personalizados

Esta página aborda como enviar dados JSON aninhados como propriedades de eventos personalizados e compras, e como usar esses objetos aninhados em seu envio de mensagens.

Você pode usar objetos aninhados — objetos que estão dentro de outro objeto — para enviar dados JSON aninhados como propriedades de eventos personalizados e compras. Esses dados aninhados podem ser usados para modelar informações personalizadas em mensagens, disparar envios de mensagens e segmentar usuários.

Considerações

• Dados aninhados são compatíveis com eventos personalizados e eventos de compra, mas não com outros tipos de evento.
• Objetos de propriedade de evento que contêm valores de array ou objeto podem ter uma carga útil de propriedade de evento de até 100 KB.
• Esquemas de propriedade de evento não podem ser gerados para eventos de compra.
• Os esquemas de propriedade de evento são gerados por amostragem de eventos personalizados das últimas 24 horas.

Versões mínimas do SDK

As seguintes versões do SDK são compatíveis com objetos aninhados:

Etapa 1: Gerar um esquema

Você pode acessar os dados aninhados no seu evento personalizado gerando um esquema para cada evento com propriedades de evento aninhadas. Para gerar um esquema:

1. Acesse Configurações de Dados > Eventos Personalizados.
2. Selecione Gerenciar Propriedades para os eventos com propriedades aninhadas.
3. Selecione o botão para gerar o esquema. Para visualizar o esquema, selecione o botão de mais .

Se novas propriedades forem enviadas no futuro, elas não estarão no esquema até que ele seja regenerado. Os esquemas podem ser regenerados a cada 24 horas.

Etapa 2: Usar o objeto aninhado

Você pode referenciar os dados aninhados durante a segmentação e a personalização. Não é necessário ter um schema. Consulte as seções a seguir para exemplos de uso:

• Corpo da solicitação da API
• Templates Liquid
• Disparo de mensagens
• Segmentação
• Personalização

Corpo da solicitação da API

• exemplo de música
• exemplo de restaurante

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

...
"properties": {
  "songs": [
    {
      "title": "Smells Like Teen Spirit",
      "artist": "Nirvana",
      "album": {
        "name": "Nevermind",
        "yearReleased": "1991"
      }
    },
    {
      "title": "While My Guitar Gently Weeps",
      "artist": "the Beatles",
      "album": {
        "name": "The Beatles",
        "yearReleased": "1968"
      }
    }
  ]
}
...

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

...
"properties": {
  "r_details": {
    "name": "SandwichEmperor",
    "identifier": "12345678",
    "location" : {
      "city": "Montclair",
      "state": "NJ"
    }
  }
}
...

Nota

Para propriedades de evento personalizado aninhadas, se o ano for menor que 0 ou maior que 3000, a Braze não armazena esses valores no usuário.

Templates Liquid

A seguir, veja como criar um template Liquid que referencia as propriedades aninhadas solicitadas na solicitação de API anterior.

• exemplo de música
• exemplo de restaurante

Disparo de mensagens

Para usar essas propriedades no disparo de uma Campaign, selecione seu evento personalizado ou compra e adicione um filtro de Nested Property. Os disparos de e-commerce Place Order e Update Cart aceitam os mesmos tipos de filtro. O disparo de mensagens ainda não é compatível com mensagens no app, mas as propriedades aninhadas na personalização Liquid nas mensagens ainda serão exibidas.

• exemplo de música
• exemplo de restaurante

Disparando uma Campaign com propriedades aninhadas do evento “Created Playlist”:

A condição de disparo songs[].album.yearReleased “is” “1968” corresponderá a um evento em que qualquer uma das músicas tenha um álbum lançado em 1968. Usamos a notação de colchetes [] para percorrer arrays e fazemos a correspondência se qualquer item no array percorrido corresponder à propriedade do evento.

Importante

O filtro does not equal só corresponde se nenhuma das propriedades no array for igual ao valor fornecido.

Por exemplo, digamos que o Canvas A tem o filtro de propriedade aninhada de evento personalizado baseado em ação equals “smartwatch”, e o Canvas B tem o filtro de propriedade aninhada de evento personalizado baseado em ação does not equal “simphone”. Se você tiver “smartwatch” e “simphone” nas suas propriedades, ambos os Canvas serão disparados. Mas se você tiver “simphone” ou “sim only” em qualquer propriedade, nenhum Canvas será disparado.

Disparando uma Campaign com propriedades aninhadas do evento “Ordered”:

r_details.name: “SandwichEmperor”
r_details.location.city: “Montclair”

Nota

Se a propriedade do seu evento contiver os caracteres [] ou ., faça o escape envolvendo o trecho entre aspas duplas. Por exemplo, "songs[].album".yearReleased corresponderá a um evento com a propriedade literal "songs[].album".

Segmentação

Para segmentar usuários com base em propriedades de evento aninhadas, você deve usar extensões de segmento. Depois de gerar um schema, o explorador de objetos aninhados será exibido na seção de segmentação.

A segmentação usa a mesma notação do disparo (consulte Disparo de mensagens).

Para editar ou criar extensões de segmento, você precisará da permissão “Edit Segments”.

Personalização

No modal Add Personalization, selecione Advanced Event Properties como o tipo de personalização. Isso permite adicionar propriedades de evento aninhadas após a geração de um schema.

Testando objetos aninhados em mensagens

A ferramenta Preview & Test do dashboard não permite adicionar dados simulados para objetos aninhados ou atributos personalizados aninhados. Para testar mensagens que referenciam dados aninhados por meio de Liquid, você pode visualizar mensagens com atributos aninhados como um usuário existente que possua esse atributo aninhado, ou visualizar mensagens com propriedades de evento personalizadas lançando uma campanha ativa para usuários teste.

Atributos personalizados aninhados

1. Importe os atributos aninhados para o perfil de usuário teste por meio da API.
2. Na sua Campaign ou Canvas, acesse Preview & Test.
3. Selecione Preview as user e procure o usuário teste. O Liquid será resolvido usando os atributos aninhados reais no perfil desse usuário.

Propriedades de evento aninhadas

As propriedades de evento aninhadas não podem ser visualizadas no dashboard porque exigem um disparo de evento em tempo real. Para testar:

1. Crie uma Campaign ou etapa do Canvas que tenha como alvo apenas seus usuários teste e que seja disparada por (ou referencie) o evento personalizado com propriedades aninhadas.
2. Lance a Campaign para o seu público de teste.
3. Registre o evento personalizado com a carga útil do objeto aninhado no perfil do seu usuário teste (usando a API ou o SDK).
4. Verifique se a mensagem é renderizada corretamente com os valores das propriedades aninhadas.

Perguntas frequentes

Usar objetos aninhados gera pontos de dados adicionais?

Não há mudança na forma como registramos pontos de dados ao adicionar essa funcionalidade. A segmentação baseada em objetos aninhados usa extensões de segmento, que não consomem pontos de dados adicionais.

Qual é o limite de dados aninhados que podem ser enviados?

Se uma ou mais propriedades do evento contêm dados aninhados, a carga útil máxima para todas as propriedades combinadas de um evento é de 100 KB. Qualquer solicitação que exceda esse limite de tamanho será rejeitada.