Primeros pasos con Código

Qué aprenderás

Descubre Code y cómo crear funciones personalizadas que Klaviyo ejecuta directamente.

El código requiere desarrollo personalizado y el equipo de asistencia de Klaviyo no puede ofrecer ayuda práctica. Si no tienes un desarrollador en tu equipo y no te sientes cómodo escribiendo código tú mismo, considera ponerte en contacto con un socio de Klaviyo para obtener ayuda.

Antes de empezar

¿Qué es el código?

El código te permite ejecutar funciones personalizadas en respuesta a los eventos capturados en Klaviyo. Puedes escribir tus propias funciones de JavaScript o Python en el editor de código y, luego, se ejecutarán directamente en la plataforma.

Con la función Código puedes enviar datos a tus sistemas externos sin tener que configurar un punto de conexión HTTP público para recibir webhooks, y crear una funcionalidad personalizada que se active en respuesta a la aparición de un evento. También puedes acceder a muchos módulos prediseñados populares para facilitar la creación de soluciones personalizadas.

Temas

Código te permite ejecutar funciones personalizadas en respuesta a cualquier evento que se pueda consultar mediante la API Get Events.

Estos eventos incluyen:

• Eventos de email (p. ej., email en el que se ha hecho clic, email marcado como spam )
• Eventos de SMS (p. ej., SMS enviado, SMS recibido)
• Eventos de notificación push (por ejemplo, Notificación push recibida, Notificación push rebotada)
• Eventos de integraciones (es decir, eventos de integraciones de origen creadas por Klaviyo)
• Eventos de API (es decir, eventos sincronizados a través de las API de Klaviyo)

Interfaz de código

Para acceder a Code, ve a la pestaña Code en Advanced Klaviyo Data Platform > Data Management > Code.

Para crear una función personalizada, selecciona el botón Crear una función :

Se te llevará a la página Recetas , donde podrás seleccionar una solución preconfigurada para ejecutar o una función Python o Node.js en blanco.

Si seleccionas una receta existente, verás el editor de código con el código de la solución, junto con una descripción de la funcionalidad.

Si seleccionas una función en blanco para poder crear tus propias soluciones personalizadas, aparecerá el modal Detalles, donde puedes:

• Ponle nombre a tu función
  Un nombre para identificar tu función.
• Selecciona un tema para tu función
  El evento que activará la ejecución de tu código.
• Selecciona un entorno de ejecución
  El entorno de ejecución en el que se ejecuta el código (es decir, Python o Node.js).

Después de realizar las selecciones necesarias y seleccionar el botón Crear función , se te llevará a una interfaz con las siguientes pestañas:

• Editor
• Resultados de la prueba
• Registros

Concesión de permisos

La primera vez que crees una función a través de Code, se te pedirá que autentiques la aplicación Code OAuth. Esto es obligatorio para que tus funciones de Code puedan acceder a los datos de tu cuenta de Klaviyo.

Una vez que hayas concedido el acceso, se te dirigirá al editor de código.

Editor

En la página Editor en Código, verás la página en una división en 3 pestañas:

• Código
  La pestaña del código tiene un editor en el que puedes escribir funciones en Python o Javascript.
• Módulos
  Los módulos son paquetes de terceros que añaden funcionalidad a tus funciones.
• Variables de entorno
  Las variables de entorno son los pares clave‑valor a los que accede tu función cuando se ejecuta.

Código

En la pestaña Código , verás un editor que puedes usar para escribir funciones de Python o JavaScript que se ejecutan en respuesta al tema seleccionado.

Parámetros de la función del controlador

Para que Klaviyo ejecute el código que escribas, debe envolverse en una función llamada «handler» que acepta 2 parámetros:

• Evento
  Consiste en los datos del evento asociados al evento activador en formato JSON:API. Si el activador no se basa en un evento (por ejemplo, Añadido a la lista), el valor de este parámetro será None o Null, según el lenguaje.
• Contexto
  Contiene metadatos adicionales sobre la ejecución de la función, incluido el perfil asociado a la invocación de la función. Puedes acceder al objeto de perfil a través de context.profile en Javascript o context["profile"] en Python.

A continuación se muestran ejemplos de los parámetros de evento y de contexto que se pasan a la función del controlador.

Ejemplo 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 ejemplo

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

Módulos

En la pestaña Módulos, puedes seleccionar entre los módulos prediseñados más populares (es decir, paquetes de terceros que añaden funcionalidades a tus funciones).

Para añadir un módulo externo para usarlo en tu código, selecciona el botón Añadir módulo:

En la ventana modal que aparece, puedes buscar y seleccionar el módulo que quieras añadir:

Una vez añadido, puedes utilizar el módulo con el código que escribas en 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())}

Variables de entorno

La pestaña Variables de entorno te permite configurar pares clave‑valor a los que tu código en Klaviyo puede hacer referencia cuando se ejecute. Puedes usarlas para almacenar información como credenciales y claves secretas, de forma que tus funciones puedan acceder a ellas mientras se ejecutan.

Para añadir una variable de entorno, selecciona el botón Añadir una variable:

En la ventana modal que aparece, puedes configurar un par clave-valor para tu variable de entorno.

Una vez creadas, las variables de entorno se mostrarán en la página y se podrán usar en tu código.

Resultados de la prueba

La pestaña Salida de prueba en Código te permite probar tu código con eventos recientes para confirmar que el resultado se comporte según lo previsto.

Para probar tu función:

1. Selecciona el botón Ejecutar prueba:
   

2. En el modal que aparece, selecciona un evento con el que hacer una prueba. Puedes seleccionar entre los 10 eventos más recientes capturados en Klaviyo.
   

3. Después de seleccionar un evento con el que hacer la prueba, se mostrará la salida de prueba:

Registros

La pestaña Registros muestra el estado de tus funciones de código en curso. Verás lo siguiente:

• Estado
  El progreso de la ejecución de una función.
• Tiempo de respuesta
  La cantidad de tiempo que tarda tu código en ejecutarse en respuesta a un evento.
• Fecha
  Una marca de tiempo de cuándo se ejecutó la función.

Límites de la tasa

El código de Klaviyo tiene los siguientes límites de frecuencia:

• Tiempo de espera de la función
  Las funciones en Code pueden ejecutarse durante un máximo de 15 segundos antes de que se agote el tiempo de espera.
• Límite de tasa de funciones
  Las funciones en Code permiten hasta 25 ejecuciones simultáneas por función.

Implementación de código

Para implementar el código que escribes en el editor, cambia el desplegable de estado a Live.

Una vez que se haya establecido como activo, el código que escribas se ejecutará cada vez que el evento del tema se capture en Klaviyo.

Solución de ejemplo

A continuación, se muestra un ejemplo de una solución personalizada que se está implementando con Code.

En el ejemplo, los datos del evento se configuran como propiedades de perfil para que puedan usarse en emails dirigidos y en la segmentación. El evento personalizado Booked shoot se captura en Klaviyo cuando los clientes reservan una sesión con la marca, y los datos sobre la ciudad de la reserva y la URL asociada se establecen como propiedades de perfil en el perfil correspondiente.

También se crea una propiedad llamada Recent bookings , que almacena datos de los 5 eventos Booked shoot más recientes para que se puedan recorrer en bucle y consultar en una plantilla de email.

Código

El código Python de esta solución se escribe en el editor de código y se ejecuta directamente en Klaviyo.

Código de ejemplo

Módulos

En este ejemplo, se utiliza el módulo klaviyo integrado. El módulo klaviyo depende de que se añada el módulo klaviyo-api a la función. Una vez añadido, el módulo klaviyo se encargará de la autenticación, así que no se necesita ninguna clave de API.

Variables de entorno

Las variables de entorno se pueden usar para almacenar información como credenciales y claves secretas para que tus funciones puedan acceder a ella mientras se ejecutan. Para este ejemplo, se ha configurado el siguiente par clave-valor:

• MAX_PROPERTIES_TO_STORE
  Una variable de entorno que se utiliza para definir el número máximo de propiedades que se van a almacenar para la función de ejemplo.

Pruebas

Mientras creas la función para establecer los datos de eventos como propiedades de perfil, se utiliza la pestaña Probar salida para verificar la salida esperada.

Registros

Una vez que se ha creado y probado la función, la pestaña Registros muestra el estado de salud de la función mientras se ejecuta en respuesta a los eventos Booked shoot .

Resultado

Con esta función de Code implementada, a medida que los clientes se registren para sesiones fotográficas y activen el evento personalizado Booked shoot, los datos del evento se almacenarán en el perfil del cliente para usarlos en la segmentación y en campañas dirigidas.

Implementar Recipes 

Las recetas en Code te permiten implementar soluciones predefinidas sin necesidad de desarrollo personalizado.

Para implementar una receta en tu cuenta de Klaviyo:

1. Selecciona el botón Crear función en la página Código.
2. Elige la receta que quieras implementar en tu cuenta. Se te llevará al editor, donde podrás ver el código de la receta seleccionada, junto con una descripción de lo que hace la función.
3. Haz clic en el botón Seleccionar para continuar.
   

4. Elige un nombre para la función y el activador que hará que se ejecute. El tiempo de ejecución se establece automáticamente en función del código de la receta.
5. Selecciona el botón Crear función.
6. Una vez creada la función, configura las variables de entorno pertinentes para que la función tenga los datos que necesita para ejecutarse.
7. Ahora se puede probar la receta y configurarla como En vivo.

Recursos adicionales