Guia de introdução ao Code

O que você vai aprender

Saiba mais sobre o Code e como criar funções personalizadas executadas diretamente pela Klaviyo.

O código exige desenvolvimento personalizado e a equipe de suporte da Klaviyo não consegue oferecer assistência prática. Se você não tem um desenvolvedor na sua equipe e não se sente à vontade para escrever código por conta própria, considere entrar em contato com um parceiro da Klaviyo para obter ajuda.

Antes de começar

O que é código?

O código permite executar funções personalizadas em resposta a eventos capturados na Klaviyo. Você pode escrever suas próprias funções em Javascript ou Python no editor de código, e elas serã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é-definidos para facilitar a criação de soluções personalizadas.

Tópicos

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

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 próprias criadas pela Klaviyo)
• Eventos de API (eventos sincronizados por meio da API da Klaviyo)

Interface de código

Para acessar o código, vá até a aba Code em Advanced Klaviyo Data Platform > Data Management > Code.

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

Você será direcionado à página Receitas , onde pode selecionar uma solução predefinida para executar ou uma função em Python ou Node.js em branco.

Se você selecionar uma receita existente, verá o editor de código com o código da solução, além de uma descrição da funcionalidade.

Se você selecionar uma função em branco para criar suas próprias soluções personalizadas, o modal Detalhes será exibido, onde você pode:

• Dê um nome à sua função
  Um nome para identificar sua função.
• Selecione um tópico para sua função
  O evento que vai disparar a execução do seu código.
• Selecione um runtime
  O ambiente de runtime em que o código é executado (ou seja, Python ou Node.js).

Depois de fazer as seleções necessárias e selecionar o botão Criar função , você será levado a uma interface com as seguintes abas:

• Editor
• Resultado do teste
• Registros

Conceder permissões

Na primeira vez que você criar uma função pelo Code, será solicitado que você autentique o aplicativo Code OAuth. Isso é necessário para que suas funções do Code consigam acessar dados na sua conta da Klaviyo.

Depois que você conceder acesso, você será direcionado(a) ao editor de código.

Editor

Na página Editor em Código, você verá a página dividida em 3 guias:

• Código
  A aba de código tem um editor onde você pode escrever funções em Python ou Javascript.
• Módulos
  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 pares de valores e chaves que sua função utiliza durante a execução.

Código

Na guia Código , você verá um editor que pode usar para escrever funções em Python ou JavaScript, executadas em resposta ao tópico selecionado.

Parâmetros da função de manipulador

Para que o Klaviyo execute o código que você escreve, ele precisa ser envolvido em uma função chamada "handler" que aceite 2 parâmetros:

• Evento
  Consiste nos dados do evento associados ao evento de acionamento no formato JSON:API. Se o gatilho não for baseado em evento (por exemplo, Adicionado à lista), então o valor desse parâmetro será Nenhum ou 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. Você pode acessar o objeto de perfil via context.profile em Javascript ou context["profile"] em Python.

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

Exemplo de formato de evento

{
    {
  "data": {
    "type": "event",
    "id": "7S2q9haejYG",
    "attributes": {
      "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"
    },
    "relationships": {
      "profile": {
        "data": {
          "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": {
        "data": {
          "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/"
    }
  }
}

Formato de contexto de exemplo

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

Módulos

Na aba Módulos, você pode selecionar entre os módulos pré-criados mais populares (ou seja, pacotes de terceiros que adicionam recursos às suas funções).

Para adicionar um módulo externo para usar no seu código, selecione o botão Adicionar módulo:

Na janela modal exibida, você pode pesquisar e selecionar o módulo que quer adicionar:

Depois de adicioná-lo, você pode usar o módulo com o código que você escreve na Klaviyo.

from klaviyo_api import KlaviyoAPIimport osdef handler(event, context):  klaviyo = KlaviyoAPI(api_key=os.getenv("KLAVIYO_API_KEY"))  print(klaviyo.Metrics.get_metrics())

import klaviyodef handler(event, context):  print(klaviyo.Metrics.get_metrics())

import { Metrics } from 'klaviyo';export default async (event, context) => {  console.log(await Metrics.getMetrics())}

Variáveis de ambiente

A aba Variáveis de ambiente permite definir pares de chave-valor que seu código no Klaviyo pode referenciar quando é 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 Adicionar uma variável:

Na janela modal exibida, você 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 no seu código.

Resultado do teste

A aba Test output em Código permite testar seu código com eventos recentes para confirmar se a saída está se comportando como esperado.

Para testar sua função:

1. Selecione o botão Executar teste:
   

2. Na janela modal exibida, selecione um evento para testar. Você pode selecionar entre os 10 eventos mais recentes capturados na Klaviyo.
   

3. Depois de selecionar um evento para testar, o resultado do teste será exibido:

Registros

A guia Logs mostra a integridade das suas funções de Code em andamento. Você verá:

• Status
  O progresso da execução de uma função.
• Tempo de resposta
  O tempo que o seu 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 taxa

O código da 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 atingir 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 implantar o código que você escreve no editor, alterne o menu suspenso de status para Ativo.

Depois de colocar em produção, o código que você escrever será executado toda vez que o evento do tópico for capturado no Klaviyo.

Solução de exemplo

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

No exemplo, os dados do evento são definidos como uma Propriedades do perfil para que possam ser usados em e-mails direcionados e na segmentação. O evento personalizado Ensaio agendado é capturado na Klaviyo quando os clientes agendam um ensaio com a marca, e os dados sobre a cidade do agendamento e a URL associada são definidos como uma Propriedades do perfil no respectivo perfil.

Uma propriedade chamada Reservas recentes também é criada, que armazena dados dos 5 eventos de Sessão agendada mais recentes para que possam ser percorridos em loop e acessados em um modelo de e-mail.

Código

O código Python desta solução é escrito no editor de código e executado diretamente pela Klaviyo.

Código de exemplo

Módulos

Neste exemplo, o módulo klaviyo integrado é usado. O módulo klaviyo depende do módulo klaviyo-api ser adicionado à função. Depois de adicionado, o módulo klaviyo vai cuidar da autenticação para você, então nenhuma chave de API é necessária.

Variáveis de ambiente

Variáveis de ambiente podem ser usadas para armazenar informações como credenciais e chaves secretas para que suas funções possam acessá-las conforme são executadas. Para este exemplo, o seguinte par chave-valor é definido:

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

Testes

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

Registros

Depois que a função for criada e testada, a guia Logs mostra o status de integridade da função conforme ela é executada em resposta aos eventos de Booked shoot .

Resultado

Com esta função de Code em vigor, conforme os clientes se inscrevem para sessões de fotos e acionam o evento personalizado Sessão de fotos agendada, os dados do evento serão armazenados no perfil do cliente para uso em segmentação e campanhas direcionadas.

Como implementar receitas 

As receitas no Code permitem que você implemente soluções pré-criadas sem a necessidade de desenvolvimento personalizado.

Para implementar uma Recipe na sua conta Klaviyo:

1. Selecione o botão Criar função na página Código.
2. Escolha a Receita que você quer implementar na sua conta. Você será direcionado ao editor, onde poderá ver o código da Receita selecionada, junto com uma descrição do que a função faz.
3. Clique no botão Selecionar para continuar.
   

4. Escolha um nome para a função e o acionador que fará com que ela seja executada. O runtime é definido automaticamente com base no código da Recipe.
5. Selecione o botão Criar função.
6. Depois que a função for criada, defina as variáveis de ambiente relevantes para que a função tenha os dados de que precisa para ser executada.
7. Agora, a Receita pode ser testada e definida como Ativa.

Recursos adicionais