> For the complete documentation index, see [llms.txt](https://doc.commandersact.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.commandersact.com/fr/fonctionnalites/destinations/destination-builder/javascript-destination-builder/tutorial-how-to-build-a-server-destination-with-the-js-sandbox.md).

# 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 **javascript** (alias Node.js), mais avec un sous-ensemble **simple et simplifié** de Node.js : le [***Javascript Sandbox***](https://doc.commandersact.com/fr/fonctionnalites/destinations/destination-builder/javascript-destination-builder.md#javascript-sandbox).

Ce tutoriel vous apprendra les bases de la création de votre propre modèle de destination server-side et de sa publication dans vos propres catalogues de destinations.

{% hint style="success" %}
Une destination server-side reçoit les données d’événements entrantes de vos sources, les transforme et les envoie où vous le souhaitez. Tant que l’outil de destination accepte les requêtes HTTP, il peut recevoir des données d’une destination server-side.
{% endhint %}

## 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 unique paramètre `webhook_url` . Slack est un outil de messagerie et de collaboration qui prend en charge l’intégration par webhook. Cas d’utilisation : « Je veux recevoir un message dans un canal Slack 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 accédant à la section **Destination** du menu et en cliquant sur **Nouveau** dans la section **Destination Builder** . Donnez ensuite un nom à votre destination, ajoutez un logo, une catégorie et une description.

<figure><img src="https://3282103337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-9182a6a108ce87e0bb37ee2e87b6a739e68b640d%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Ensuite, accédez à la section **Champs** de l’éditeur pour ajouter des options de configuration à votre destination. Vous avez trois possibilités pour créer votre destination :

1. **Configuration complète** : créez un champ de configuration pour chaque paramètre afin que l’utilisateur puisse tout définir explicitement.
2. **Aucune configuration** : n’incluez aucune option de configuration pour la destination. Toutes les données sont plutôt directement tirées de l’événement.
3. **Configuration partielle** : incluez des champs pour certains paramètres, mais pas pour les autres.

Bien qu’un champ pour chaque paramètre offre une grande flexibilité, cela peut entraîner beaucoup de travail en double pour l’utilisateur. Il est donc préférable de laisser le code gérer la configuration des données non ambiguës et universelles.\
Par exemple, si vous créez une destination d’analytics, vous ne voulez pas demander à l’utilisateur de saisir l’URL de l’API d’analytics chaque fois qu’il configure cette destination. Il est préférable d’inscrire l’URL en dur dans votre code, sans demander à l’utilisateur de la saisir.\
\
À l’inverse, si votre destination récupère les données uniquement à partir de l’événement, sans ajouter de champs dans les paramètres pour l’utilisateur, celui-ci ne pourra pas personnaliser la destination.\
Par exemple, si la destination nécessite un token, celui-ci peut varier selon le contexte (prod, dev, pays, etc.). Si vous inscrivez un token en dur dans le code...\
Ou encore, les hypothèses de la destination concernant la structure des données d’événement entrantes peuvent ne pas correspondre à la réalité des événements ou propriétés personnalisés. Dans les deux cas, l’utilisateur ne peut pas poursuivre.

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

Dans le cas de notre destination Slack, nous allons ajouter un champ afin que l’utilisateur puisse copier-coller l’URL du webhook Slack. Nous choisissons une entrée de texte comme celle-ci :

<figure><img src="https://3282103337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-dd54607875539f770b8c64071b874eb168236917%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Nous pouvons maintenant accéder à l’onglet *Code* et commencer à écrire le code de notre modèle de destination.

<figure><img src="https://3282103337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-042a7de5d9437739afd3668095e9c3da59797fb8%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

### Comment récupérer les données dans votre code ?

Vous pouvez vouloir récupérer deux types de données :

1. les données saisies par l’utilisateur (champs renseignés dans l’onglet des paramètres)
2. les 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 renseignées par l’utilisateur dans les différents champs sont accessibles dans l’objet `data` de votre code.\
Dans notre exemple, nous avons un seul champ nommé « url », et la valeur saisie par l’utilisateur final 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 deux fonctions pour récupérer les données de votre événement :

* [getAllEventData() ](https://doc.commandersact.com/fr/fonctionnalites/destinations/destination-builder/javascript-destination-builder/serverside-js-helpers.md#getalleventdata-2)=> renverra un objet contenant toutes les propriétés de l’événement
* [getEventData(myProperty)](https://doc.commandersact.com/fr/fonctionnalites/destinations/destination-builder/javascript-destination-builder/serverside-js-helpers.md#geteventdata) => 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 implémenter son comportement dans le JavaScript Sandbox.

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

1. Récupérer l’URL du webhook dans les paramètres de la destination.
2. Créer le message qui sera envoyé à l’API Slack.
3. Envoyer une requête au serveur de collecte de Slack pour transmettre les données.
4. Tester 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 l’onglet Filtre. Plus précisément, le code ne doit **pas**:

* **gérer le consentement** pour déterminer si l’événement doit être envoyé ou non.\
  C’est à la liste déroulante des catégories de consentement de l’onglet *Filtre* de s’en charger. Il est important de ne pas remplacer cette fonctionnalité afin de ne pas perturber les rapports de gouvernance des données.
* Analyser 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 *Filtre* les événements qui seront envoyés à la destination. Vous pouvez vouloir limiter votre code à certains types d’événements, mais vous ne devez pas empêcher l’utilisateur de filtrer ses événements selon certaines propriétés (ex. : l’utilisateur peut vouloir envoyer uniquement les événements dont la propriété « country » est égale à « UK »).
* Renvoyer une erreur globale (`data.onFailure()`) lorsqu’un type d’événement ne correspond pas à la destination. Privilégiez 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 risque de semer la confusion chez les utilisateurs de votre destination. Par exemple, une destination qui envoie des erreurs à Event Delivery lorsque des événements non pris en charge sont détectés peut entraîner des avertissements inutiles dans les rapports Health. Cela ne correspondrait pas aux attentes des utilisateurs quant au comportement prévu de la destination.

Dans cette optique, voici un exemple commenté de l’implémentation du tag dans le JavaScript Sandbox :

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

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

if (eventModel.event_name == 'sign_up') {
    //récupérer l’URL saisie par l’utilisateur dans le champ de l’URL du webhook
    //Les données des paramètres sont transmises au code isolé dans le 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 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, une fonction de 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) {
            //envoyer une confirmation de réussite 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 ne génère pas d’erreur dans le rapport Event Delivery
    data.onFailure({ status: 'filtered', detail: 'unsupported_event' });
}
```

{% hint style="success" %}
Notez que `data.onSuccess()` est obligatoire dans votre code.\
Le `data.onSuccess()`et `data.onFailure()` les valeurs indiquent à la plateforme quand la destination a terminé sa tâche ou a échoué, puis servent de signal pour *la diffusion des événements* le Dashboard et *Inspecteur en direct des destinations*
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.commandersact.com/fr/fonctionnalites/destinations/destination-builder/javascript-destination-builder/tutorial-how-to-build-a-server-destination-with-the-js-sandbox.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
