Perguntas frequentes sobre objetos personalizados

O que você vai aprender

Saiba mais sobre as perguntas frequentes relacionadas a objetos personalizados no Klaviyo. Se você não encontrar sua pergunta no recurso abaixo, entre em contato no nosso fórum da Community.

Perguntas gerais sobre objetos

Preciso de um desenvolvedor para criar um objeto?

Você precisa de um desenvolvedor para enviar dados personalizados por meio de APIs. Você pode criar a fonte de dados e configurar o objeto no Klaviyo.

Posso criar objetos personalizados usando formulários da Klaviyo ou uploads de CSV?

Formulários do Klaviyo e uploads de CSV não enviam registros de objetos personalizados. Use a API para enviar seus dados personalizados e, em seguida, mapeie-os para um objeto no Klaviyo.

Quando devo usar um objeto personalizado em vez de uma propriedade do perfil ou evento?

Você deve usar objetos personalizados quando houver uma relação de muitos para um entre a categoria que seu objeto personalizado representa e seus perfis. Por exemplo, se você quiser manter informações sobre os animais de estimação do seu cliente, e seu cliente puder ter mais de um animal de estimação, representá-los como um objeto personalizado funciona muito melhor do que Propriedades do perfil ou eventos.

Ao fazer rastreamento de itens como o status de um programa de associação, em que um perfil só pode ter um status de cada vez, as Propriedades do perfil são mais adequadas. No entanto, se você também quiser armazenar outros detalhes sobre a associação de um perfil, um objeto pode funcionar melhor.

Ao fazer o rastreamento de algo mais amplo, como quantas vezes um destinatário abriu um e-mail, recomendamos usar eventos.

Posso atualizar meu objeto personalizado após a criação?

Sim, você pode adicionar propriedades não obrigatórias até o limite de propriedades do objeto da sua conta. Para saber mais, leia sobre atualizar um objeto personalizado.

Quando devo emitir um evento em vez de atualizar as propriedades do objeto personalizado?

Os eventos servem para acionar fluxos rapidamente, permitindo que você envie mensagens oportunas e relevantes. Quando o status de um objeto muda e você quer disparar uma mensagem como resultado, você deve atualizar o objeto com as novas informações e nos enviar um evento para disparar o fluxo.

Você pode personalizar modelos com as informações do objeto no fluxo acionado por evento. Há duas maneiras de fazer isso:

1. Inclua as propriedades de que você precisa nos dados do evento e, em seguida, faça referência a elas no seu modelo. Por exemplo, se o evento incluir uma propriedade pet_name, use {{ event.pet_name }}. Isso funciona bem quando a rapidez é importante.
2. Inclua o ID do objeto nos dados do evento e, em seguida, recupere o objeto no modelo. Para um objeto chamado Pet, com uma propriedade Name e uma propriedade de evento chamada pet_id, use {% customobject event.pet_id object_type_title="Pet" as pet %}{{ pet.Name }}{% endcustomobject %}. Substitua esses nomes pelos nomes do seu próprio objeto, propriedade e campo de evento. Pode levar um tempo para que as atualizações do objeto fiquem disponíveis; por isso, uma mensagem do fluxo pode ser enviada antes que o objeto tenha os valores mais recentes.

Dúvidas sobre o envio de dados de objetos

Como começo a enviar meus dados para objetos personalizados?

1. Crie uma nova fonte de dados usando nossa API.
2. Defina sua estrutura de dados usando o JSON de exemplo em Criar registros de fonte de dados em massa.
3. Envie os registros da sua fonte de dados para a Klaviyo via API.
4. Criar seu objeto personalizado usando essa fonte de dados. Escolha um ID de objeto exclusivo e mapeie as propriedades que você quer usar.
5. Crie a relação entre seu objeto personalizado e seus perfis mapeando os identificadores de perfil nos seus dados, como e-mail ou número de telefone.
6. Revise seus mapeamentos, clique em Criar objeto e depois clique em Criar objeto novamente para confirmar.

Como as fontes de dados são criadas e usadas?

Quando você cria uma fonte de dados pela API, a Klaviyo retorna um identificador exclusivo como parte da resposta à sua solicitação de API. Isso permite que a Klaviyo identifique fontes de dados, especialmente em casos em que uma conta tem várias fontes de dados (por exemplo, 1 para cada integração personalizada, data warehouse ou integração personalizada de terceiros da qual a marca depende para o seu negócio).

Com esse identificador exclusivo, seu desenvolvedor pode criar registros de fonte de dados pela API da Klaviyo.

Como devo formatar meus dados?

Seu desenvolvedor precisará enviar dados no formato JSON para a Klaviyo. Para uma propriedade com vários valores de texto, envie um array de strings e mapeie-o como Lista (Texto). Você pode filtrar esses valores em segmentos e fluxos. Consulte a referência de condições de segmento para mais informações sobre a filtragem.

Tipos de dados compatíveis em objetos personalizados:

• Texto
• Número (inteiro)
• Número (decimal)
• Carimbo de data/hora: datas e horários são armazenados em UTC. Um valor sem fuso horário, como 2025-04-03, é tratado como 2025-04-03 00:00:00 UTC. Um valor com um deslocamento, como 2025-04-03T00:00:00+03:00, é convertido em 2025-04-02 21:00:00 UTC.
• Booleano
• Lista (texto)

Lista (Texto) oferece suporte a arrays de strings, como ["cachorro", "gato"]. Ela não oferece suporte a arrays de números, listas aninhadas ou objetos. Para ver um payload de exemplo do registro da fonte de dados na API, consulte Criar registros de fonte de dados em massa.

Quais são os limites de dados para objetos personalizados?

Cada propriedade de objeto personalizado mapeada pode conter até 2 KB, e cada registro de objeto personalizado mapeado pode conter até 8 KB.

Posso mapear com dados aninhados?

Recomendamos definir seu objeto JSON sem aninhar as propriedades que você quer usar no seu objeto personalizado. Para dados aninhados, selecione uma propriedade no menu suspenso Propriedade da fonte de dados ou insira manualmente o caminho JSON dela. Para uma lista de valores de texto, mapeie a própria lista como Lista (texto). Para mapear um único item de um array, use a posição dele, como [0] para o 1º item ou [1] para o 2º.

Posso associar vários identificadores a um perfil?

Sim, se você quiser usar 2 ou mais identificadores de perfil (por exemplo, e-mail e número de telefone) para associar os registros do seu objeto personalizado a um perfil, inclua essas duas propriedades em toda sincronização, mesmo que o valor de uma delas seja nulo. 

Perguntas sobre o uso de objetos com fluxos

Se meu objeto não acionou um fluxo e eu não tenho um ID de objeto de um evento, ainda posso personalizar minhas mensagens?

Sim, você pode usar filtros de objeto para encontrar o objeto certo ao personalizar suas mensagens.

Posso pré-visualizar mensagens do fluxo quando um objeto dispara um fluxo?

Sim. Você pode visualizar mensagens que usam dados de {{ object }} em um fluxo acionado por data com base em um objeto personalizado antes de ativar o fluxo.

Para visualizar uma mensagem:

1. Abra uma mensagem em um fluxo acionado por data com base em um objeto personalizado e, em seguida, clique em Visualizar no editor de e-mail.
2. Selecione um perfil associado a um registro desse objeto e, em seguida, revise a mensagem personalizada.

A prévia usa um objeto de exemplo associado ao perfil selecionado. Se nenhum estiver disponível, ele usa um registro de amostra do mesmo tipo de objeto. Confira os valores exibidos: a prévia não confirma qual registro vai acionar o fluxo. Se nenhum registro estiver disponível, não há dados de objeto para visualizar na prévia.

Posso atualizar meus objetos usando ações de fluxo, como webhooks e código da Klaviyo?

No momento, recomendamos que você atualize primeiro sua fonte de dados original e, em seguida, envie o objeto revisado de volta para a Klaviyo no formato permitido. Se esses dois sistemas ficarem fora de sincronia, você corre o risco de enviar um registro desatualizado de volta para a Klaviyo a partir do seu sistema, revertendo-o para o valor original.