> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/~/changes/B87CND5z8x8BAzJwmSVQ/products/ui-widgets.md).

# UI Widgets

Smartico provides UI widgets to create a powerful HTML-based user interface with custom styles that represent a gamification environment of specific users.

These widgets can be used on your website, rendered as an iframe, and organically composed in the context of your website. They can also be used inside mail communication as static HTML with dynamic content generated for a particular user.

<figure><img src="/files/Chj7d8oJ6GAl2KZ3Lf0m" alt=""><figcaption><p>Example of UI Widgets implementation for Missions, Avatars and Mini-games</p></figcaption></figure>

{% hint style="info" %}
Before going into details of UI Widgets management, you can check this demo page  - <https://demo.smartico.ai/tests/landing-demo-inline-w.html>&#x20;
{% endhint %}

## Usage context and types of widgets

UI widgets have two main usage contexts:

* Website - they can be used on your website, where they are rendered as an iframe.
* Communication - they can be used inside mail/popup creatives as static HTML with dynamic content generated for a particular user.

Smartico provides UI widgets that support the following areas:

* Missions
* Tournaments
* Leaderboards
* Mini-games
* Store
* Levels

Here are a few examples of how you can use UI widgets:

* Show a list of available missions for the user on your website.
* Show a list of the top 20 players for the weekly leaderboard.
* Show a list of the Mini-games that are available for the player.
* Build a mail campaign, sending a list of items in the store that a particular user can purchase.
* Build a Journey campaign, that sends a list of new missions every time the user completes a mission or upgrades to a new level.
* Every day during a tournament period, send a mail to the participants of the tournament with a leaderboard, positions of players, and scores they got.

## Managing UI Widgets

UI Widgets can be managed in the Gamification section in the Smartico BackOffice

<figure><img src="/files/uTxZAOKRmIomOPrxQXme" alt=""><figcaption><p>UI Widgets management interface</p></figcaption></figure>

To create a new UI widget, you need to have knowledge of HTML and CSS. If you are building a widget for your website, you can also use JavaScript to make it more interactive. In case the widget is going to be used in the mail templates, you should use only HTML and CSS and keep them as simple as possible due to the limitations of different mail clients.

<figure><img src="/files/19YJHZVaQLM1wIUTaCrh" alt=""><figcaption><p>Creating new UI Widget</p></figcaption></figure>

When creating a new UI widget, you need to choose a type of widget that represents the gamification area you want to visualize. Once you choose a widget type, you will see a default HTML/CSS template that gives an example of how to use underlying data.

{% hint style="info" %}
We are using a Liquid template engine for rendering UI based on your template. This template engine is providing powerful possibilities to build a rich UI. You can refer to <https://shopify.dev/docs/api/liquid> for more details about using the engine.
{% endhint %}

When building a UI Widget, you will need to focus on the four main areas:

* HTML template - is the place where you will put your HTML/CSS with the help of the Liquid template engine
* Source data for template preview - is the place of sample data that will be fed to your HTML template, or you can choose a real user in your label to see how the data will look on behalf of the user
* Preview area - will show you the results of applying “HTML template” to the date specified in the “Source data for template preview”
* Below the “Preview area”, you will find JavaScript code that will be needed to add to your website and a “tag” that can be used in the mail templates.&#x20;

### Translations

As part of the widget data, you have access to all translation keys that are used in the Smartico Gamification widget.

A full list of the keys is available in Smartico BackOffice in the Label \ Translation \ Values section

<figure><img src="/files/TJY1l8HGJWc8ZkVLisgu" alt=""><figcaption><p>Interface to manage translations key</p></figcaption></figure>

You can customize default translations provided by Smartico or can introduce custom keys that can be used in the widget.

Inside the Widget HTML template, you can access translation keys in the following way

```html

<a href="dp:gf_store&id={{shop_item.id}}&hide_main=true" class="button">{{tr.buyNow}}</a>

```

Note that during widget design in the BackOffice, you will see only English versions of strings.

The translations will be applied only in the final widget setup on the website or when sent as part of the mail template.

*Read more about how to override translations:*

{% content-ref url="/pages/7xiVjhWu4SeNViuU06rZ" %}
[Override translations on Label/Brand Level](/welcome/~/changes/B87CND5z8x8BAzJwmSVQ/products/general-concepts/override-translations-on-label-brand-level.md)
{% endcontent-ref %}

### Widget Caching

All the widgets are personalized for the user who is accessing them.&#x20;

When the widget is rendered for a specific user, the results of the rendered HTML can be cached for a specific period of time.&#x20;

During this time, if the user requests the Widget again, they will get the same, cached visual result, even though they may have changes in the list of missions or their progress.&#x20;

The minimum period of caching is 1 minute, but you can define it to be higher.

### Widget refresh period

When designing a widget for the website, you can specify a refresh period.

This is the period when the widget will automatically refresh without the need for any actions from the user's side.

## Placing UI Widgets on the website

When you are ready with your widget you can set it in the website using the JavaScript code that has the following format:

```javascript
_smartico.showWidget('ui-widget', { 
    iframe: 'target-frame-id', // 
    zoom: 1,
    height: 'auto',
    wuuid: '10/c9696b2c-c1a7-11ed-b3f8-06104d6e754b'
} );

/*
iframe element should specify the ID of DOM element where the widget will be loaded.
zoom - can be used to control the size of the element
height - can be set to “auto”, in this case, widget will be resized according to the content or to a specified height in the pixel
wuuid - is identifying the instance of your widget.
*/

```

Note that some UI Widgets can be targeted to a specific instance in the gamification environment. For example to visualize a tournament lobby of a specific tournament.

In such case, you will need to specify additional parameters for the ID, e.g.&#x20;

```javascript
_smartico.showWidget('ui-widget', { 
    iframe: 'target-frame-id', // 
    zoom: 1,
    height: 'auto',
    wuuid: '10/c9696b2c-c1a7-11ed-b3f8-06104d6e754b',
    id: 123
} );
```

{% hint style="info" %}
You can also check an example of using JavaScript on our demo page <https://demo.smartico.ai/tests/landing-demo-inline-w.html>&#x20;
{% endhint %}

## Using UI Widgets in the mail templates

If you are designing a widget that will be used for the mail templates, you need to take a special tag to embed it in the HTML of the mail resource.

<figure><img src="/files/TaE4Bqvb7GvulB5AsNSN" alt=""><figcaption><p>Placing UI Widget in the mail resource</p></figcaption></figure>

## Usage Limits

Widgets functionality is limited in two aspects:

* Number of non-cached renders of the content per month
* The rate per hour of non-cached renders

These limits are defined according to your tier of MAU users and set to have a balanced usage of Smartico eco-system.&#x20;

In order to follow the limits, we recommend setting a reasonable caching period for the widgets used on the websites.&#x20;

For the widgets used in the mail, consider limiting the target audience and the mail-sending rate that can be set on the “Scheduled campaign” setup screen.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.smartico.ai/welcome/~/changes/B87CND5z8x8BAzJwmSVQ/products/ui-widgets.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.