Tutoriel - Comment construire une destination serveur avec le sandbox JS

Exemple de destination créée avec le sandbox J0 dans le Destination Builder

Le Destination builder vous permet de créer des destinations server-side personnalisées en utilisant server-side javascript (alias Node.js), mais avec un sous-ensemble simple et simplifié de Node.js : le Javascript Sandbox.

Ce tutoriel vous apprendra les bases pour écrire votre propre modèle de destination server-side et le publier dans votre(s) propre(s) catalogue(s) de destinations.

Une destination server-side reçoit des données d'événements entrants depuis vos sources, les transforme et envoie les données où vous le souhaitez. Tant que l'outil de destination accepte des requêtes HTTP, il peut accepter des données d'une destination server-side.

Exemple basique : Slack

Dans ce tutoriel, vous allez créer une destination qui envoie des données d'événements à Slack en utilisant un seul webhook_url paramètre. Slack est un outil de messagerie et de collaboration qui prend en charge l'intégration via webhook. Le cas d'utilisation peut être : "Je veux recevoir sur un canal Slack un message chaque fois qu'un événement "sign_up" est reçu"

Configuration de la destination

Pour commencer, créez le modèle de destination en naviguant vers la Destination section du menu et en cliquant sur Nouvelle dans le Destination Builder section. Ensuite, donnez à votre destination un nom, un logo, une catégorie et une description.

Ensuite, allez dans la Fields section de l'éditeur pour ajouter des options de paramètres pour votre destination. Vous avez trois options pour construire votre destination :

Configuration totale: Créer un champ de configuration pour chaque paramètre, permettant à l'utilisateur de tout définir explicitement.
Pas de configuration: Ne pas inclure d'options pour configurer la destination. À la place, toutes les données sont prises directement depuis l'événement.
Configuration partielle: Inclure des champs pour certains paramètres mais pas pour d'autres.

Bien qu'avoir un champ pour chaque paramètre soit flexible, cela peut entraîner beaucoup de travail dupliqué pour l'utilisateur. Par conséquent, il est préférable de laisser le code gérer la configuration des données non ambiguës et universelles. Par exemple, si vous construisez une destination d'analytics, vous ne voulez pas demander à l'utilisateur d'entrer l'URL de l'API analytics à chaque fois qu'il configurera cette destination. Vous préférerez hardcoder l'URL dans votre code sans demander à l'utilisateur de la saisir. D'un autre côté, si vous construisez votre destination pour récupérer les données uniquement depuis l'événement, sans ajouter de champ dans les paramètres pour l'utilisateur, l'utilisateur ne pourra pas personnaliser la destination. Par exemple, si la destination nécessite un token, ce token peut varier selon le contexte (prod, dev, pays...), donc si vous hardcodez un token dans le code... Ou peut-être que les hypothèses faites par la destination concernant la structure des données d'événement entrantes ne correspondent pas à la réalité pour des événements/propriétés personnalisés. Dans les deux scénarios, l'utilisateur est incapable d'aller de l'avant.

En conclusion, certaines données doivent toujours être extraites de l'événement tandis que d'autres doivent être configurées par l'utilisateur. C'est à vous de décider afin que le résultat final soit convivial.

Dans le cas de notre destination Slack, nous voudrons ajouter un champ afin que l'utilisateur puisse copier/coller son webhook url Slack. Nous choisissons un champ de saisie texte comme ceci :

Maintenant, nous pouvons aller à l'onglet » : Description de la variable tab, et commencer à écrire le code de notre modèle de destination.\

Comment obtenir les données dans votre code ?

Vous pouvez vouloir obtenir 2 types de données :

données saisies par l'utilisateur (champs remplis dans l'onglet settings)
données d'événement (certaines propriétés de votre événement que vous souhaitez envoyer au partenaire)

1. Données saisies par l'utilisateur

Toutes les données remplies dans les différents champs par l'utilisateur sont accessibles dans l' des données objet dans votre code. Dans votre exemple, nous n'avons qu'un seul champ nommé "url", et la valeur que l'utilisateur final saisira sera accessible via data.url

2. Données d'événement

Vous souhaiterez récupérer certaines propriétés de vos événements pour les envoyer au serveur du partenaire. Vous pouvez utiliser l'une de ces 2 fonctions pour obtenir vos données d'événement :

getAllEventData() => renverra un objet avec toutes les propriétés de l'événement
getEventData(myProperty) =>renverra la valeur d'une propriété spécifique dans votre événement

Implémentation de la destination

Après avoir configuré la destination, vous pouvez procéder à l'implémentation de son comportement dans le JavaScript Sandbox.

L'exemple Slack requiert les quatre étapes suivantes :

Obtenir l'URL du webhook depuis les paramètres de la destination.
Créer le message qui sera envoyé à l'API Slack.
Envoyer une requête au serveur de collecte Slack pour transmettre les données.
Tester votre code, pour s'assurer que la destination se comportera correctement en production.

Il est important de noter que le code ne doit pas effectuer certaines actions, car elles relèvent de la responsabilité de l'onglet filter. Plus précisément, le code doit ne:

Gérer le consentement pour déterminer si l'événement doit être envoyé ou non. C'est la responsabilité du menu déroulant de catégorie de consentement dans le Filter onglet. Il est important de ne pas outrepasser cette fonctionnalité, afin de ne pas casser les rapports Data Governance
Analyser les propriétés de l'événement pour déterminer si cela doit être exécuté. N'oubliez pas que l'utilisateur pourra choisir dans l' Filter tab quels événements seront envoyés à la destination. Vous pouvez vouloir restreindre votre code à certains types d'événements, mais vous ne devez pas supprimer la capacité de l'utilisateur à filtrer ses événements sur certaines propriétés (ex : l'utilisateur peut vouloir n'envoyer que les événements avec la propriété "country" égale à "UK")
Retourner une erreur globale (data.onFailure()) lorsqu'un type d'événement ne convient pas à la destination. Préférez utiliser une erreur silencieuse avec data.onFailure({ status: 'filtered'})

Si vous créez un modèle de destination qui effectue l'une de ces actions, cela peut provoquer de la confusion pour les utilisateurs de votre destination. Par exemple, une destination qui envoie des erreurs à Event Delivery chaque fois que des événements non pris en charge sont détectés peut entraîner des avertissements inutiles dans les rapports Health. Cela violerait les attentes des utilisateurs concernant le comportement attendu de la destination.

Dans cet esprit, voici un exemple annoté de l'implémentation du tag dans le JavaScript sandbox :

const sendHttpRequest = require('sendHttpRequest');
const getAllEventData = require('getAllEventData');

//Nous récupérons les données de l'événement (toutes les propriétés de l'événement)
const eventModel = getAllEventData();

if (eventModel.event_name == 'sign_up') {
    //récupérer l'url depuis ce que l'utilisateur a écrit dans le champ webhook url
    //Les données de Settings arrivent dans le code sandboxé sous la forme d'une 
    //variable prédéfinie appelée 'data'.
    const url = data.url; 
    //Construire le corps du message, en concaténant le prénom et le nom de l'utilisateur dans la phrase à envoyer
    const postBody = '{"text": "' + eventModel.user.firstname + ' ' + eventModel.user.lastname + 'just signed up!"}';

    // Envoyer les données au serveur Slack
    //La fonction sendHttpRequest prend une URL, un callback de résultat, optionnellement un header, une méthode et un body.
    sendHttpRequest(url, (statusCode, headers, body) => {
        if (statusCode >= 200 && statusCode < 300) {
            //envoyer une information de succès au rapport Event Delivery
            data.onSuccess();
        } else {
           //envoyer une erreur au rapport Event Delivery
            data.onFailure();
        }
    }, { headers: { 'Content-Type': 'application/json' }, method: 'POST', timeout: 1000 }, postBody);
}
else {
    //échec silencieux qui n'enverra pas d'erreur dans le rapport Event Delivery
    data.onFailure({ status: 'filtered', detail: 'unsupported_event' });
}

Notez que le data.onSuccess() est obligatoire dans votre code. Les data.onSuccess()et data.onFailure() valeurs indiquent à la plateforme quand la destination a terminé ou échoué sa tâche, et sont ensuite utilisées comme signal pour Event Delivery dashboard et Destination Live Invent Inspector

PrécédentConstructeur de destination Javascript SuivantHelpers javascript côté serveur

Mis à jour il y a 2 ans

Ce contenu vous a-t-il été utile ?