The Destination builder allows you to create custom server-side destinations using server-side javascript (aka Node.js), but with an easy and simplified subset of Node.js : the Javascript Sandbox.

This tutorial will teach you the basics of writing your own server-side destination template and publish it in your own destination catalog(s).

Basic example: Slack

In this tutorial, you will create a destination that sends event data to Slack using a single webhook_url parameter. Slack is a messaging and collaboration tool that supports webhook integration. The Use cas can be : "I want to receive on a Slack channel a message each time an event "sign_up" is received"

Destination Configuration

To begin, create the destination template by navigating to the Destination section in the menu and clicking New in the Destination Builder section. Then, give your destination a name, a logo, a category and a description.

Then, go to the Fields section of the editor to add settings options for your destination. You have three options for building your destination:

1. Total Configuration: Create a configuration field for every parameter, allowing the user to set everything explicitly.

2. No Configuration: Do not include any options for configuring the destination. Instead, all data is taken directly from the event.

3. Some Configuration: Include fields for some parameters but not others.

While having a field for every parameter is flexible, it can result in a lot of duplicated work for the user. Therefore, it is best to have the code handle the configuration of unambiguous and universal data. For example, if you are building an analytics destination, you don't want to ask to the user to enter the URL of the analytics API every time he will setup this destination. You will prefer to hardcode the URL inside your code without to ask user to enter it. On the other hand, if you build your destination to get the data only from the event, without adding any field in the settings for the user, the user will not be able to personnalize the destination. For example, if the destination required a token, this token may vary according to the context (prod, dev, country...), so if you hardcode one token in the code... Or, perhaps the assumptions made by the destination regarding the structure of the incoming event data do not align with the actual reality for custom events/properties. In both scenarios, the user is unable to proceed.

In conclusion, some data should always be extracted from the event while other data needs to be configured by the user. It is up to you to decide so that the end result is user-friendly.

In the case of our Slack destination, we will want to add one field so that the user can copy/paste its Slack's webhook url. We choose a text input like this:

Now, we can go to the Code tab, starting to write the code of our destination template.

How to get the data in your code ?

You may want to get 2 types of data :

1. user-entered data (fields filled in the settings tab)

2. event data (some properties of your event that you want to send to the partner)

1. User-entered data

All data filled in the differents fields by the user are accessible in the data object in your code. In your example, we have only one field named "url", and the value that the end-user will enter will be accessible via data.url

2. Event data

You will want to get some properties of your events to send them to the partner server. You can use one of this 2 functions to get your event data :

• getAllEventData() => will return an object will all the event properties

• getEventData(myProperty) =>will return the value of a specific property in your event

Destination implementation

After setting up the destination configuration, you can proceed to implement its behavior in the JavaScript Sandbox.

The Slack example requires the following four steps:

1. Obtain the webhook URL from the destination's settings.

2. Create the message that will be sent to the Slack API.

3. Send a request to the Slack collection server to transmit the data.

4. Test your code, to make sure that the destination will behave appropriately in production.

It's important to note that the code should not perform certain actions, as they are the responsibility of the filter tab. Specifically, the code should not:

• Manage the consent to determine wether the event should be send or not. It is the responsability of the consent category dropdown in the Filter tab. It is important not to override this feature, to not break the Data Governance reports

• Analyze the event properties to determine whether it should be executed. Don't forget that the user will be able to choose in the Filter tab wich event will be sent to the destination. You may want to restrict your code to some event's type, but you should not remove the user's ability to filter his events on certain properties (ex : the user may want to send only events with property "country" equals to "UK")

• Return an global error (data.onFailure()) when some event's type does not fit the destination. Prefer to use silent error with data.onFailure({ status: 'filtered'})

If you create a destination template that performs any of these actions, it can cause confusion for users of your destination. For instance, a destination that sends errors to Event Delivery whenever unsupported events are detected can lead to unnecessary warnings in Health reports. This would violate users' expectations regarding the expected behavior of the destination.

With this in mind, here is an annotated example of the tag implementation in JavaScript sandbox:

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

//We get the event data (all event's properties)
const eventModel = getAllEventData();

if (eventModel.event_name == 'sign_up') {
    //get the url from what the user wrote in the webhook url field
    //Settings data comes into the sandboxed code as a predefined 
    //variable called 'data'.
    const url = data.url; 
    //Construct the body message, concatening the user name inside the sentence to send
    const postBody = '{"text": "' + eventModel.user.firstname + ' ' + eventModel.user.lastname + 'just signed up!"}';

    // Send the data to the Slack server
    //The sendHttpRequest function takes a URL,a result callback, optionally a header, a method and a body.
    sendHttpRequest(url, (statusCode, headers, body) => {
        if (statusCode >= 200 && statusCode < 300) {
            //send a success information to the Event Delivery report
            data.onSuccess();
        } else {
           //send an error to the Event Delivery report
            data.onFailure();
        }
    }, { headers: { 'Content-Type': 'application/json' }, method: 'POST', timeout: 1000 }, postBody);
}
else {
    //silent failure that will not send an error in the Event Delivery report
    data.onFailure({ status: 'filtered', detail: 'unsupported_event' });
}

decodeURI

Decodes any encoded characters in the provided URI. Returns a string that represents the decoded URI. Returns undefined when provided with invalid input.

Syntax

decodeUri(encoded_uri);

Example

const decodeUri = require('decodeUri');

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

decodeUriComponent

Decodes any encoded characters in the provided URI component. Returns a string that represents the decoded URI component. Returns undefined when given invalid input.

Syntax

decodeUriComponent(encoded_uri_component);

Example

const decodeUriComponent = require('decodeUriComponent');

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

encodeUri

Returns an encoded Uniform Resource Identifier (URI) by escaping special characters. Returns a string that represents the provided string encoded as a URI.

Syntax

encodeUri(uri);

Example

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

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

encodeUriComponent

Returns an encoded Uniform Resource Identifier (URI) by escaping special characters. Returns a string that represents the provided string encoded as a URI.

Syntax

encodeUriComponent(str);

Example

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

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

fromBase64

Decodes a base64-encoded string. Returns undefined if the input is invalid.

Syntax

fromBase64(base64EncodedString);

Example

const fromBase64 = require('fromBase64');

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

generateRandom

Returns a random number (integer) within the given range.

Syntax

generateRandom(min, max);

Example

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

getAllEventData

Returns a copy of the event data.

Syntax

getAllEventData();

Usage Example

const getAllEventData= require('getAllEventData');
const eventModel = getAllEventData();
//build body request from event properties 
const body = {
    crm_id:eventModel.user.id,
    currency:eventModel.currency
};

Data example:

If you send this web event:

cact('trigger', 'search', {
  "search_term": "blue t-shirt",
  "user": {
    "id": "12345",
    "email": "anakin.skywalker@domain.com",
    "consent_categories": ["1","3"]
  }
);

Then the getAllEventData() function will return this object:

{
   "event_name": "search",
   "search_term": "blue t-shirt",
   "user": {
      "id": "12345",
      "email": "anakin.skywalker@domain.com",
      "consent_categories": ["1","3"]
   },
   "url": "https://www.mywebsite.com/path1/path2/", //Automatically added if missing
   "path": "/path1/path2/", //Automatically added
   "referrer": "https:///www.google.fr", //Automatically added
   "title": "My page title", //Automatically added if missing
   "context": {
      "event_id": "202110130000000000", //Automatically added
      "generatorVersion": "10.0", //Automatically added
      "containerVersion": "3.1", //Automatically added
      "event_timestamp": "1639044446636", //Automatically added
      "page": { //Automatically added
         "title": "Search page", //Automatically added
         "url": "https://shop.com/search?q=...", //Automatically added
         "lang": "en", //Automatically added
         "referrer": "https:///www.google.fr", //Automatically added
         "viewport": { //Automatically added
            "width": 320, //Automatically added
            "height": 568 //Automatically added
         }
      },
      "device": { //Automatically added
         "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",//Automatically added
         "ip": "102.3.4.56",//Automatically copied from the request header
         "lang": "fr",//Automatically added
         "cookie": "_fbp=123; _fbc=456; _ga=789",//Automatically added
         "timezone": "Europe/Paris"//Automatically added
      }
   }
}

getCookieValues

Returns an array containing the values of all cookies with the given name.

Syntax

getCookieValues(name[, noDecode]);

Example

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

Parameters

getEventData

Returns a copy of the value at the given path in the event data. Returns undefined if there is no event data or if there is no value at the given path.

Syntax

getEventData(keyPath);

Example

const getEventData = require('getEventData');

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

Parameters

getRemoteAddress

Returns a string representation of the IP address where the request originated, e.g. 62.123.65.780 for IPv4 or 2001:0db8:85a3:0:0:8a2e:0370:1234 for IPv6

Syntax

getRemoteAddress();

getTimestamp

Deprecated. Prefer getTimestampMillis.

Returns a number that represents the current time in milliseconds since Unix epoch, as returned by Date.now().

Syntax

getTimestamp();

getTimestampMillis

Returns a number that represents the current time in milliseconds since Unix epoch, as returned by Date.now().

Syntax

getTimestampMillis();

getType

Returns a string describing the given value's type.

Syntax

getType(value);

Example

const getType = require('getType');

const type = getType(value);
if (type === 'string') {
  // Handle string input.
} else if (type === 'number') {
  // Handle numeric input.
} else {
  logToConsole('Unsupported input type: ', type);
}

Parameters

logToConsole

Logs its argument(s) to the console.

These logs are visible within Destination Builder's console.

Example

const logToConsole = require('logToConsole');

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

Syntax

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

Parameters

The function takes one or more arguments, each of which is converted to a string, if necessary, and logged to the console.

makeInteger

Converts the given value to a number (integer).

Syntax

makeInteger(value);

Parameters

makeNumber

Converts the given value to a number.

Syntax

makeNumber(value);

Parameters

makeString

Returns the given value as a string.

Syntax

makeString(value);

Parameters

parseUrl

Returns an object that contains all of a given URL's component parts, similar to the URL object.

This API will return undefined for any malformed URL. For properly formatted URLs, fields not present in the URL string will have a value of an empty string, or in the case of searchParams, an empty object.

The returned object will have the following fields:

{  
    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,
}

Syntax

parseUrl(url);

Example

const parseUrl = require('parseUrl');const urlObject = parseUrl('https://abc:xyz@example.com:8080/foo?param=val%2Cue#bar');

Parameters

sha256

Calculates the SHA-256 digest of the input and invokes a callback with the digest encoded in base64, unless the options object specifies a different output encoding.

This API signature and behavior matches the sha256 API for web containers; however, Custom Templates in server containers should use the sha256Sync API for simpler code.

Syntax

sha256(input, onSuccess, options = undefined);

Example

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'});

Parameters

sha256Sync

Calculates and returns the SHA-256 digest of the input, encoded in base64, unless the options object specifies a different output encoding.

Syntax

sha256Sync(input, options = undefined);

Example

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));

Parameters

toBase64

Encodes a string as base64.

Syntax

toBase64(input);

Example

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

Parameters

JSON

Returns an object that provides JSON functions.

The parse() function parses a JSON string to construct the value or object described by the string. If the value cannot be parsed (malformed JSON), the function will return undefined. If the input value is not a string, the input will be coerced to a string.

The stringify() function converts the input into a JSON string. If the value cannot be parsed (ex. the object has a cycle), the method will return undefined.

Syntax

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

Example

const JSON = require('JSON');
// The JSON input string is converted to an object.
const object = JSON.parse('{"foo":"bar"}');
// The input object is converted to a JSON string.
const str = JSON.stringify({foo: 'bar'});

Math

An object providing Math functions.

Syntax

const Math = require('Math');
// Retrieve the absolute value.
const absolute = Math.abs(-5);
// Round the input down to the nearest integer.
const roundedDown = Math.floor(4.6);
// Round the input up to the nearest integer.
const roundedUp = Math.ceil(2.1);
// Round the input to the nearest integer.
const rounded = Math.round(4.2);
// Return the largest argument.
const biggest = Math.max(1, 4);
// Return the smallest argument.
const smallest = Math.min(4, 5);
// Return the first argument raised to the power of the second argument.
const powerful = Math.pow(4, 2);
// Return the square root of the argument.
const unsquared = Math.sqrt(81);

Parameters

Math function parameters are converted to numbers.

sendHttpGet

Makes an HTTP GET request to the specified URL, and invokes a callback with the response once the request completes or times out.

Syntax

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

Example

const sendHttpGet = require('sendHttpGet');
// Sends a GET request and nominates response// based on the response from the GET 
sendHttpGet('https://example.com/collect', function(statusCode, headers, body) {
    if (statusCode != 200) {yourCallbackFunction();}
}, {
    headers: {key: 'value'},
    timeout: 500
});

Parameters

Options

• headers: Additional request headers represented as an object.

• timeout: The timeout, in milliseconds, before the request is aborted.

• extraOptions: Advanced options (ex: {strictSSL:true})

sendHttpRequest

Makes an HTTP request to the specified URL, and invokes a callback with the response once the request completes or times out.

Syntax

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

Example

const sendHttpRequest = require('sendHttpRequest');
const body = {
    user_type:'vip',
    account:'123'
};
// Sends a POST request 
sendHttpRequest('https://example.com/collect', function(statusCode, headers, body) {
    //your callback code...
}, {
    headers: {
        token: '123456789'
    },
    method: 'POST',
    timeout: 1000
},  JSON.stringify(body));

Parameters

Options

• headers: Additional request headers.

• method: The request method, defaults to 'GET'.

• timeout: The timeout, in milliseconds, before the request is aborted.

• extraOptions: Advanced options (ex: {strictSSL:true})

md5Sync

Calculates and returns the md5 digest of the input.

Syntax

md5Sync(input);

Example

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

For more advanced users, we propose to create custom destinations using server-side javascript (aka Node.js), but with an easy and simplified subset of Node.js : the Javascript Sandbox.

Javascript Sandbox

Sandboxed JavaScript is a simplified Javascript that allows you to execute arbitrary JavaScript logic from your custom destination securely and easily (no need to learn Node.js or to understand the async/await syntax for example. If you know the basics of Javascript ES5, it is enough)

This simplified Javascript is based on helpers, set of methods that allow you to easily and quickly process and send your data.

Event or Audience destination

You can choose to create an Event destination (to forward events like purchase, page view...) or Audience destination (send users who entered or were removed from a specific segment).

For Event destination, all standard and custom events can be used as input.

For Audience destination, only 2 system events are managed:

• user_enters_segment

• user_leaves_segment

These 2 events are automatically trigger by the system when a user enter or leave a segment. Format of audience events:

{
  "event_name": "user_enters_segment",
  "user": {
    "id": "user1",
    "email": "user1@example.com",
    "firstname": "john user1",
    "lastname": "Doe"
  },
  "context": {
    "segment_id": 1,
    "segment_name": "Audience 1"
  }
}

{
  "event_name": "user_leaves_segment",
  "user": {
    "id": "user1",
    "email": "user1@example.com",
    "firstname": "john user1",
    "lastname": "Doe"
  },
  "context": {
    "segment_id": 1,
    "segment_name": "Audience 1"
  }
}

The template editor

The Template Editor enables you to create, preview, and test custom templates. It has four primary areas for input to help you define your destination template:

• Informations: Define basic information of the template, such as the logo, category, name.

• Fields: This is a visual drag&drop editor to add input fields to your destination template.

• Code: Enter sandboxed JavaScript to define how your destination will map/transform/send the data.

• Publish: View/change on wich catalogs (workspaces) your destination is visible.

If you want to send data to a destination that is not in our destination's catalog, you can open a destination request, or you can write your own destination.

The destination builder allows you to create your own custom destination, either with a no-code approach (Webhook, FTP, API, GTM importer) or with a javascript sandbox aproach (low-code) :

• Webhook/API/FTP destination builder (no-code experience)

• JavaScript destination builder (JS sandbox)

• GTM template importer (convert to JS sandbox template out of the box)

Create and publish a destination

When you publish your work in the destination builder, your destination will be visible for your team in the destination catalog beside other destinations.

In the destination builder interface, you will be able to set:

• Information about the destination (label, logo, category)

• Destination settings, i.e. questions that will be asked to the user that will add this destination (e.g. token, account id, options ...)

• Connector technical options (url, method, etc.) or JavaScript code

Your destination can also be hosted on Github and automatically imported to facilitate updates on your side.