NAV
js

Templates API

Welcome to Trustisto Templates API documentation. You can use our Template API to create new templates for your Trust Overlays, Trust Bars, Trust Mails.

If you have any problem with our API, our developers are happy to help. You can drop us an e-mail at it@trustisto.com. We are happy to help you.

Dev Index

Introduction

Templates are HTML/CSS/JS components that can be used as Trustisto Overlays, Bars or even Mails.

As a developer, you are creating template with set of parameters which user can use to personalize that template for his need. For example user can change:

You decide what can be changed by embedding parameters into HTML and embedded CSS code using handlebars {{...}}) notation and describe all parameters in manifest.json file.

Structure

Our Templates have strict structure:

zip -rj template.zip template_folder/*
  adding: index.html (deflated 73%)
  adding: manifest.json (deflated 81%)
  adding: thumbnail.png (deflated 19%)

unzip -l template.zip
Archive:  template.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
     3923  04-23-2021 14:41   index.html
     3642  04-23-2021 14:41   manifest.json
     7229  03-17-2021 11:47   thumbnail.png
---------                     -------
    14794                     3 files

Template when deployed should be compressed into zip file.

manifest.json

Manifest is a file that describe your template and all parameters that final user can personalize.

{
  "version": 1,
  "name": "Template Name",
  "categories": ["collect", "increase", "guide", "connect"],
  "type": "popup",
  "origin": "URL address of origin template, if this was cloned",
  "description": {
    "pl": "Polish description",
    "en": "English description"
  },
  "width": 1200,
  "height": 630,
  "responsive": false,
  "form": {
    "fields": {
       "name": "string",
       "email": "string"
    },
    "options": {
      "closeOnSubmit": false
    }
  },
  "params-sections": {
    "general": {
      "title": {
        "pl": "Ustawienia",
        "en": "Settings"
      },
      "description": {
        "pl": "Główne ustawienia overlaya",
        "en": "Main overlay settings"
      }
    }
  },
  "params": {
    "header": {
      "type": "text",
      "section": "general",
      "label": "Headline", // without localization
      "required": false,
      "default": {
        "pl": "Cześć <b>Świecie</b>",
        "en": "Hello <b>World</b>"
      },
      "html-friendly": true
    },
    "headerFontSize": {
      "type": "number",
      "section": "general",
      "label": {
        "pl": "Rozmiar czcionki nagłówka",
        "en": "Header font size"
      },
      "required": false,
      "default": 24,
      "min": 12,
      "max": 36
    },
    "bgcolor": {
      "type": "color",
      "section": "general",
      "label": {
        "pl": "Kolor tła",
        "en": "Background color"
      },
      "required": false,
      "default": {
        "pl": "#ffffff",
        "en": "#ffffff"
      }
    }
  }
}

Trust Bar only manifest fields:

Form form

If template has a form that can be submitted you need to declare it in manifest in form node (look at example on the right). Inside this node there are two objects fields and options

In fields you declare names (name=) of the form fields alongside type which can be one of the following:

In options whish is optional, you can include following parameters:

Parameter Sections params-sections

Parameter section groups parameters to single logic set. Parameter sections are stored in params-sections object, where keys are a sections individual IDs.

Single params-sections has following properties:

Parameters params

Parameters makes template dynamic and personal. When final user choose your template he can change any of them. So make sure you add plenty of them to allow personalize your template.

You can group parameters into parameters sections. Parameters are stored in params object, where keys are parameter names.

Single param has following properties:

Parameter property type:

"buttonHeight": {
  "type": "number",
  "min": 10,
  "max": 50,
  "section": "general",
  "label": {
    "pl": "Wysokość przycisku",
    "en": "Button height"
  },
  "required": false
},

"buttonAnimation": {
  "type": "select",
  "section": "general",
  "label": {
    "pl": "Animacja przycisku",
    "en": "Button animation"
  },
  "required": false,
  "selectOptions": [
    {
      "value": "appear",
      "labels": {
        "pl": "Pojawienie się",
        "en": "Button appear"
      }
    },
    {
      "value": "slide-in-left",
      "labels": {
        "pl": "Wjazd od lewej",
        "en": "Slide-in from left"
      }
    }
  ]
}

Parameter property html-friendly:

Sometimes we need to allow final user to insert raw HTML code inside our template. To make this work, mark parameter as HTML friendly with this attribute. This will give user hint in template editor.

To make this full work you need to also put data-html-friendly="true" attribute in parent tag, see below.

Parameter property showWhen:

"buttonColor": {
  "type": "color",
  "section": "general",
  "label": {
    "pl": "Kolor przycisku",
    "en": "Button color"
  },
  "required": false,
  "showWhen": {
    "otherParameterName": "isButtonVisible",
    "comparisonType": "equals",
    "otherParameterValue": "true"
  }
}

You can display certain parameters in Template Editor based on other parameters value. This is helpful if you have some conditions like "show/hide button" and then you can specify "buttonColor".

comparisonType: includes|equals|greaterOrEqual|lessOrEqual

index.html

This file is a entry point of a template.

<script src="https://js.trustisto.com/socialproof_succker.js"></script>

When creating index.html you can use every HTML tag - but please check their support in older browsers. You can include custom Stylesheets and JavaScript. In case of Mail templates it is better to use some framework ex. MJML.

<link rel="stylesheet" href="/mystyle.css">
<link rel="stylesheet" href="//other.domain.com/external-style.css">

We recommend to save all 3rd party resources inside template folder and load them via relative path.

For external sources please use URL without protocol, so not http://somehost.com/file.png but use //somehost.com/file.png, so you template can work properly in HTTP and HTTPS environment (see samples on the right)

Parameters

<html>
<head>
  <style>
    h2 {
      background-color: {{bg-color}};
    }
  </style>
</head>
<body>
  <h2 ut:style="font-size: {{headerFontSize}}px;" data-html-friendly="true">{{header}}</h2>
  <form>
    <input type="text" name="name" />
    <input type="email" name="email" />
    <input type="submit" ut:text="{{submitText}}"/>
  </form>
  <script src="https://js.trustisto.com/socialproof_succker.js"></script>
</body>
</html>

In addition to static HTML and CSS you can include parameters using handlebars syntax {{parameter}}. In render time (see below), this parameter will be replaced by proper value.

You can also use parameters in tag attribute. To skip browser validation perpend attribute name with ut: ex. <img ut:src="{{imageURL}}" /> When value of a parameter will be known, name of the attribute would change.

You can add data-html-friendly="true" if you'd like to allow user to insert HTML code in that element. Information in manifest about HTML content is only for template editor. This attribute is mandatory to make it work.

You can also use parameters inside embedded Stylesheet <style></style>

Control Visibility

In addition, you can also control visibility of tags using this attributes:

Loops

You can use ut:loop argument to build dynamically HTML elements based on array parameters. Please check section about products (below).

Redirects

<a ut:data-redirect="http://myshop.com/target-website">Click me</a>
<a ut:data-redirect="{{some-param}}">Click me</a>

If you want to redirect client to specific page, and that action need to be measured use ut:data-redirect attribute on <a> tag. Whenever user click on that element, he will be redirected to specific page and that click will be measured as engage from overlay.

CTA

<a ut:cta="{{param}}">Click me</a>

If you want to make Call To Action element, you can use ut:data-cta= attribute on a button or <a> tag. Each of CTA types will trigger an engage event.

Product & ProductArray

{
  "productName": "Product name",
  "productPrice": "50",
  "productCurrency": "USD",
  "productImage": "assets/img/shoe.jpeg",
  "productUrl": "http://shop.com/link-to-product"
}

<div ut:loop="{{products}}">
  <a ut:data-redirect="{{products[].productUrl}}" >
    <img src="{{products[].productImage}}" />
    <span>{{products[].productName}}</span>
  </a>
</div>

Our template can display products. There is a type of a parameter product and productArray. You can use ut:loop= to iterate over product and display them, or just display single product.

Reviews

{
  "userName": "John",
  "rate": "5",
  "timestamp": "",
  "description": "This store is gr8!",
  "permalink": "http://facebook.com/review/..."
}

Our template can also display users reviews, from Google, Facebook etc. There is a type of a parameter review and reviewArray. You can use ut:loop= to iterate over product and display them, or just display single product.

Forms

Your template can also have a form!

You can have only one form inside template and it should be described in manifest.json (see above)

Consents

You can send two types of consent within the form. If form has an e-mail or phone filed, this consent will be attached to a specific user on channel used in that form. So if user will submit his e-mail, specific consent will be set for that user only for e-mail channel.

Those types are:

To send consent insert checkbox or input type=hidden inside the form:

Counters

"deadline": {
  "type": "date",
  "section": "countdown",
  "label": {
    "pl": "Termin wygaśnięcia licznika",
    "en": "Countdown final time"
  },
  "required": false,
  "default": "",
  "dateOptions": {
    "relative": true,
    "absolute": true
  }

<div class="countdown" ut:data-deadline="{{deadline}}" ut:data-timePassedMessage="{{tooLate}}">
  <span class="days"></span>
  <span class="hours"></span>
  <span class="minutes"></span>
  <span class="seconds"></span>
</div>

Our template have build-in counter feature. So you can easily display dynamic counters in your template.

You can use parameters with counters, so user can decide what is the deadline absolute or relative.

When defining countdown in HTML you must add countdown class to container and in that container you need to have containers with following class:

Images

<img ut:src="{{imagePath}}" />

You can attach images to your template. Just add them to you template folder and use relative path.

You can also use image as parameters. Just use attribute evaluation ut:src={{imagePath}} and you are done.

thumbnail.png

Thumbnail is a small, visual representation of the template. It can bee anything, from screenshot to dedicated artwork.

Requirement:

Rendering

This template:

<html>
<head>
  <style>
    h2 {
      background-color: {{bg-color}};
    }
  </style>
</head>
<body>
  <h2 ut:style="font-size: {{headerFontSize}}px;" data-html-friendly="true">{{header}}</h2>
  <form>
    <input type="text" name="name" />
    <input type="email" name="email" />
    <input type="submit" ut:text="{{submitText}}"/>
  </form>
  <script src="https://js.trustisto.com/socialproof_succker.js"></script>
</body>
</html>

with this request

GET /template_folder/
       ?id=1
       &locale=en
       &bg-color=white
       &headerFontSize=12
       &header=Hello
       &submitText=Send

will render to this:

<html>
<head>
  <style>
    h2 {
      background-color: white;
    }
  </style>
</head>
<body>
  <h2 ut:style="font-size: 12px;" data-html-friendly="true">Hello</h2>
  <form>
    <input type="text" name="name" />
    <input type="email" name="email" />
    <input type="submit" text="Send"/>
  </form>
  <script src="https://js.trustisto.com/socialproof_succker.js"></script>
</body>
</html>

When we render a template, we call index.html file via HTTP or HTTPS (secure) GET request with query params:

All parameters ex. {{title}} will be replaced (evaluated) by value from (in order):

Testing

To test template you should open it via some kind of webserver and add following query parameters

All default parameters from manifest in selected locale (or from en locale) will be loaded into template.

If you are using VisualStudio Code you can use this LiveServer extension

For checking template in proper size (width x height), please use Chrome Inspector and mobile devise simulator.

Samples

We have prepared you few sample templates:

FAQ

How to create a loading bar?

When rendering a template I see handlebars {{...}} for very short period of time. Can we create a loading bar and show template after all parameters will be evaluated?

Answers

<body>
    <div style="display: none;" ut:style="display:flex;">
      <!-- content -->
    </div>
    <div style="display:flex;" ut:style="display:none;" >
      Loading...
    </div>
    <script src="http://js.socialproof.local/socialproof_succker.js"></script>
</body>

Of course. The easiest way is to use built-in feature of evaluating attributes. For example ut:style will overwrite style when template will be rendered. So you can use it to show/hide content and loading message.

js