Build and managing experience templates

In this article, we will focus on the tasks of building, configuring, and managing the templates that are used to build experiences. These tasks should be performed by a developer familiar with JavaScript and CSS.


Step 1

Select Experiences from the side menu, select new template, and Create new template

Step 2

Enter a name for the template and a description-both are mandatory

Select Save

Editing the code that will power your experiences

For those familiar with creating Custom experiences, the UI for editing code is very similar; you use the same editor to access and edit the JavaScript and CSS files that form the basic building blocks of each template. The JavaScript and CSS are contained in the following files:

  • triggers.js(/content/developers/experience-triggers-js) - used to determine when an experience executes
  • utils.js(/content/developers/experience-utils-js) - used to define common functions and variables that can be reused across experience files
  • fields.json(/content/developers/experience-fields-json) - predefined schema used to define the options that will be made available to the user creating the Simple messages experience
  • package.json(/content/developers/experience-package-json) - contains metadata about your experience, including package dependencies
  • variation.css(/content/developers/experience-variation-css) - used to inject CSS rules into a page if your variation is executed

To get started select template-menu and Edit against the template you wish to edit:


Once you have finished editing the code, you must save it by selecting Save in the editor

You can now return to the Templates view by selecting close-editor in the top-right hand corner of the editor

Working with the triggers.js file

The editor includes a default code block:

module.exports = function triggers (options, cb) {

This trigger will pass when cb() is called. Any code that you wish to add must stay inside that function.

info-icon Code can be asynchronous.

info-icon The cb() function must be called at some point to ensure the trigger rule is seen as passed.

Working with the variation.js file

The variation.js file contains a code block that executes if the visitor is served the experience. Of course, the visitor is only served an experience once all the trigger and segment conditions have been met.

By default, an empty function block is provided:

module.exports = function variation (options) {

Any JavaScript added to the page must be added inside this function block.


module.exports = function variation (options) {
  var $ = window.jQuery

All the code written in the editor is locally scoped.


In this section we will look at a few examples that you can use to get started with the variation.js file.

Remember preview snippet

This is used to persist the preview of the experience across different pages, without the necessity of adding the preview URL parameter to the URL. This will persist the preview link for 15 minutes or until another preview link is loaded.


function (options, cb) {
Poll for elements snippet

This can be used to poll for certain elements to ensure they are on the page before variation.js runs. It can poll for an array of elements or an outcome of functions within the array:


module.exports = function triggers (options, cb) {
  // 1.

  // 2.
  options.poll(function() { return true }).then(cb)

  // 3.
  options.poll(['.nav', '.header']).then(cb)

  // 4.
  options.poll(['.nav', 'window.universal_variable']).then(cb)

  // 5.
  options.poll(['.nav', 'window.universal_variable', function () {
    return true

The resulting targets will be passed into the callback function in the same order.

module.exports = function triggers (options, cb) {
  options.poll(['.nav', '', function () {
Get pageview count snippet

Within Experiences, we expose the options object. Within this there are the getVisitorState and getBrowserState functions. The following can be used to only run the experience if the visitor has more than 5 pageviews in the current session.


module.exports = function triggers (options, cb) {
  options.getVisitorState().then(function (data) {
    if (data.viewNumber > 5) cb()
Get session count snippet

This can be used to return the total session count for a visitor.


module.exports = function triggers (options, cb) {
  options.getVisitorState().then(function (data) {
    if (data.sessionNumber > 2) cb()

Working with the fields.json file

This file defines the options that will be available to the user building the experience. See fields.json for details of using this file.

Previewing a template

Periodically, whilst building your template, it is recommended that you preview it to ensure it functions as expected.

Step 1

Select preview exp

Step 2

Enter a value in the Preview URL field and define the background image to use for the banner by entering a value in the Image field

info-icon This must be an absolute URL and include the prefix http://, for example, will work. /my-background-image will not work.

Step 3

Define the hyperlink for the banner by entering a value in the Link URL field

info-icon This must be an absolute URL and include the prefix http://, for example will work.

Step 4

Select Preview

The fields displayed above correspond to the input fields you defined in fields.json:


  "title": {
    "type": "url",
    "label": "Preview URL",
    "required": true,
    "description": "The preview URL"

Managing existing templates

Once you have built and configured a template, it will be added to your list of templates. From this list, you can edit it, change its status, and duplicate it. Refer to the following sections.

To manage your templates, select Experiences from the side menu, select new template, and Manage templates

The Templates view shows a list of your templates and includes the following details for each one:

  • The template name
  • The type of experience the template can be used for
  • The number of experiences the template is powering
  • The status of the template

In the following example, we see that the template called Hero banner offer is currently powering 2 Simple messages experiences. Its status denotes that it has been tested and verified by QA and is therefore ready to be used in a productive environment. Only templates that are marked as Production-ready can be used to build experiences.


info-icon Once a template powers one or more experiences, it can no longer be edited. In this scenario, it is recommended to duplicate the template and make any changes there. See Duplicating a template for more information.

Editing a template

As long as your template is not being used by an experience, you can make changes to it.

Step 1

Select the menu button and Edit, as shown in the following example:

experience dev template 5

Duplicating a template

As mentioned, duplicating a template is a good option if a template you built is already being used to power experiences and you want to make a change to the template. Duplicating is also recommended when you want to push a template to a productive environment and keep a copy as a draft that you could continue working on.

Step 1

Select the menu button and Duplicate

Step 2

Enter a name for the duplicate template and select Duplicate

Renaming a template

As long as your template is not being used to power any Simple messages experiences, you can rename it

Step 1

Select the menu button and Rename

Step 2

Enter a name for the template and select Rename

Deleting a template

As long as your template is not being used to power any experiences, you can delete it. Once deleted, a template cannot be retrieved. It is therefore recommended that you exercise caution when deleting templates.

Step 1

Select the menu button and Delete

Step 2

Select Delete to confirm

Last updated: January 2023
Did you find this article useful?