Introdução ao código

O que você vai aprender

Saiba mais sobre o Code e como criar funções personalizadas que são executadas diretamente pelo Klaviyo.

O código requer desenvolvimento personalizado e a equipe de suporte da Klaviyo não pode oferecer assistência prática. Se o senhor não tiver um desenvolvedor na sua equipe e não se sentir à vontade para escrever códigos por conta própria, considere a possibilidade de entrar em contato com um parceiro da Klaviyo para obter ajuda.

Antes de começar

O que é código?

O código permite que o senhor execute funções personalizadas em resposta a eventos capturados no Klaviyo. O senhor pode escrever suas próprias funções Javascript ou Python no editor de código, e elas são executadas diretamente na plataforma.

Com o código, você pode enviar dados para sistemas externos sem precisar configurar um ponto de extremidade HTTP público para receber webhooks e criar uma funcionalidade personalizada que é acionada em resposta à ocorrência de um evento. Você também pode acessar vários módulos pré-configurados populares para facilitar a criação de soluções personalizadas.

Tópicos

O código permite que o senhor execute funções personalizadas em resposta a qualquer evento que possa ser consultado por meio da API Get Events.

tais como:

• Eventos de e-mail (por exemplo, Clicked email, Marked email as spam )
• Eventos de SMS (por exemplo, Sent SMS, Received SMS)
• notificação push de eventos (por exemplo, Received push, Bounced push)
• Eventos de integrações (ou seja, eventos de integrações primárias criadas pela Klaviyo)
• Eventos de API (eventos sincronizados por meio da API da Klaviyo)

Interface de código

Para acessar o Code (Código), navegue até a guia Code (Código) em Advanced Klaviyo Data Platform (Plataforma de dados avançada) > dados Management (Gerenciamento de dados) > Code (Código). 

Para criar uma função personalizada, selecione o botão Criar uma função :

O senhor será levado à página Recipes (Receitas ), onde poderá selecionar uma solução pré-construída para executar ou uma função Python ou Node.js em branco.

Se o senhor selecionar uma receita existente, verá o editor de código com o código da solução, juntamente com uma descrição da funcionalidade. 

Se o senhor selecionar uma função em branco para poder criar suas próprias soluções personalizadas, o modal Details (Detalhes ) será exibido, onde o senhor poderá fazê-lo:

• Dê um nome à sua função
  Um nome para identificar sua função.
• Selecione um tópico para sua função
  O evento que acionará a execução de seu código.
• Selecione um tempo de execução
  O ambiente de tempo de execução no qual o código é executado (ou seja, Python ou Node.js).

Depois de fazer as seleções necessárias e selecionar o botão Create function (Criar função ), o senhor será levado a uma interface com as seguintes guias: 

• Editor 
• Saída de teste 
• Registros

Concessão de permissões

Na primeira vez que o senhor criar uma função por meio do Code, será solicitado a autenticar o aplicativo Code OAuth. Isso é necessário para que suas funções de código possam acessar os dados em sua conta Klaviyo.

Depois de conceder acesso, o senhor será levado ao editor de código.

Editor

Na página Editor em Code, o senhor verá a página dividida em 3 guias:

• Código
  A guia código tem um editor onde o senhor pode escrever funções Python ou Javascript.
• Módulos
  Os módulos são pacotes de terceiros que adicionam funcionalidade às suas funções.
• Variáveis de ambiente
  As variáveis de ambiente são os pares de valores-chave que sua função acessa quando é executada. 

Código

Na guia Code (Código ), o senhor verá um editor que pode ser usado para escrever funções Python ou Javascript que são executadas em resposta ao tópico selecionado.

Parâmetros da função do manipulador

Para que o Klaviyo execute o código que o senhor escreve, ele deve estar envolvido em uma função chamada "handler" que aceita dois parâmetros:

• Evento
  Consiste nos dados do evento associados ao evento de acionamento no formato JSON:API. Se o acionador não for baseado em eventos (por exemplo, Added to list), o valor desse parâmetro será None (Nenhum ) ou Null (Nulo ), dependendo do idioma.
• Contexto
  Contém metadados adicionais sobre a execução da função, incluindo o perfil associado à invocação da função. O senhor pode acessar o objeto de perfil por meio de context.perfil em Javascript ou context["perfil" ] em Python.

Abaixo estão exemplos dos parâmetros de evento e contexto que são passados para a função de tratamento.

Exemplo de formato de evento

{
    {
  "data": {
   "type": "event",
   "id": "7S2q9haejYG",
   "atributos": {
     "timestamp": 1694435729,
     "event_properties": {
        "MfaEnabled": false,
        "IpAddress": "000.00.0.0",
        "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36",
        "UserRole": "Owner",
        "SessionId": "34sh0a9nh8ngnk2nfacjxmt592yx40ib",
        "LoginType": "Username_password",
        "current_company_id": "XXXXX",
        "$event_id": "1694435729"
      },
     "datetime": "2023-09-11 12:35:29+00:00",
     "uuid": "b0b8fe80-509f-11ee-8001-278cc529fcd3"
    },
   "relacionamentos": {
     "profile": {
       "dados": {
          "type": "profile",
          "id": "123456"
        },
       "links": {
          "self": "https://a.klaviyo.com/api/events/7S2q9haejYG/relationships/profile/",
          "related": "https://a.klaviyo.com/api/events/7S2q9haejYG/profile/"
        }
      },
      metric": {
       "dados": {
          "type": "metric",
          "id": "4Tdup6"
        },
       "links": {
          "self": "https://a.klaviyo.com/api/events/7S2q9haejYG/relationships/metric/",
          "related": "https://a.klaviyo.com/api/events/7S2q9haejYG/metric/"
        }
      }
    },
   "links": {
      "self": "https://a.klaviyo.com/api/events/7S2q9haejYG/"
    }
  }
}

Exemplo de formato de contexto 

{
   "company_id": "XXXXX",
   "trigger": {"type": "event", "uid": "123456"},
   "function_id": "123456",
}

Módulos

Na guia Modules (Módulos ), o senhor pode selecionar entre os módulos pré-construídos mais populares (ou seja, pacotes de terceiros que adicionam recursos às suas funções). 

Para adicionar um módulo externo a ser usado em seu código, selecione o botão Add module (Adicionar módulo ):

No modal que aparece, o senhor pode pesquisar e selecionar o módulo que deseja adicionar: 

Depois de adicionado, o senhor pode usar o módulo com o código que escreve no Klaviyo.

from klaviyo_api importar KlaviyoAPI
importar os
def handler(event, context):
  Klaviyo = KlaviyoAPI(api_key=os.getenv("API"))
  print(Klaviyo.métrica.get_metrics())

importar Klaviyo

def handler(event, context):
  print(Klaviyo.métrica.get_metrics())

importar { Metrics } de 'Klaviyo';
export default async (event, context) => {
  console.log(await Metrics.getMetrics())
}

Variáveis de ambiente 

A guia Environment variables (Variáveis de ambiente ) permite que o senhor defina pares de valores-chave que o código no Klaviyo pode referenciar quando for executado. Elas podem ser usadas para armazenar informações como credenciais e chaves secretas para que suas funções possam acessá-las durante a execução. 

Para adicionar uma variável de ambiente, selecione o botão Add a variable (Adicionar uma variável ): 

No modal que aparece, o senhor pode definir um par chave-valor para sua variável de ambiente. 

Depois de criadas, as variáveis de ambiente serão listadas na página e poderão ser usadas em seu código. 

Saída de teste

A guia Saída de teste em Código permite que o senhor teste seu código com eventos recentes para confirmar que a saída está se comportando conforme o esperado. 

Para testar sua função:

1. Selecione o botão Run test:
   
2. Na janela modal que aparece, selecione um evento para testar. O senhor pode selecionar entre os 10 eventos mais recentes capturados no Klaviyo.
   
3. Depois de selecionar um evento para testar, a saída do teste será exibida:

Registros

A guia Logs mostra a integridade de suas funções de código em andamento. O senhor verá:

• Status
  O progresso da execução de uma função. 
• Tempo de resposta
  O tempo que o código leva para ser executado em resposta a um evento.
• Data
  Um registro de data e hora de quando a função foi executada. 

Limites de taxas

O código Klaviyo tem os seguintes limites de taxa:

• Tempo limite da função
  As funções no Code podem ser executadas por até 15 segundos antes de atingirem o tempo limite.
• Limite de taxa de função
  As funções no Code permitem até 25 execuções simultâneas por função.

Implementação de código 

Para implementar o código que o senhor escreve no editor, alterne o menu suspenso de status para Live. 

Uma vez definido como ativo, o código que o senhor escreve será executado sempre que o evento do tópico for capturado no Klaviyo.

Exemplo de solução

Abaixo está um exemplo de uma solução personalizada sendo implementada com o Code.

No exemplo, os dados do evento são definidos como uma propriedade de perfil para que possam ser usados em e-mails direcionados e na segmentação. O evento personalizado Booked shoot é capturado no Klaviyo quando os clientes reservam uma sessão de fotos com a marca, e os dados sobre a cidade da reserva e o URL associado são definidos como uma propriedade de perfil no respectivo perfil.

Também é criada uma propriedade chamada Recent bookings (Reservas recentes ), que armazena os dados dos 5 eventos de filmagem reservados mais recentes, para que possam ser percorridos e acessados em modelos de e-mail.

Código

O código Python para essa solução é escrito no editor Code e é executado diretamente pelo Klaviyo.

Exemplo de código

Módulos

Neste exemplo, é usado o módulo Klaviyo incorporado. O módulo Klaviyo depende de o módulo Klaviyo-API ser adicionado à função. Uma vez adicionado, o módulo Klaviyo cuidará da autenticação para o senhor, portanto, não é necessária nenhuma chave de API.

Variáveis de ambiente

As variáveis de ambiente podem ser usadas para armazenar informações como credenciais e chaves secretas para que suas funções possam acessá-las durante a execução. Para este exemplo, o seguinte par de valores-chave é definido:

• MAX_PROPERTIES_TO_STORE
  Uma variável de ambiente usada para definir o número máximo de propriedades a serem armazenadas para a função de exemplo.

Testes

Ao criar a função para definir dados de eventos como propriedades de perfil, a guia Saída de teste é usada para verificar a saída esperada.

Registros

Depois que a função tiver sido criada e testada, a guia Logs mostrará o status de integridade da função à medida que ela for executada em resposta aos eventos de disparo reservados . 

Resultado

Com essa função de código implementada, à medida que os clientes se inscrevem para filmagens e acionam o evento personalizado Booked shoot, os dados do evento serão armazenados no perfil do cliente para uso em segmentação e campanhas direcionadas. 

Implementação de receitas  

As receitas no código permitem que o senhor implemente soluções pré-construídas sem a necessidade de desenvolvimento personalizado.

Para implementar uma Receita em sua conta da Klaviyo:

1. Selecione o botão Criar função na página Código.
2. Escolha o Recipe que o senhor gostaria de implementar em sua conta. O senhor será levado ao editor, onde poderá ver o código do Recipe selecionado, juntamente com uma descrição do que a função faz.
3. Clique no botão Select para continuar.
   
4. Escolha um nome para a função e o acionador que fará com que ela seja executada. O tempo de execução é definido automaticamente com base no código da receita.
5. Selecione o botão de função Criar.
6. Depois que a função tiver sido criada, defina as variáveis de ambiente relevantes para que a função tenha os dados necessários para ser executada.
7. Agora, a receita pode ser testada e definida como Live.

Recursos adicionais 

Guia de introdução ao Advanced Klaviyo Data Platform
Entenda os diferentes webhooks disponíveis na Klaviyo