index.html

This file is the 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 your 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:value="{{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 prepend attribute name with ut: ex. <img ut:src="{{imageURL}}" /> When value of a parameter will be known, name of the attribute would change: ut:src becomes src, ut:value becomes value and so on. Any attribute works this way; there is no special ut:text - to set the label of a submit button use ut:value, and for the text of other elements put the parameter inside the element, ex. <button>{{submitText}}</button>.

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:

• ut:hide-if="{{param}}" - if the value of the parameter is missing or falsy (empty, false, no, 0) it sets style="display: none;" on the element (the element’s own style is replaced)
• ut:delete-if="{{param}}" - similar to ut:hide-if, but the element is removed from DOM
• ut:show-when="{{otherParameterName, otherParameterValue, comparisonType}}" - keeps the element only when the parameter value meets the condition, otherwise the element is removed from DOM. comparisonType is one of equals (default), includes, greaterOrEqual, lessOrEqual (see showWhen in manifest.json)

Loops

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

Order

<div ut:order-parent="true">
  <div ut:order="{{imageOrder}}">...</div>
  <div ut:order="{{textOrder}}">...</div>
  <div ut:order="{{buttonOrder}}">...</div>
</div>

To let the user change the order of elements, put ut:order-parent on the container and ut:order="{{param}}" with a number parameter on every child element. The children are sorted by that number, from the lowest.

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.

Inline links

<a target="_blank" data-cta-inline="{{url}}">Read more</a>

data-cta-inline turns an <a> into a regular link to the given URL, which goes through Trustisto first, so the click is measured as engage. Use it when the link has to behave like a normal link, ex. open in a new tab with target="_blank".

CTA

<a ut:data-cta="{{param}}">Click me</a>
<a data-cta="redirect::https://myshop.com/promo">Go to promo</a>
<button data-cta="copy::SUMMER10">Copy the code</button>
<button data-cta="close::">No, thanks</button>

If you want to make Call To Action element, use the data-cta attribute on a button or <a> tag. Its value has the form type::value. With a parameter of type cta (see manifest.json) use ut:data-cta="{{param}}": the user picks the action in the template editor.

Types:

• redirect::URL - redirect to the URL
• redirectNewTab::URL - open the URL in a new tab
• copy::TEXT - copy the text to clipboard and show a “Copied to clipboard” message
• openPopup::ID - open the Trust Overlay with the given ID
• openTopbar::ID - open the Trust Bar with the given ID
• openMailClient::E-MAIL - open the user’s mail client with the given address
• close:: - close the template

A value without :: is treated as redirect. Each CTA except close is measured as engage (copy only on the first click). openPopup and openTopbar close the current template.

Engage and close

<button data-engage-close>Got it</button>

A click on an element with data-engage-close is measured as engage and closes the template.

To measure engage from your own script, call SPP.engage().

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)

• You should use <form> tag without action and method attributes
• Each input need to have name= attribute assigned to it
• For validating please use HTML required attribute
• You need to have default submit button
• Put elements with form-success and form-error classes inside the form, hidden by default. After submit the .form-success element is shown (display: flex), so it can hold a thank-you message.

<form>
  <input type="email" name="email" required />
  <input type="submit" ut:value="{{submitText}}" />
  <div class="form-success" style="display: none;">{{successMessage}}</div>
  <div class="form-error" style="display: none;">{{errorMessage}}</div>
</form>

After submit the template closes in 2.5 seconds, unless closeOnSubmit is false in manifest.json.

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:

• general consent, to communicate using specific channel ex. e-mail or phone,
• marketing consent, to have ability to send marketing content to specific user using specific channel

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

• general consent name="consent" and value true or false
• marketing consent name="marketing" and value true or false

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:

• days
• hours
• minutes
• seconds

The deadline (data-deadline) can be:

• a date, ex. 2026-12-31T23:59:59 - absolute deadline
• a number of seconds, ex. 3600 - relative deadline, counted from the moment the visitor sees the template for the first time
• daily HH:MM, ex. daily 18:00 - every day at this time

When the time passes, the countdown is replaced with data-timePassedMessage (if set) and every element with the data-countdown-disappear attribute is hidden.

To hide the days or hours when they reach zero, wrap each <span> in an element with the tile class, as in sample_countdown.zip.

Countdown in Mails

<img class="countdown-gif"
     ut:data-deadline="{{deadline}}"
     ut:data-width="{{countdownWidth}}"
     ut:data-height="{{countdownHeight}}" />

Mail clients don’t run JavaScript, so in Mail templates the countdown is an animated GIF. Add an <img> with the countdown-gif class: its src is set to the countdown GIF built from the data-* attributes:

• data-deadline - the deadline
• data-width, data-height - size in pixels (default: 400 × 200)
• data-background, data-color - background and digits color (default: #000000, #ffffff)
• data-font - font name (default: Bungee)
• data-locale - language of the labels (default: en)
• data-pass-text - text shown when the time has passed
• data-frames - number of frames, i.e. seconds of animation (default: 30)
• data-draw-numbers-background - true to draw a background behind the digits

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.

Context

<script>
  SPP.askForContext({ modules: ['client', 'basketValue'] }, function (context) {
    document.querySelector('.name').textContent = context.client.firstname || '';
  });
</script>

SPP.askForContext(contextParams, callback) asks the website for data about the current visitor. contextParams.modules is a list of:

• client - the saved client, as from SP.getClient()
• basket - the products in the basket
• basketValue - the basket value
• visit - the products the visitor has recently seen
• purchase - the products the visitor has recently bought

callback receives an object with the requested keys. The template already asks for the context it needs for its parameters, so you need this only for your own scripts.

Script API

socialproof_succker.js exposes window.SPP with:

• SPP.engage() - measure engage
• SPP.askForContext(contextParams, callback) - see Context
• SPP.manifest - the parsed manifest.json, available once the template is rendered
• SPP.log(message), SPP.warn(message), SPP.error(message) - log to the console with the template ID