Helpers JavaScript server-side

Cet article décrit les API de destination server-side.

decodeURI

Décode tous les caractères encodés dans l'URI fourni. Renvoie un string qui représente l'URI décodé. Renvoie undefined lorsqu'on lui fournit une entrée invalide.

Syntaxe

decodeUri(encoded_uri);

Exemple

const decodeUri = require('decodeUri');

const decodedUrl = decodeUri(data.encodedUrl);
if (decodedUrl) {
  // ...
}

Paramètre	Type	Description
encoded_uri	string	Un URI qui a été encodé par encodeUri() ou par d'autres moyens.

decodeUriComponent

Décode tous les caractères encodés dans le composant d'URI fourni. Renvoie un string qui représente le composant d'URI décodé. Renvoie undefined lorsqu'on lui fournit une entrée invalide.

Syntaxe

decodeUriComponent(encoded_uri_component);

Exemple

const decodeUriComponent = require('decodeUriComponent');

const decodedQuery = decodeUriComponent(data.query);
if (decodedQuery) {
  // ...
}

Paramètre	Type	Description
encoded_uri_component	string	Un composant d'URI qui a été encodé par encodeUriComponent() ou par d'autres moyens.

encodeUri

Renvoie un Uniform Resource Identifier (URI) encodé en échappant les caractères spéciaux. Renvoie un string qui représente la chaîne fournie encodée sous forme d'URI.

Syntaxe

encodeUri(uri);

Exemple

const encodeUri = require('encodeUri');
const sendHttpGet = require('sendHttpGet');

sendHttpGet('https://www.example.com/' + encodeUri(pathInput));

Paramètre	Type	Description
uri	string	Un URI complet.

encodeUriComponent

Renvoie un Uniform Resource Identifier (URI) encodé en échappant les caractères spéciaux. Renvoie un string qui représente la chaîne fournie encodée sous forme d'URI.

Syntaxe

encodeUriComponent(str);

Exemple

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');

sendHttpGet('https://www.example.com/?' + encodeUriComponent(queryInput));

Paramètre	Type	Description
str	string	Un composant d'URI.

fromBase64

Décode une chaîne encodée en base64. Renvoie undefined si l'entrée est invalide.

Syntaxe

fromBase64(base64EncodedString);

Exemple

const fromBase64 = require('fromBase64');

const greeting = fromBase64('aGVsbG8=');
if (greeting === 'hello') {
  // ...
}

Paramètre	Type	Description
base64EncodedString	string	Chaîne encodée en base64.

generateRandom

Renvoie un nombre aléatoire number (entier) dans l'intervalle donné.

Syntaxe

generateRandom(min, max);

Exemple

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

Paramètre	Type	Description
min	number	Valeur potentielle minimale de l'entier renvoyé (inclus).
max	number	Valeur potentielle maximale de l'entier renvoyé (inclus).

getAllEventData

Renvoie une copie des données d'événement.

Syntaxe

getAllEventData();

Exemple d'utilisation

const getAllEventData= require('getAllEventData');
const eventModel = getAllEventData();
// construire le corps de la requête à partir des propriétés de l'événement 
const body = {
    crm_id:eventModel.user.id,
    currency:eventModel.currency
};

Notez que les données d'événement peuvent contenir plus de propriétés que ce que vous avez envoyé initialement, en raison des propriétés système ajoutées automatiquement sur les événements web et les événements app sdk.

Exemple de données :

Si vous envoyez cet événement web :

cact('trigger', 'search', {
  "search_term": "blue t-shirt",
  "user": {
    "id": "12345",
    "email": "[e-mail]",
    "consent_categories": ["1","3"]
  }
);

Alors la fonction getAllEventData() renverra cet objet :

{
   "event_name": "search",
   "search_term": "blue t-shirt",
   "user": {
      "id": "12345",
      "email": "[e-mail]",
      "consent_categories": ["1","3"]
   },
   "url": "https://www.mywebsite.com/path1/path2/", //Ajouté automatiquement s'il manque
   "path": "/path1/path2/", //Ajouté automatiquement
   "referrer": "https:///www.google.fr", //Ajouté automatiquement
   "title": "My page title", //Ajouté automatiquement s'il manque
   "context": {
      "event_id": "202110130000000000", //Ajouté automatiquement
      "generatorVersion": "10.0", //Ajouté automatiquement
      "containerVersion": "3.1", //Ajouté automatiquement
      "event_timestamp": "1639044446636", //Ajouté automatiquement
      "page": { //Ajouté automatiquement
         "title": "Search page", //Ajouté automatiquement
         "url": "https://shop.com/search?q=...", //Ajouté automatiquement
         "lang": "en", //Ajouté automatiquement
         "referrer": "https:///www.google.fr", //Ajouté automatiquement
         "viewport": { //Ajouté automatiquement
            "width": 320, //Ajouté automatiquement
            "height": 568 //Ajouté automatiquement
         }
      },
      "device": { //Ajouté automatiquement
         "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.86 Safari/537.36",//Ajouté automatiquement
         "ip": "102.3.4.56",//Copié automatiquement depuis l'en-tête de la requête
         "lang": "fr",//Ajouté automatiquement
         "cookie": "_fbp=123; _fbc=456; _ga=789",//Ajouté automatiquement
         "timezone": "Europe/Paris"//Ajouté automatiquement
      }
   }
}

getCookieValues

Renvoie un tableau contenant les valeurs de tous les cookie portant le nom donné.

Syntaxe

getCookieValues(name[, noDecode]);

Exemple

const getCookieValues = require('getCookieValues');
const facebook_fbp = getCookieValues('fbp')[0];
if (facebook_fbp ) {  // ...}

---

Paramètres

Paramètre	Type	Description
name	string	Nom du cookie.
noDecode	boolean	Si true, les valeurs de cookie ne seront pas décodées avant d'être renvoyées. Par défaut, false.

getEventData

Renvoie une copie de la valeur au chemin donné dans les données d'événement. Renvoie undefined s'il n'y a pas de données d'événement ou s'il n'y a pas de valeur au chemin donné.

Syntaxe

getEventData(keyPath);

Exemple

const getEventData = require('getEventData');

const campaignId = getEventData('campaign.id');
const itemId = getEventData('items.0.id');
const referrer = getEventData('page_referrer');

Paramètres

Paramètre	Type	Description
keyPath	de	Le chemin de la clé, où les composants du chemin sont séparés par des points. Les composants du chemin peuvent être des clés dans un objet ou des indices dans un tableau. Si keyPath ce n'est pas une chaîne, il est converti en chaîne.

getRemoteAddress

Renvoie une string représentation de l'adresse IP d'origine de la requête, par exemple 62.123.65.780 pour IPv4 ou 2001:0db8:85a3:0:0:8a2e:0370:1234 pour IPv6

Syntaxe

getRemoteAddress();

getTimestamp

Obsolète. Préférez getTimestampMillis.

Renvoie une number qui représente l'heure actuelle en millisecondes depuis l'époque Unix, telle que renvoyée par Date.now().

Syntaxe

getTimestamp();

getTimestampMillis

Renvoie une number qui représente l'heure actuelle en millisecondes depuis l'époque Unix, telle que renvoyée par Date.now().

Syntaxe

getTimestampMillis();

getType

Renvoie une chaîne décrivant le type de la valeur donnée.

Type d'entrée	Valeur renvoyée
string	'string'
number	'number'
boolean	'boolean'
null	'null'
undefined	'undefined'
Tableau	'array'
Objet	'object'
Fonction	'function'

Syntaxe

getType(value);

Exemple

const getType = require('getType');

const type = getType(value);
if (type === 'string') {
  // Gérer l'entrée de chaîne.
} else if (type === 'number') {
  // Gérer l'entrée numérique.
} else {
  logToConsole('Unsupported input type: ', type);
}

Paramètres

Paramètre	Type	Description
valeur	de	Valeur d'entrée.

logToConsole

Enregistre ses arguments dans la console.

Ces journaux sont visibles dans la console de Destination Builder.

Exemple

const logToConsole = require('logToConsole');

const product_color= "red";
const product_price= 10;
logToConsole('color is: ', product_color, ' and price is: ', product_price);

Syntaxe

logToConsole(argument1[, argument2, ...]);

Paramètres

La fonction prend un ou plusieurs arguments, chacun étant converti en chaîne si nécessaire, puis consigné dans la console.

makeInteger

Convertit la valeur donnée en number (entier).

Syntaxe

makeInteger(value);

Paramètres

Paramètre	Type	Description
valeur	tout type	La valeur à convertir.

makeNumber

Convertit la valeur donnée en number.

Syntaxe

makeNumber(value);

Paramètres

Paramètre	Type	Description
valeur	tout type	La valeur à convertir.

makeString

Renvoie la valeur donnée sous forme de string.

Syntaxe

makeString(value);

Paramètres

Paramètre	Type	Description
valeur	tout type	La valeur à convertir.

parseUrl

Renvoie un objet qui contient toutes les parties composantes d'une URL donnée, similaire à URL objet.

Cette API renverra undefined undefined pour toute URL malformée. Pour des URL correctement formatées, les champs absents de la chaîne d'URL auront la valeur d'une chaîne vide, ou, dans le cas de searchParams, un objet vide.

L'objet renvoyé aura les champs suivants :

{  
    href: string,  
    origin: string, 
    protocol: string,  
    username: string,  
    password: string,  
    host: string,  
    hostname: string,  
    port: string,  
    pathname: string,  
    search: string,  
    searchParams: Object<string, (string|Array)>,  
    hash: string,
}

Syntaxe

parseUrl(url);

Exemple

const parseUrl = require('parseUrl');const urlObject = parseUrl('https://abc:[e-mail]:8080/foo?param=val%2Cue#bar');

Paramètres

Paramètre	Type	Description
url	string	L'URL complète qui sera analysée.

sha256

Calcule le condensat SHA-256 de l'entrée et appelle un callback avec le condensat encodé en base64, sauf si le options objet options spécifie un encodage de sortie différent.

Cette signature et ce comportement de l'API correspondent à sha256 l'API pour les conteneurs web ; cependant, les Custom Templates dans les conteneurs serveur doivent utiliser la sha256Sync API pour un code plus simple.

Syntaxe

sha256(input, onSuccess, options = undefined);

Exemple

const encodeUriComponent = require('encodeUriComponent');const sendHttpGet = require('sendHttpGet');const sha256 = require('sha256');sha256('inputString', (digest) => {  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));});sha256('inputString', (digest) => {  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));}, {outputEncoding: 'hex'});

Paramètres

Paramètre	Type	Description
input	string	La chaîne à hacher.
onSuccess	fonction	Appelé avec le condensat résultant, encodé en base64, sauf si l' options objet options spécifie un encodage de sortie différent.
options	object	Facultatif objet options permet de spécifier l'encodage de sortie. S'il est spécifié, l'objet doit contenir la clé outputEncoding avec comme valeur l'un de base64 ou hex.

sha256Sync

Calcule et renvoie le condensat SHA-256 de l'entrée, encodé en base64, sauf si le options objet options spécifie un encodage de sortie différent.

Syntaxe

sha256Sync(input, options = undefined);

Exemple

const encodeUriComponent = require('encodeUriComponent');const sendHttpGet = require('sendHttpGet');const sha256Sync = require('sha256Sync');const digestBase64 = sha256Sync('inputString');const digestHex = sha256Sync('inputString', {outputEncoding: 'hex'});sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestBase64));sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestHex));

Paramètres

Paramètre	Type	Description
input	string	La chaîne à hacher.
options	object	Facultatif objet options permet de spécifier l'encodage de sortie. S'il est spécifié, l'objet doit contenir la clé outputEncoding avec comme valeur l'un de base64 ou hex.

signHmac

Génère une signature HMAC pour le payload donné, en utilisant sha256 et base64 l'encodage par défaut, sauf si l' options objet options indique le contraire. Les objets passés en tant que payload sont automatiquement JSON.stringify'd. Renvoie un string.

Syntaxe

signHmac(payload, secret, options = undefined);

Exemple

const signHmac = require('signHmac');

// Signe une chaîne avec les options par défaut (sha256 + base64)
const signature = signHmac('my payload', 'mySecretKey');

// Signe avec un algorithme et un encodage personnalisés
const signatureHex = signHmac('my payload', 'mySecretKey', { alg: 'sha1', outputEncoding: 'hex' });

// Signe un objet (automatiquement JSON.stringify'd)
const objectSignature = signHmac({ key: 'value' }, 'mySecretKey');

Paramètres

Paramètre	Type	Description
payload	string|object	Les données à signer. Les objets sont automatiquement convertis en chaînes JSON.
secret	string	La clé secrète utilisée pour la génération HMAC.
options	object	Facultatif Objet options permettant de personnaliser l'algorithme et l'encodage de sortie. Voir les détails des options ci-dessous.

Options

Propriété	Type	Par défaut	Description
alg	string	'sha256'	L'algorithme de hachage. Valeurs prises en charge : 'sha256', 'sha1', 'sha512', 'sha384', 'md5' et autres algorithmes de condensat OpenSSL.
outputEncoding	string	'base64'	L'encodage de sortie. Valeurs prises en charge : 'base64', 'base64url', 'hex', 'binary' (latin1).

toBase64

Encode une chaîne en base64.

Syntaxe

toBase64(input);

Exemple

const toBase64 = require('toBase64');const base64Hello = toBase64('hello');

Paramètres

Paramètre	Type	Description
input	string	Chaîne à encoder.

JSON

Renvoie un objet qui fournit des fonctions JSON.

Le parse() la fonction analyse une chaîne JSON pour construire la valeur ou l'objet décrits par la chaîne. Si la valeur ne peut pas être analysée (JSON mal formé), la fonction renverra undefined. Si la valeur d'entrée n'est pas une chaîne, l'entrée sera convertie en chaîne.

Le stringify() la fonction convertit l'entrée en chaîne JSON. Si la valeur ne peut pas être sérialisée (ex. l'objet a un cycle), la méthode renverra undefined.

Syntaxe

JSON.parse(yourString);
JSON.stringify(yourObject);

Exemple

const JSON = require('JSON');
// La chaîne d'entrée JSON est convertie en objet.
const object = JSON.parse('{"foo":"bar"}');
// L'objet d'entrée est converti en chaîne JSON.
const str = JSON.stringify({foo: 'bar'});

---

Math

Un objet fournissant Math fonctions.

Syntaxe

const Math = require('Math');
// Récupère la valeur absolue.
const absolute = Math.abs(-5);
// Arrondit l'entrée à l'entier inférieur le plus proche.
const roundedDown = Math.floor(4.6);
// Arrondit l'entrée à l'entier supérieur le plus proche.
const roundedUp = Math.ceil(2.1);
// Arrondit l'entrée à l'entier le plus proche.
const rounded = Math.round(4.2);
// Renvoie le plus grand argument.
const biggest = Math.max(1, 4);
// Renvoie le plus petit argument.
const smallest = Math.min(4, 5);
// Renvoie le premier argument élevé à la puissance du second argument.
const powerful = Math.pow(4, 2);
// Renvoie la racine carrée de l'argument.
const unsquared = Math.sqrt(81);

Paramètres

Les paramètres des fonctions Math sont convertis en nombres.

sendHttpGet

Effectue une requête HTTP GET vers l'URL spécifiée, et invoque un callback avec la réponse une fois la requête terminée ou expirée.

Syntaxe

sendHttpGet(url[, callback[, options]]);

Exemple

const sendHttpGet = require('sendHttpGet');
// Envoie une requête GET et nomme la réponse// en fonction de la réponse du GET 
sendHttpGet('https://example.com/collect', function(statusCode, headers, body) {
    if (statusCode != 200) {yourCallbackFunction();}
}, {
    headers: {key: 'value'},
    timeout: 500
});

Paramètres

Paramètre	Type	Description
url	string	L'URL de la requête.
callback	fonction	Un callback facultatif à invoquer à la fin de la requête, en cas d'erreur ou de timeout. Il est appelé avec le code d'état de la réponse, le les en-têtes de la réponse, et le corps de la réponse (ou undefined s'il n'y avait pas de corps de réponse). Si la requête a échoué (par ex. URL invalide, aucune route vers l'hôte, échec de la négociation SSL, etc.), le callback sera appelé avec un code d'état de réponse égal à zéro, aucun en-tête, et un corps undefined. Si l' 'timeout' option a été définie et que la requête a expiré, le callback sera appelé avec un code d'état de réponse égal à -1, aucun en-tête, et un corps undefined.
options	object	Options de requête facultatives. Les options prises en charge sont headers, timeout. Des options avancées peuvent être ajoutées dans extraOptions

Options

• headers: En-têtes de requête supplémentaires représentés sous forme d'objet.

• timeout: Le timeout, en millisecondes, avant l'abandon de la requête.

• extraOptions: Options avancées (ex : {strictSSL:true})

sendHttpRequest

Effectue une requête HTTP vers l'URL spécifiée et appelle un callback avec la réponse une fois la requête terminée ou expirée.

Syntaxe

sendHttpRequest(url[, callback[, options[, body]]]);

Exemple

const sendHttpRequest = require('sendHttpRequest');
const body = {
    user_type:'vip',
    account:'123'
};
// Envoie une requête POST 
sendHttpRequest('https://example.com/collect', function(statusCode, headers, body) {
    // votre code de callback...
}, {
    headers: {
        token: '123456789'
    },
    method: 'POST',
    timeout: 1000
},  JSON.stringify(body));

Paramètres

Paramètre	Type	Description
url	string	L'URL de la requête.
callback	fonction	Un callback facultatif à invoquer à la fin de la requête, en cas d'erreur ou de timeout. Il est appelé avec le code d'état de la réponse, le les en-têtes de la réponse, et le corps de la réponse (ou undefined s'il n'y avait pas de corps de réponse). Si la requête a échoué (par ex. URL invalide, aucune route vers l'hôte, échec de la négociation SSL, etc.), le callback sera appelé avec un code d'état de réponse égal à zéro, aucun en-tête, et un corps undefined. Si l'option 'timeout' a été définie et que la requête a expiré, le callback sera appelé avec un code d'état de réponse égal à -1, aucun en-tête, et un corps undefined.
options	object	Options de requête facultatives. Les options prises en charge sont : headers, method, et timeout. Les clés d'option inconnues sont ignorées. Des options avancées peuvent être ajoutées dans extraOptions.
body	string	Corps de requête facultatif.

Options

• headers: En-têtes de requête supplémentaires.

• method: La méthode de requête, la valeur par défaut est 'GET'.

• timeout: Le timeout, en millisecondes, avant l'abandon de la requête.

• extraOptions: Options avancées (ex : {strictSSL:true})

md5Sync

Calcule et renvoie le md5 empreinte de l'entrée.

Syntaxe

md5Sync(input);

Exemple

const md5Sync= require('md5Sync');
const email = {};
const email.md5 = md5Sync(user.user_email);
sendHttpGet('https://example.com/collect?e5=' + email.md5);

templateDataStorage

Le templateDataStorage helper permet le stockage temporaire et la récupération de données, telles que des tokens API, pendant l'exécution du script. Il est particulièrement utile pour mettre en cache des données réutilisables afin de réduire les appels API redondants. Les données stockées dans templateDataStorage persiste sur le serveur qui exécute le template. Comme les templates s'exécutent sur plusieurs serveurs, et que chaque serveur peut avoir plusieurs instances, il n'est pas garanti que les données stockées soient accessibles pour toutes les exécutions ultérieures du template.

Syntaxe

templateDataStorage.setItemCopy(key, value);
templateDataStorage.getItemCopy(key);
templateDataStorage.removeItemCopy(key);

Exemple : gestion des tokens API

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

const tokenKey = 'apiToken';

function fetchNewToken(callback) {
  sendHttpRequest('https://example.com/api/token', function (status, _, body) {
    if (status === 200) {
      const { accessToken, expiresIn } = JSON.parse(body);
      const tokenData = { token: accessToken, expiry: Date.now() + expiresIn * 1000 };
      templateDataStorage.setItemCopy(tokenKey, tokenData);
      callback(accessToken);
    } else {
      callback(null);
    }
  }, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ clientId: 'id', clientSecret: 'secret' }) });
}

function sendEvent(eventData) {
  const cachedToken = templateDataStorage.getItemCopy(tokenKey);
  const token = cachedToken && cachedToken.expiry > Date.now() ? cachedToken.token : null;

  sendHttpRequest('https://example.com/api/events', function (status) {
    if (status === 401) {
      fetchNewToken(function (newToken) {
        if (newToken) {
          sendHttpRequest('https://example.com/api/events', () => {}, { method: 'POST', headers: { Authorization: `Bearer ${newToken}` }, body: JSON.stringify(eventData) });
        }
      });
    }
  }, { method: 'POST', headers: { Authorization: `Bearer ${token}` }, body: JSON.stringify(eventData) });
}

sendEvent({ eventName: 'purchase', value: 100 });

Méthode	Description
setItemCopy(key, value)	Stocke une valeur sous la clé spécifiée. Écrase la valeur si la clé existe déjà.
getItemCopy(key)	Récupère la valeur associée à la clé spécifiée. Renvoie undefined si la clé n'existe pas.
removeItemCopy(key)	Supprime la valeur associée à la clé spécifiée.

Paramètre	Type	Description
clé	string	L'identifiant unique des données à stocker/récupérer.
valeur	de	Les données à stocker (par setItemCopy).