Functions d'événement de plateforme

Écrivez une function qui s'exécute de façon asynchrone après un événement dans OmniLab, et abonnez-la aux types d'événements auxquels elle doit réagir.

Une function d'événement de plateforme s'exécute après coup. Quelque chose se produit dans OmniLab (un point de contact est terminé, une récompense est gagnée, un contact est créé) et votre function est invoquée avec cet événement. Elle ne peut pas changer ce qui s'est déjà passé : c'est donc le type le plus sûr pour commencer.

Quand choisir une function d'événement de plateforme

Choisissez une function d'événement de plateforme pour réagir à une activité : enrichir un contact après sa participation, envoyer une fiche à votre CRM, prévenir un canal interne quand un lot est réclamé. Si vous devez plutôt influencer une opération pendant qu'elle se déroule (refuser une inscription, réécrire un email saisi), il vous faut une function de type hook.

Le gestionnaire

Votre fichier exporte onPlatformEvent. Il reçoit un événement et ne renvoie rien.

user.ts — hello world

import type { PlatformEventHandler } from "./omnilab";

export const onPlatformEvent: PlatformEventHandler = (event) => {
  console.log("Hello world! Received " + event.type + " (" + event.id + ")");
};

Compilez ce code et abonnez la function à un type d'événement : chaque événement correspondant apparaît alors dans le journal d'exécution, avec votre message dans le panneau Journaux. Voilà toute la boucle ; mieux vaut la valider avant d'écrire du code plus élaboré.

L'événement reçu comporte toujours les cinq mêmes champs :

What your handler receives

{
  type: "touchpoint.completed.v1",
  id: "evt-...",              // unique par événement
  time: "2026-05-28T14:48:31Z",
  source: "…",                // l'origine de l'événement
  data: { /* le payload de l'événement */ }
}

Faire quelque chose d'utile

La valeur de retour étant ignorée, une function d'événement de plateforme n'agit qu'en appelant l'extérieur via le SDK. Celle-ci inscrit sur la fiche du contact le dernier point de contact qu'il a terminé :

user.ts — write a contact custom field

import { OmniLab } from "./omnilab";
import type { PlatformEventHandler } from "./omnilab";

type TouchpointCompleted = {
  contact?: { contact_id?: string };
  touchpoint_title?: string;
};

export const onPlatformEvent: PlatformEventHandler = async (event) => {
  const data = event.data as TouchpointCompleted;
  const contactId = data.contact?.contact_id;

  if (!contactId) {
    console.log("No contact on " + event.id + ", nothing to do");
    return;
  }

  await OmniLab.Contact.setCustomField(
    contactId,
    "last_touchpoint",
    data.touchpoint_title ?? "unknown",
  );
};

event.data est le payload brut de l'événement : castez-le vers le type attendu et lisez-le prudemment, car les champs varient d'un type d'événement à l'autre. La référence des événements détaille le contenu de chaque type. Pour obtenir un exemple complet de n'importe quel type proposé par le sélecteur, ouvrez l'onglet Tester et sélectionnez Charger un exemple.

Le même événement peut atteindre votre gestionnaire deux fois : dédoublonnez sur event.id avant tout effet externe.

Abonner la function à des événements

Une function compilée ne s'exécute qu'une fois abonnée à des types d'événements, et seulement pour les événements qui concernent un contact identifié.

Dans l'éditeur de la function :

Sélectionnez l'onglet Abonnements.
Sélectionnez Ajouter un abonnement.
Dans le champ Nom à afficher, saisissez un nom, ici Loyalty award trigger.
Sous Types d'événements, choisissez Terminé dans le groupe Point de contact.

Laissez le champ Types d'événements vide pour recevoir tous les événements.
Sélectionnez Créer.

L'abonnement est créé au statut Actif et apparaît dans la liste avec ses types d'événements et ses filtres. Le sélecteur regroupe les événements en Point de contact, Récompense, Contact et Autre, et propose une recherche. Ignorez le type Expiré du groupe Récompense : la plateforme ne l'envoie jamais. La référence des événements indique quels types atteignent une function, qu'ils figurent ou non dans le sélecteur.

Une function peut avoir plusieurs abonnements. L'onglet vous prévient quand un type d'événement atteint son plafond d'abonnements.

Ajouter un type d'événement absent du sélecteur

Dans le formulaire d'abonnement :

Saisissez le type dans le champ d'événement personnalisé, sous Types d'événements.
Sélectionnez Ajouter un élément personnalisé.

Les événements de réservation, de billet, d'enregistrement et d'envoi de ticket de caisse atteignent une function de cette façon : copiez leurs noms depuis la référence des événements. Tout autre type est accepté lui aussi, même un type que la plateforme n'envoie jamais : un nom mal orthographié ne déclenche donc jamais rien. Seul touchpoint.page_visit.v1 est refusé, au moment où vous sélectionnez Créer.

Restreindre un abonnement avec des filtres

Les filtres se combinent par un ET logique et doivent correspondre exactement. Sans filtre, chaque événement des types sélectionnés déclenche la function.

Certains événements de réservation et de billet ne sont rattachés à aucune organisation : leur group_context est vide. Ils n'atteignent que les abonnements sans filtre Organisation.

Dans le formulaire d'abonnement :

Sélectionnez Ajouter un filtre.
Choisissez la clé, ici Interaction. Les autres clés sont Tenant, Organisation et Contact.
Saisissez l'identifiant exact à faire correspondre, ici la valeur interaction.interaction_id de la campagne, tirée du payload.
Sélectionnez Créer, ou Enregistrer quand vous modifiez un abonnement.

Le statut d'un abonnement ne peut pas être modifié

Le champ Statut apparaît quand vous modifiez un abonnement, mais une modification enregistrée n'a aucun effet, comme le formulaire l'indique. Pour arrêter un abonnement, supprimez-le, puis recréez-le quand vous en avez de nouveau besoin.

Échecs et réessais

Les échecs de votre function n'affectent pas l'activité qui a produit l'événement : l'opération est déjà terminée au moment où la function est invoquée.

Ce qui s'est passé	Ce que fait OmniLab
Votre gestionnaire lève une exception	L'échec apparaît comme une exécution avec un code de sortie non nul, et n'est pas réessayé : le même code échouerait à nouveau
Un problème passager du côté d'OmniLab	Jusqu'à 5 nouvelles tentatives après la première, avec une attente plus longue à chaque fois
Un problème permanent, par exemple une function supprimée	Les tentatives s'arrêtent, car réessayer ne servirait à rien

En cas de blocage

L'onglet Abonnements est absent : il n'apparaît que sur les functions d'événement de plateforme. Vérifiez le badge de type en haut de l'éditeur.
Un abonnement existe mais la function ne s'exécute jamais : vérifiez que la function est au statut Prêt (une function au statut Brouillon est entièrement ignorée) et que l'abonnement a le statut Actif. Vérifiez ensuite que vos filtres n'excluent pas tout, et que l'événement concerne un contact identifié.
Un type d'événement personnalisé ne se déclenche jamais : la plateforme n'envoie pas ce type. Un nom mal orthographié est accepté sans erreur : vérifiez-le dans la référence des événements.
L'abonnement est refusé quand vous sélectionnez Créer : il inclut touchpoint.page_visit.v1, un type auquel aucune function ne peut s'abonner.
Elle s'est exécutée, mais rien n'a changé : rappelez-vous que la valeur de retour est ignorée. Consultez le panneau Journaux et les résultats des appels SDK dans le détail de l'exécution : une erreur EGRESS_BLOCKED, PERMISSION_DENIED ou NOT_FOUND y explique en général pourquoi un gestionnaire s'exécute sans erreur mais sans effet.