Helpers javascript serverside

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

decodeURI

Décode tous les caractères encodés dans l'URI fournie. Retourne un string qui représente l'URI décodée. Retourne 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	Une URI qui a été encodée par encodeUri() ou par d'autres moyens.

decodeUriComponent

Décode tous les caractères encodés dans le composant d'URI fourni. Retourne un string qui représente le composant d'URI décodé. Retourne 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

Retourne une Uniform Resource Identifier (URI) encodée en échappant les caractères spéciaux. Retourne un string qui représente la chaîne fournie encodée en tant qu'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	Une URI complète.

encodeUriComponent

Retourne une Uniform Resource Identifier (URI) encodée en échappant les caractères spéciaux. Retourne un string qui représente la chaîne fournie encodée en tant qu'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'une URI.

fromBase64

Décode une chaîne encodée en base64. Retourne 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

Retourne un nombre aléatoire number (entier) dans la plage donnée.

Syntaxe

generateRandom(min, max);

Exemple

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

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

getAllEventData

Retourne une copie des données de l'é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
};

Remarquez que les données de l'événement peuvent contenir plus de propriétés que ce que vous avez initialement envoyé à cause des propriétés système qui sont ajoutées automatiquement sur web events et app sdk events.

Exemple de données :

Si vous envoyez cet événement web :

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

Alors la fonction getAllEventData() retournera cet objet :

{
   "event_name": "search",
   "search_term": "blue t-shirt",
   "user": {
      "id": "12345",
      "email": "[email protected]",
      "consent_categories": ["1","3"]
   },
   "url": "https://www.mywebsite.com/path1/path2/", //Ajouté automatiquement si absent
   "path": "/path1/path2/", //Ajouté automatiquement
   "referrer": "https:///www.google.fr", //Ajouté automatiquement
   "title": "My page title", //Ajouté automatiquement si absent
   "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

Retourne un tableau contenant les valeurs de tous les cookies 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 du cookie ne seront pas décodées avant d'être retournées. Par défaut false.

getEventData

Retourne une copie de la valeur au chemin donné dans les données de l'événement. Retourne 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 n'est pas une chaîne, il est converti en chaîne.

getRemoteAddress

Retourne une string représentation de l'adresse IP d'où la requête a été initiée, p.ex. 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.

Retourne une number qui représente l'heure actuelle en millisecondes depuis l'époque Unix, comme retourné par Date.now().

Syntaxe

getTimestamp();

getTimestampMillis

Retourne une number qui représente l'heure actuelle en millisecondes depuis l'époque Unix, comme retourné par Date.now().

Syntaxe

getTimestampMillis();

getType

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

Type d'entrée	Valeur retournée
string	'string'
number	'number'
boolean	'boolean'
null	'null'
undefined	'undefined'
Array	'array'
Object	'object'
Function	'function'

Syntaxe

getType(value);

Exemple

const getType = require('getType');

const type = getType(value);
if (type === 'string') {
  // Traiter une entrée de type string.
} else if (type === 'number') {
  // Traiter une entrée numérique.
} else {
  logToConsole('Unsupported input type: ', type);
}

Paramètres

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

logToConsole

Enregistre son ou ses argument(s) dans la console.

Ces logs 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, et enregistré dans la console.

makeInteger

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

Syntaxe

makeInteger(value);

Paramètres

Paramètre	Type	Description
value	n'importe quel type	La valeur à convertir.

makeNumber

Convertit la valeur donnée en un number.

Syntaxe

makeNumber(value);

Paramètres

Paramètre	Type	Description
value	n'importe quel type	La valeur à convertir.

makeString

Retourne la valeur donnée en tant que string.

Syntaxe

makeString(value);

Paramètres

Paramètre	Type	Description
value	n'importe quel type	La valeur à convertir.

parseUrl

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

Cette API retournera undefined pour toute URL mal formée. Pour les URLs correctement formatées, les champs non présents dans la chaîne URL auront la valeur d'une chaîne vide, ou dans le cas de searchParams, un objet vide.

L'objet retourné 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:[email protected]: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 digest SHA-256 de l'entrée et appelle un callback avec le digest encodé en base64, sauf si l'objet options spécifie un encodage de sortie différent.

Cette signature et ce comportement d'API correspondent à l'API sha256 pour les conteneurs web ; cependant, les Custom Templates dans les conteneurs serveur devraient utiliser l'API sha256Sync 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 digest résultant, encodé en base64, sauf si l'objet options spécifie un encodage de sortie différent.
options	object	Optionnel options pour spécifier l'encodage de sortie. Si spécifié, l'objet doit contenir la clé outputEncoding avec pour valeur l'un des base64 ou hex.

sha256Sync

Calcule et retourne le digest SHA-256 de l'entrée, encodé en base64, sauf si 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	Optionnel options pour spécifier l'encodage de sortie. Si spécifié, l'objet doit contenir la clé outputEncoding avec pour valeur l'un des base64 ou hex.

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

Retourne un objet qui fournit des fonctions JSON.

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

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

Syntaxe

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

Exemple

const JSON = require('JSON');
// La chaîne JSON en entrée est convertie en objet.
const object = JSON.parse('{"foo":"bar"}');
// L'objet en 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érer la valeur absolue.
const absolute = Math.abs(-5);
// Arrondir l'entrée vers le bas au plus proche entier.
const roundedDown = Math.floor(4.6);
// Arrondir l'entrée vers le haut au plus proche entier.
const roundedUp = Math.ceil(2.1);
// Arrondir l'entrée à l'entier le plus proche.
const rounded = Math.round(4.2);
// Retourner le plus grand argument.
const biggest = Math.max(1, 4);
// Retourner le plus petit argument.
const smallest = Math.min(4, 5);
// Retourner le premier argument élevé à la puissance du deuxième argument.
const powerful = Math.pow(4, 2);
// Retourner 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

Fait une requête HTTP GET vers l'URL spécifiée, et appelle un callback avec la réponse une fois la requête terminée ou en cas de timeout.

Syntaxe

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

Exemple

const sendHttpGet = require('sendHttpGet');
// Envoie une requête GET et désigne 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 optionnel à invoquer à la fin de la requête, en cas d'erreur ou de timeout. Il est invoqué avec le code de statut de la réponse, le entê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é (p.ex. URL invalide, pas de route vers l'hôte, échec de la négociation SSL, etc.), le callback sera invoqué avec un code de statut de la réponse égal à zéro, pas d'entêtes, et un corps undefined. Si l'option 'timeout' a été définie et que la requête a expiré, le callback sera invoqué avec un code de statut de la réponse égal à -1, pas d'entêtes, et un corps undefined.
options	object	Options de requête optionnelles. Les options prises en charge sont headers, timeout. Des options avancées peuvent être ajoutées dans extraOptions

Options

• headers: Entêtes de requête supplémentaires représentées sous forme d'objet.

• timeout: Le timeout, en millisecondes, avant que la requête ne soit abortée.

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

sendHttpRequest

Fait 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 en cas de timeout.

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 optionnel à invoquer à la fin de la requête, en cas d'erreur ou de timeout. Il est invoqué avec le code de statut de la réponse, le entê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é (p.ex. URL invalide, pas de route vers l'hôte, échec de la négociation SSL, etc.), le callback sera invoqué avec un code de statut de la réponse égal à zéro, pas d'entêtes, et un corps undefined. Si l'option 'timeout' a été définie et que la requête a expiré, le callback sera invoqué avec un code de statut de la réponse égal à -1, pas d'entêtes, et un corps undefined.
options	object	Options de requête optionnelles. 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 optionnel.

Options

• headers: Entêtes de requête supplémentaires.

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

• timeout: Le timeout, en millisecondes, avant que la requête ne soit abortée.

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

md5Sync

Calcule et retourne le digest md5 de l'entrée.

Syntaxe

md5Sync(input);

Exemple

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

templateDataStorage

The templateDataStorage l'aide permet le stockage temporaire et la récupération de données, telles que des tokens API, pendant l'exécution du script. Elle 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 persistes sur le serveur exécutant le template. Puisque les templates s'exécutent sur plusieurs serveurs, et que chaque serveur peut avoir plusieurs instances, les données stockées ne sont pas garanties d'être accessibles pour toutes les exécutions de template ultérieures.

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. Retourne 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 pour les données à stocker/récupérer.
value	de	Les données à stocker (pour setItemCopy).