Functions d'événement de plateforme

Une function d'événement de plateforme s'exécute après les faits. Un événement se produit dans OmniLab — un touchpoint 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 modifier ce qui vient de se passer, ce qui en fait le type le plus sûr pour démarrer.

Quand l'utiliser

Choisissez une function d'événement lorsque vous voulez réagir à une activité : enrichir un contact après une participation, transmettre un enregistrement à votre CRM, notifier un canal interne lorsqu'un lot est réclamé. Si vous devez au contraire influencer une opération pendant son déroulement — refuser une inscription, réécrire un e-mail soumis — il vous faut une function de type hook.

Le gestionnaire

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

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

export const onPlatformEvent: PlatformEventHandler = (event) => {
  console.log("Hello world ! Événement reçu : " + event.type + " (" + event.id + ")");
};

Compilez ceci, abonnez la function à un type d'événement, et chaque événement correspondant apparaîtra dans le journal d'exécution avec votre ligne dans le panneau Logs. C'est la boucle complète, et il vaut la peine de la valider avant d'écrire quelque chose de plus élaboré.

L'événement que vous recevez comporte toujours les cinq mêmes champs :

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

Faire quelque chose d'utile

La valeur de retour étant ignorée, une function d'événement n'a d'effet qu'en passant par le SDK. Celle-ci marque le contact avec le dernier touchpoint qu'il a terminé :

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("Aucun contact sur " + event.id + ", rien à faire");
    return;
  }

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

event.data est le payload brut de l'événement : convertissez-le vers la forme attendue et lisez-le prudemment, car les champs diffèrent d'un type à l'autre. La référence des charges utiles indique ce que porte chaque famille, et Load example dans l'onglet Test vous donne un échantillon complet et à jour de n'importe quel type.

L'abonner à des événements

Une function compilée n'est déclenchée par rien tant que vous ne l'avez pas abonnée. Ouvrez-la, utilisez l'onglet Subscriptions, puis sélectionnez Add subscription.

Les événements sont regroupés par famille dans le sélecteur — Touchpoint, Reward, Contact et Other — avec une recherche intégrée. Si la plateforme émet un type d'événement absent du sélecteur, saisissez-le dans le champ d'événement personnalisé et sélectionnez Add custom. Voir la liste des types d'événements pour l'ensemble des possibilités.

Les filtres restreignent la livraison à un Tenant, un Group, une Interaction ou un Contact précis. Sans filtre, tout événement des types sélectionnés déclenche la function.

Sélectionnez Create. L'abonnement apparaît dans la liste avec son statut, ses puces de types d'événements et ses filtres.

Une function peut porter plusieurs abonnements, mais un tenant ne peut avoir plus de 5 abonnements actifs par type d'événement. L'onglet vous avertit lorsqu'un type atteint son plafond.

Ce qui déclenche une function, et ce qui ne la déclenche pas

Deux règles de plateforme s'ajoutent à ce que vous avez choisi.

Seuls les événements porteurs d'un contact identifié déclenchent une function. Un événement sans contact est abandonné : un abonnement apparemment correct peut donc sembler inactif si l'activité derrière lui était anonyme.

Les événements de visite de page anonymes ne sont jamais disponibles. touchpoint.page_visit.v1 représente un volume bien supérieur à celui de tous les autres types : les functions ne sont donc pas autorisées à s'exécuter dessus. Le saisir dans le champ d'événement personnalisé est refusé.

É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ù vous êtes invoqué.

Si quelque chose bloque

L'onglet Subscriptions est absent. Il n'apparaît que sur les functions d'événement. Vérifiez le badge de type en haut de l'éditeur.

Un abonnement existe mais la function ne s'exécute jamais. Confirmez que le statut est Ready — une function en Draft est entièrement ignorée — et que l'abonnement est Active. Vérifiez ensuite que vos filtres n'excluent pas tout, et que l'activité attendue implique bien un contact identifié.

Le type d'événement personnalisé est refusé. Soit la plateforme ne l'émet pas, soit il s'agit de l'événement de visite de page anonyme, auquel les functions ne peuvent jamais s'abonner.

Elle s'est exécutée, mais rien n'a changé. Rappelez-vous que la valeur de retour est ignorée. Consultez les Logs et le résultat des appels SDK dans le détail de l'exécution : une erreur EGRESS_BLOCKED ou NOT_FOUND est la raison habituelle d'un gestionnaire qui s'exécute proprement sans effet.

Pour aller plus loin