Primeros pasos con el código

Objetivos del artículo

Obtén información sobre Code y cómo crear funciones personalizadas que Klaviyo ejecuta directamente.

El código requiere desarrollo personalizado y el equipo de soporte de Klaviyo no puede brindar asistencia práctica. Si no cuentas con un desarrollador en el equipo y no te sientes con confianza para escribir código, considera ponerte en contacto con un socio de Klaviyo para que te ayude.

Antes de empezar

¿Qué es el código?

Código te permite ejecutar funciones personalizadas en respuesta a eventos capturados en Klaviyo. Puedes escribir tus propias funciones de Javascript o Python en el editor de Código y luego se ejecutan directamente en la plataforma.

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

Temas

El código te permite ejecutar funciones personalizadas en respuesta a cualquier evento que se pueda consultar mediante la interfaz de programación de aplicaciones (API) Get Events.

Entre ellos, se incluyen los siguientes:

• Eventos de correo electrónico (p. ej., Hizo clic en el correo electrónico, Marcó el correo electrónico como spam )
• Eventos de SMS (p. ej., SMS enviados, SMS recibidos)
• Eventos de notificación push (p. ej., Notificación push recibida, Notificación push rebotada)
• Eventos de integraciones (es decir, eventos de integraciones propias creadas por Klaviyo)
• Eventos de interfaz de programación de aplicaciones (API) (es decir, eventos sincronizados a través de las interfaz de programación de aplicaciones (API) de Klaviyo)

Interfaz de código

Para acceder al código, ve a la pestaña Código en Advanced Klaviyo Data Platform > Gestión de datos > Código.

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

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

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 crear tus propias soluciones personalizadas, aparecerá el modal de Detalles, donde puedes:

• Nombra 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 hacer las selecciones requeridas y seleccionar el botón Crear función , se te llevará a una interfaz con las siguientes pestañas:

• Editor
• Resultado de la prueba
• Registros

Concesión de permisos

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

Una vez que hayas otorgado acceso, se te llevará al editor de código.

Editor

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

• Código
  La pestaña de código tiene un editor donde puedes escribir funciones de 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 la 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 controladora

Para que Klaviyo ejecute el código que escribes, debe estar envuelto en una función llamada “handler” que acepte 2 parámetros:

• Evento
  Consiste en los datos del evento asociados con el evento desencadenante en formato JSON:interfaz de programación de aplicaciones (API). Si el activador no se basa en un evento (p. ej., Agregado a la lista), el valor de este parámetro será Ninguno o Nulo, según el idioma.
• Contexto
  Contiene metadatos adicionales sobre la ejecución de la función, incluido el perfil asociado con 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 contexto que se pasan a la función controladora.

Formato de evento de ejemplo

{
    {
  "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 preintegrados más populares (es decir, paquetes de terceros que agregan capacidades a tus funciones).

Para agregar un módulo externo que se use en el código, selecciona el botón Agregar módulo:

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

Una vez agregado, puedes usar 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 puede hacer referencia tu código en Klaviyo cuando se ejecuta. Se pueden usar para almacenar información como credenciales y claves secretas para que tus funciones puedan acceder a ellas mientras se ejecutan.

Para agregar una variable de entorno, selecciona el botón Agregar una variable:

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

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

Resultado de la prueba

La pestaña Probar salida en Código te permite probar el código con eventos recientes para confirmar que la salida se comporta como se espera.

Para probar la función:

1. Selecciona el botón Ejecutar prueba:
   

2. En la ventana modal que aparece, selecciona un evento para hacer la prueba. Puedes seleccionar entre los 10 eventos más recientes registrados en Klaviyo.
   

3. Después de seleccionar un evento para hacer la prueba, se mostrará el resultado de la prueba:

Registros

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

• 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 tasa

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

• Tiempo de espera de la función
  Las funciones en Code pueden ejecutarse hasta por 15 segundos antes de que se agote el tiempo de espera.
• Límite de tasa de función
  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 menú desplegable de estado a En vivo.

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

Solución de ejemplo

A continuación se muestra un ejemplo de una solución personalizada que se implementa con Código.

En el ejemplo, los datos del evento se establecen como propiedades del perfil para que se puedan usar en correos electrónicos segmentados y en la segmentación. El evento personalizado Booked shoot se registra 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 del perfil en el perfil correspondiente.

También se crea una propiedad llamada Reservas recientes , que almacena datos de los 5 eventos de Sesión reservada más recientes para que se pueda iterar y acceder a ellos en una plantilla de correo electrónico.

Código

El código de Python para esta solución está escrito 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 integrado klaviyo. El módulo klaviyo depende de que el módulo klaviyo-api se agregue 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 las funciones puedan acceder a ellas mientras se ejecutan. Para este ejemplo, se establece el siguiente par clave-valor:

• MAX_PROPERTIES_TO_STORE
  Una variable de entorno que se usa para definir la cantidad máxima de propiedades que se almacenarán para la función de ejemplo.

Pruebas

Mientras se crea la función para establecer datos del evento como propiedades del perfil, la pestaña Salida de prueba se usa para verificar la salida esperada.

Registros

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

Resultado

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

Implementación de Recipes 

Las recetas en Code te permiten implementar soluciones prediseñadas 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 la 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 configura automáticamente según el código de la receta.
5. Selecciona el botón Crear función.
6. Una vez que se haya creado la función, configura las variables de entorno relevantes para que la función tenga los datos que necesita para ejecutarse.
7. La receta ahora se puede probar y configurar como Activa.

Recursos adicionales