Tutoriel - Comment créer une destination server-side 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 à l’aide de server-side JavaScript (alias Node.js), mais avec un simple et simplifié sous-ensemble de Node.js : le JavaScript Sandbox.

Ce tutoriel vous apprendra les bases de l’écriture de votre propre modèle de destination server-side et de sa publication dans votre ou vos catalogues de destinations.

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

Exemple de base : Slack

Dans ce tutoriel, vous allez créer une destination qui envoie les données d’événements à Slack à l’aide d’un seul webhook_url Slack est un outil de messagerie et de collaboration qui prend en charge l’intégration de webhooks. Le cas d’usage 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 allant dans la Destination section du menu puis en cliquant sur Nouveau dans Destination Builder section. Ensuite, donnez à votre destination un nom, un logo, une catégorie et une description.

Ensuite, allez dans la Champs section de l’éditeur pour ajouter des options de configuration à votre destination. Vous avez trois options pour créer votre destination :

1. Configuration totale: Créez un champ de configuration pour chaque paramètre, afin de permettre à l’utilisateur de tout définir explicitement.

2. Aucune configuration: N’incluez aucune option de configuration de la destination. À la place, toutes les données sont prises directement depuis l’événement.

3. Configuration partielle: Incluez des champs pour certains paramètres mais pas pour d’autres.

Même s’il est flexible d’avoir un champ pour chaque paramètre, cela peut entraîner beaucoup de travail en double pour l’utilisateur. Il est donc préférable que le code gère la configuration des données non ambiguës et universelles. Par exemple, si vous créez une destination analytics, vous ne voulez pas demander à l’utilisateur de saisir l’URL de l’API analytics à chaque fois qu’il configure cette destination. Vous préférerez coder en dur 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écessitait un token, ce token peut varier selon le contexte (prod, dev, country...), donc si vous codez en dur 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é des événements/propriétés personnalisés. Dans les deux cas, l’utilisateur ne peut pas aller plus loin.

En conclusion, certaines données devraient 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 l’URL du webhook de Slack. Nous choisissons une saisie de texte comme celle-ci :

Maintenant, nous pouvons aller dans l’ Code onglet, en commençant à é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 :

1. données saisies par l’utilisateur (champs remplis dans l’onglet des paramètres)

2. données d’événement (certaines propriétés de votre événement que vous voulez envoyer au partenaire)

1. Données saisies par l’utilisateur

Toutes les données renseignées dans les différents champs par l’utilisateur sont accessibles dans l’ data 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 voudrez 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 de votre événement

Implémentation de la destination

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

L’exemple Slack nécessite les quatre étapes suivantes :

1. Obtenez l’URL du webhook à partir des paramètres de la destination.

2. Créez le message qui sera envoyé à l’API Slack.

3. Envoyez une requête au serveur de collecte Slack pour transmettre les données.

4. Testez votre code pour vous 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 pas:

• 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 l’ Filter onglet. Il est important de ne pas remplacer cette fonctionnalité afin de ne pas casser les rapports Data Governance

• Analysez les propriétés de l’événement pour déterminer s’il doit être exécuté. N’oubliez pas que l’utilisateur pourra choisir dans l’ onglet Filter quel événement sera envoyé à la destination. Vous pouvez vouloir limiter votre code à certains types d’événements, mais vous ne devez pas supprimer la possibilité pour l’utilisateur de filtrer ses événements selon certaines propriétés (ex. : l’utilisateur peut vouloir n’envoyer que les événements dont la propriété "country" est égale à "UK")

• Retournez une erreur globale (data.onFailure()) lorsqu’un certain type d’événement ne correspond 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 semer la confusion chez 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 irait à l’encontre des attentes des utilisateurs concernant le comportement attendu de la destination.

Dans cette optique, 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ère l’URL à partir de ce que l’utilisateur a écrit dans le champ webhook url
    //Les données de configuration entrent dans le code sandboxé sous forme de 
    //variable prédéfinie appelée 'data'.
    const url = data.url; 
    //Construit le message du corps, en concaténant le nom de l’utilisateur à l’intérieur de la phrase à envoyer
    const postBody = '{"text": "' + eventModel.user.firstname + ' ' + eventModel.user.lastname + 'just signed up!"}';

    // Envoie les données au serveur Slack
    //La fonction sendHttpRequest prend une URL, un rappel de résultat, et éventuellement un en-tête, une méthode et un corps.
    sendHttpRequest(url, (statusCode, headers, body) => {
        if (statusCode >= 200 && statusCode < 300) {
            //envoie une information de succès au rapport Event Delivery
            data.onSuccess();
        } else {
           //envoie 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 data.onSuccess() est obligatoire dans votre code. Le data.onSuccess()et data.onFailure() values indiquent à la plateforme quand la destination a terminé ou échoué sa tâche, puis sont utilisées comme signal pour Event Delivery dashboard et Destination Live Invent Inspector