Démarrer avec la fonctionnalité de code

Objectif de cet article

Découvrez la fonctionnalité de code et comment créer des fonctions personnalisées qui sont exécutées directement par Klaviyo.

La fonctionnalité de code nécessite un développement personnalisé et l’équipe d’assistance de Klaviyo n’est pas en mesure d’intervenir directement pour vous aider. Si vous n’avez pas de développeur dans votre équipe et si vous ne disposez pas des compétences nécessaires pour écrire du code vous-même, vous pouvez demander l’aide d’un partenaire Klaviyo.

Avant de commencer

La fonctionnalité de code fait partie de la Customer Data Platform (CDP) de Klaviyo. 

Qu’est-ce que la fonctionnalité de code ?

La fonctionnalité de code vous permet d’exécuter des fonctions personnalisées en réponse à des événements collectés dans Klaviyo. Vous pouvez écrire vos propres fonctions JavaScript ou Python dans l’éditeur de code. Il est ensuite exécuté directement sur la plateforme.

Avec la fonctionnalité de code, vous pouvez envoyer des données à vos systèmes externes sans avoir à configurer un point de terminaison HTTP public pour recevoir des webhooks, mais aussi créer des fonctionnalités personnalisées qui sont déclenchées en réponse à des événements précis. Vous pouvez également accéder à de nombreux modules préconçus populaires pour faciliter la création de solutions personnalisées.

Sujets

La fonctionnalité de code vous permet d’exécuter des fonctions personnalisées en réponse à tout événement pouvant être interrogé via l’API Get Events.

En voici quelques exemples :

• Événements liés aux e-mails (par exemple, E-mail cliqué, E-mail marqué comme spam)
• Événements liés aux SMS (par exemple, SMS Envoyé, SMS Reçu)
• Événements liés aux notifications push (par exemple, Push Reçue, Rebond de Push)
• Événements provenant d’intégrations (c’est-à-dire les événements provenant d’intégrations first-party créées par Klaviyo)
• Événements d’API (c’est-à-dire, les événements synchronisés via les API de Klaviyo)

Interface de la fonctionnalité de code

Pour accéder à Code, affichez l’onglet Code sous CDP > Gestion des données > Code. 

Pour créer une fonction personnalisée, sélectionnez le bouton Créer une fonction :

Vous accédez à la page Recettes, qui vous permet de sélectionner une solution préconçue à exécuter, ou une fonction Python ou Node.js vierge.

Si vous sélectionnez une recette existante, l’éditeur de code apparaît avec le code de la solution, ainsi qu’une description de la fonctionnalité. 

Si vous sélectionnez une fonction vierge pour créer vos propres solutions personnalisées, la fenêtre modale Détails s’affiche afin de vous permettre de réaliser les opérations suivantes :

• Nommer votre fonction
  Nom permettant d’identifier votre fonction.
• Sélectionner le sujet de votre fonction
  Événement qui déclenche l’exécution de votre code.
• Sélectionner un environnement d’exécution
  Environnement d’exécution dans lequel le code s’exécute (par exemple, Python ou Node.js).

Après avoir procédé aux sélections requises et sélectionné le bouton Créer une fonction, vous accédez à une interface comportant les onglets suivants : 

• Éditeur 
• Test de sortie 
• Journaux

Octroi des autorisations

La première fois que vous créez une fonction via la fonctionnalité de code, vous êtes invité à authentifier l’application OAuth. Cette étape est nécessaire pour que les fonctions de la fonctionnalité de code puissent accéder aux données de votre compte Klaviyo.

Une fois l’accès accordé, l’éditeur de code s’ouvre.

Éditeur

Dans la fonctionnalité de code, la page Éditeur est fractionnée en 3 onglets :

• Code
  L’onglet Code comporte un éditeur qui vous permet d’écrire des fonctions Python ou JavaScript.
• Modules
  Les modules sont des packages tiers qui étendent les fonctionnalités de vos fonctions.
• Variables d’environnement
  Les variables d’environnement sont les paires clé-valeur auxquelles votre fonction accède lorsqu’elle s’exécute. 

Code

Depuis l’onglet Code, un éditeur vous permet d’écrire des fonctions Python ou JavaScript qui s’exécutent en réponse au sujet sélectionné.

Paramètres de la fonction de traitement

Pour que Klaviyo exécute le code que vous écrivez, celui-ci doit être encapsulé dans une fonction appelée « handler » qui accepte 2 paramètres :

• Event
  Il s’agit des données associées à l’événement déclencheur au format JSON:API. Si le déclencheur n’est pas basé sur un événement (par exemple, Ajouté à la Liste), la valeur de ce paramètre sera None ou Null en fonction du langage.
• Context
  Contient des métadonnées supplémentaires à propos de l’exécution de la fonction, y compris le profil associé à l’invocation de la fonction. Vous pouvez accéder à l’objet de profil en utilisant context.profile en JavaScript ou context["profile"] en Python.

Vous trouverez ci-dessous des exemples de paramètres d’événement et de contexte transmis à la fonction de traitement.

Exemple de format d’événement

{
    {
  "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/"
    }
  }
}

Exemple de format de contexte 

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

Modules

L’onglet Modules propose les modules préconçus les plus populaires (c’est-à-dire des packages tiers qui étendent les capacités de vos fonctions). 

Pour ajouter un module externe à utiliser dans votre code, sélectionnez le bouton Ajouter un module :

Dans la fenêtre modale qui s’affiche, vous pouvez rechercher et sélectionner le module que vous souhaitez ajouter : 

Une fois le module ajouté, vous pouvez l’utiliser avec le code que vous écrivez dans Klaviyo.

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

import klaviyo

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

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

Variables d’environnement 

L’onglet Variables d’environnement vous permet de définir des paires clé-valeur auxquelles votre code peut se référer dans Klaviyo lorsqu’il s’exécute. Elles peuvent stocker des identifiants et des clés secrètes afin que vos fonctions puissent y accéder pendant leur exécution. 

Pour ajouter une variable d’environnement, sélectionnez le bouton Ajouter une variable : 

Dans la fenêtre modale qui s’affiche, vous pouvez attribuer une paire clé-valeur à votre variable d’environnement. 

Une fois créées, les variables d’environnement sont répertoriées sur la page et peuvent être utilisées dans votre code. 

Test de sortie

L’onglet Test de sortie dans la fonctionnalité de code vous permet de tester votre code avec des événements récents pour vérifier qu’il parvient au résultat souhaité. 

Pour tester votre fonction :

1. Sélectionnez le bouton Exécuter le test :
   
2. Dans la fenêtre modale qui s’affiche, sélectionnez un événement à tester. Vous pouvez choisir parmi les 10 événements les plus récents capturés dans Klaviyo.
   
3. Après avoir sélectionné un événement à tester, le résultat du test s’affiche :

Journaux

L’onglet Journaux montre l’état de vos fonctions de code en cours. Voici ce que vous verrez :

• Statut
  État d’avancement de l’exécution d’une fonction. 
• Temps de réponse
  Temps nécessaire à votre code pour s’exécuter en réponse à un événement.
• Date
  Horodatage de l’exécution de la fonction. 

Limites

Le code Klaviyo dispose des limites suivantes :

• Délai d’expiration des fonctions
  Les fonctions du code peuvent s’exécuter pendant 15 secondes au maximum avant d’expirer.
• Limite d’exécution des fonctions
  Les fonctions du code permettent jusqu’à 25 exécutions simultanées par fonction.

Déploiement du code 

Pour déployer le code que vous écrivez dans l’éditeur, définissez le statut sur Actif dans le menu déroulant. 

Une fois activé, le code que vous écrivez s’exécute chaque fois que l’événement du sujet est capturé dans Klaviyo.

Exemple de solution

Vous trouverez ci-dessous un exemple de solution personnalisée mise en œuvre avec la fonctionnalité de code.

Dans l’exemple, les données relatives aux événements sont définies comme une propriété de profil afin d’être utilisées dans des e-mails ciblés et dans la segmentation. L’événement personnalisé Booked shoot est capturé dans Klaviyo lorsque les clients réservent une séance photo avec la marque. Les données concernant la ville de réservation et l’URL associée sont définies comme une propriété de profil sur le profil respectif.

Une propriété appelée Recent bookings est également créée pour stocker les données des 5 derniers événements Booked shoot, afin de pouvoir les consulter en boucle et y accéder dans un modèle d’e-mail.

Code

Le code Python de cette solution est écrit dans l’éditeur de code et exécuté directement par Klaviyo.

Exemple de code

Modules

Dans cet exemple, le module klaviyo intégré est utilisé. Le module klaviyo repose sur l’ajout du module klaviyo-api à la fonction. Une fois ajouté, le module klaviyo se charge de l’authentification pour vous. Aucune clé d’API n’est alors nécessaire.

Variables d’environnement

Les variables d’environnement peuvent stocker des identifiants et des clés secrètes afin que vos fonctions puissent y accéder pendant leur exécution. Pour cet exemple, la paire clé-valeur suivante est définie :

• MAX_PROPERTIES_TO_STORE
  Variable d’environnement qui définit le nombre maximal de propriétés à stocker pour la fonction d’exemple.

Tests

Lors de la création de la fonction permettant de définir les données d’événement comme propriétés de profil, l’onglet Test de sortie est utilisé pour vérifier le résultat attendu.

Journaux

Une fois la fonction créée et testée, l’onglet Journaux présente l’état de la fonction lorsqu’elle est exécutée en réponse aux événements Booked shoot. 

Conclusion

Avec cette fonction de code, lorsque les clients s’inscrivent à des séances photo et déclenchent l’événement Booked shoot personnalisé, les données d’événement sont stockées sur le profil du client pour être utilisées dans la segmentation et les campagnes ciblées. 

Mise en œuvre des recettes  

Dans la fonctionnalité de code, les recettes permettent de mettre en œuvre des solutions préconçues sans recourir à un développement personnalisé.

Pour mettre en œuvre une recette dans votre compte Klaviyo :

1. Sélectionnez le bouton Créer une fonction sur la page Code.
2. Choisissez la recette à mettre en œuvre dans votre compte. Vous accéderez à l’éditeur où vous pourrez voir le code de la recette sélectionnée, ainsi qu’une description de la fonction.
3. Cliquez sur le bouton Sélectionner pour continuer.
   
4. Choisissez un nom pour la fonction et le déclencheur qui provoquera son exécution. La durée d’exécution est automatiquement définie en fonction du code de la recette.
5. Sélectionnez le bouton Créer une fonction.
6. Une fois la fonction créée, définissez les variables d’environnement appropriées afin que la fonction dispose des données dont elle a besoin pour s’exécuter.
7. La recette peut maintenant être testée et activée.

Ressources complémentaires 

Démarrer avec la CDP de Klaviyo
Comprendre les différents webhooks disponibles dans Klaviyo