Build and manage experience templates

In this article...

We'll 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.

Why use templates?

Once you have built a template, it can be used by non-technical members of your team to create experiences without the need for additional developer resources.

Building

Step 1

▸ Select Experiences from the side menu and then New experience. Switch to the My templates view

▸ Select Add new and then Template

Step 2

▸ Enter a name for the template and a description—both are mandatory

▸ Select Save

Editing the code that will power your template

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 - used to determine when an experience executes
  • utils.js - used to define common functions and variables that can be reused across experience files
  • fields.json - predefined schema used to define the options that will be made available to the user creating the Simple messages experience
  • package.json - contains metadata about your experience, including package dependencies
  • variation.js - controls what happens once the experience has been triggered and should contain the main body of your experience logic
  • 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 start building:

edit-template

▸ Then in Edit template, select Edit in Code:

edit-code

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

▸ You can then 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) {
  cb()
}

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

INFO: Code can be asynchronous.

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

For more on triggers, see triggers.js.

Triggers.js snippets

In this section we will look at a few examples that you can use to get started with the triggers.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.

Example:

function (options, cb) {
  require('@qubit/remember-preview')(15)
  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:

Example:

module.exports = function triggers (options, cb) {
  // 1.
  options.poll('.nav').then(cb)

  // 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
  }]).then(cb)
}

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

module.exports = function triggers (options, cb) {
  options.poll(['.nav', 'window.universal_variable.page.type', function () {
    return window.foo()
  }]).then(cb)
}

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.

Example:

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.

Example:

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

Working with the utils.js file

This file provides a convenient space for defining common functions and variables that can be reused across experience files.

See utils.js for details of how to use this file.

Working with the fields.json file

One of the key strengths of templates is that they allow you to standardize experiences and move towards an out-of-the-box approach to delivering experiences. Many times, however, you will want to allow non-technical members of your team to customize some parts of those experiences that use your template. This is done in fields.json.

Importantly, this customization can be done without further developer assistance or changes to experience code. See fields.json for details of using this file.

Working with the package.json file

This file is used to declare package dependencies. Declaring dependencies means that we only include those packages that are used in the smartserve bundle, which is good for performance and bundle size.

Declaring package dependencies is covered in detail in Using Packages and you can read more about the power of packages and code re-use in Packages & Code Re-use.

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.

Example:

module.exports = function variation (options) {
  var $ = window.jQuery
  $("#navigation_sale").text("offers")
}

All the code written in the editor is locally scoped.

Configuring a template

Configuring the experience template is done pretty much in the same way as configuring any one of our experiences, and involves adding the goals, simple triggers, segments, etc, that control how experiences behave.

TIP: Of course non-technical team members are free to change any of this configuration when they build an experience from a template. For this reason, we recommend considering whether it is more convenient for your team to add configuration to the template rather than leaving it at the experience level.

WARNING: Traffic allocation, custom statistical threshold, Google Analytics integration, and scheduling must be added to the experience rather than the template.

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

edit-template

▸ Then in Edit template, select Edit in the part of the configuration you wish to edit

Refer to our documentation on configuring experiences for more information about how to do this.

Publishing a template

Only published template can be used to build experiences.

INFO: Any experience you build using a template will not be affected by any changes you subsequently make to that template.

Let's suppose you build a new template, publish it, and then build 5 experiences using that template. You now decide to edit the template by adding the trigger Minimum pageviews, publish it a second time, and build another experience using the same template.

Only the last experience you built will include the triggers. The changes you made will not be applied to those 5 experiences you already built:

publishing template

Step 1

▸ If your template is not already open, select context menu and then Edit

Step 2

▸ Select Publish

Editing a template

As mentioned above, any changes you make to a template after it has been published are not applied retrospectively to those experiences built before the changes.

Step 1

▸ If your template is not already open, select context menu and then Edit

Step 2

▸ Make the necessary changes to the template and select Save after each change. In the following example, the user can see that 1 unpublished change has been made:

unpublished change

Step 3

▸ If you wish to publish those changes immediately, select Review and Publish. This opens a window displaying a before and after view of all the unpublished changes.

In the following example, we see that the user has removed the Revenue Per Converter goal:

all changes

Step 4

▸ If you are happy with the changes, you can now select Publish. Alternatively, to delete the changes, select Discard

TIP: You may also choose to not publish those changes immediately. For example, if other team members are involved in building templates, you may wish to wait for a review of the change, or equally, wait for other team members to also make changes.

Whatever the reason, you can simply close Edit template and return to the template at a later date to publish the changes. When you do this, draft will display alongside your template and the tooltip will be Has Unpublished Changes:

unpublished changes

Duplicating a template

Duplicating is useful when you want to copy a template as the basis for a new one or when you want to publish a template but keep a copy as a draft that you can continue working on.

▸ If your template is not already open, select context menu and then Duplicate

Archiving a template

In the same way that you can archive an experience, you can also archive templates. Only published templates can be archived.

Archived templates are hidden by default, but you can show them along with all your other templates by selecting show archived.

archived-template denotes an archived template:

archived-template-in-list

▸ If your template is not already open, select context menu and then Archive

▸ To unarchive a template, select context menu and then Unarchive

Deleting a template

If you are certain that you no longer require a template, you can delete it. Only templates that have not been published can be deleted.

▸ If your template is not already open, select context menu and then Delete. Select Delete a second time to confirm

Sharing templates between properties

You can share templates with any other properties created for your client property. For example, you might develop templates on a staging environment—counted as a property—and want to move them to your production environment.

▸ Select template-menu and Share with other properties

▸ Select inside the Properties field and choose one or more properties to share the template with

TIP: You can also search for a property by entering a value in Properties.

In the following example, we can see that the user has selected to share the template with the property FR property:

chosen-property

▸ When done, select Save:

share-template

Creating template folders

In many cases, it will make sense to organize your templates into folders. For example, you may choose to organize your templates around experience types or campaign types.

Step 1

▸ Select Experiences from the side menu and then New experience. Switch to the My templates view

Alternatively, select the down arrow next to New experience and select From a template:

from-a-template

Step 2

▸ Select Add new and Folder:

choose-folder

By default, your folder will be named New folder:

new-folder

You can also create a folder by selecting the option Create group from selection:

create-folder-from-selection

Moving templates into folders

Once created, you can now start to move templates into the folder by dragging and dropping. In the following example, we see that the user is moving the template Recs-light to their new folder:

drag-drop

TIP: You can move templates between folders and out of folders in the same way.

The number of templates inside a folder is shown. Selecting this number expands the folder to show the templates inside.

In the following example, we see that the folder Recs folder has one template inside:

templates-in-folder

Renaming a folder

▸ To rename, simply select the folder name and edit as required

Deleting a folder

WARNING: You can only delete empty folders.

▸ To delete, select delete-folder against the template

Last updated: June 2020
Did you find this article useful?