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 tanto com eventos personalizados quanto com 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 adição .

Se novas propriedades forem enviadas no futuro, elas não estarão no esquema até que ele seja gerado novamente. 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. Note que um schema não é necessário. Consulte as seções a seguir para ver exemplos de uso:

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

Corpo da requisição da API

• music example
• restaurant example

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 aninhadas, se o ano for menor que 0 ou maior que 3000, a Braze não armazena esses valores no perfil do usuário.

Templates Liquid

A seguir, mostramos como criar um template Liquid que faz referência às propriedades aninhadas solicitadas na requisição de API anterior.

• music example
• restaurant example

Disparo de mensagens

Para usar essas propriedades para disparar uma Campaign ou um Canvas, selecione seu evento personalizado ou compra e adicione um filtro de Nested Property. Os disparadores de eCommerce Place Order e Update Cart (disparadores de eCommerce) aceitam os mesmos tipos de filtro.

Importante

Os filtros de Nested Property não são compatíveis com disparadores de mensagens no app. Você ainda pode usar propriedades aninhadas para personalização via Liquid em mensagens no app.

Filtros de propriedades de evento de nível superior (básico) — incluindo propriedades do tipo array — podem ser usados para disparar mensagens no app. Esses filtros são separados dos filtros de Nested Property.

• music example
• restaurant example

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 corresponder se qualquer item no array percorrido atender à propriedade do evento.

Importante

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

Por exemplo, digamos que o Canvas A tenha o filtro de propriedade aninhada de evento personalizado baseado em ação equals “smartwatch”, e o Canvas B tenha 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 ., escape-os envolvendo o trecho em 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. Após 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

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

Testando objetos aninhados em mensagens

A ferramenta Preview & Test do dashboard não oferece suporte para adicionar dados simulados para objetos aninhados ou atributos personalizados aninhados. Para testar mensagens que referenciam dados aninhados por meio de Liquid, você pode pré-visualizar mensagens com atributos aninhados como um usuário existente que possua esse atributo aninhado, ou pré-visualizar mensagens com propriedades de evento personalizado 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 busque 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 pré-visualizadas no dashboard porque exigem um disparo de evento em tempo real. Para testar:

1. Crie uma Campaign ou etapa do Canvas que segmente apenas seus usuários teste e seja disparada por (ou referencie) o evento personalizado com propriedades aninhadas.
2. Lance a campanha para 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

O uso de objetos aninhados registra pontos de dados adicionais?

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

Qual a quantidade de dados aninhados que pode ser enviada?

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.