Admin login Smartico.ai TheAffiliatePlatform.com

🕸️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.

Visit our expo page to explore examples of already created UI Widgets:

https://expo.smartico.ai/ui_widgets/dp_ui_widgets

Usage context and types of widgets

UI widgets have two main usage contexts:

  • Website - they can be used on your website, rendered as an iframe.

  • Communication - they can be used inside mail/popup creatives as static HTML with dynamic content generated for a particular user.

Editing the widget types requires knowledge of HTML, Liquid HTML, and CSS. However, some components, such as Title, Message, CTA button text, and CTA button action, are located at the top of the HTML editor in a section called <!--Static Content-- > and can be easily edited.

Smartico provides UI widgets that support the following areas:

  1. Badges earned recently - Create a widget to display recently earned badges by the user within a defined period. By default, it shows badges completed this month. Other options include badges completed this week or today. If no badges are completed during the selected period, a message will appear: "You haven't completed any badges this month".

You can change the period in the Liquid template inside the HTML editor to the following values only:

  • completed_this_month

  • completed_this_week

  • completed_today

The widget's title and button text are easily customizable. In the HTML editor, under the <!--Static Content-- > section, you can edit the title text, the message displayed if no badges are completed, the CTA button text, and the CTA action.

  1. Missions

  • Missions in Progress - Create a widget to display all the missions that are currently in progress for the user. If there are no missions in progress for the user, a message will appear: “You don't have any missions in progress”. You can edit the widget’s title, description, message if there are no missions in progress, and CTA buttons in the HTML editor, under the <!--Static Content-- > section.

  • Missions completed recently - Allows you to create a widget and display all recently completed missions by the user. By default, it shows missions completed this week. Other options include missions completed this month or today. If no missions are completed during the selected period, a message will appear: "You haven't completed any mission this week". You can edit the widget’s title, description, message if no missions are available, and CTA buttons in the HTML editor, under the <!--Static Content-- > section.

    The period can be changed in the Liquid template inside the HTML editor to the following values only:

    • completed_this_month

    • completed_this_week

    • completed_today

  1. Tournaments

  • Tournaments available - Create a widget with all the available tournaments for the user. If there are no available tournaments for the user, a message will appear: “You don't have any tournaments available". You can edit the widget’s title, description, message when there are no available tournaments, and CTA buttons in the HTML editor, under the <!--Static Content-- > section.

  • Tournaments, one specific - Create a widget with the most recent (last created) tournament available for the user. You can edit the widget’s title, description, and CTA buttons in the HTML editor, under the <!--Static Content-- > section.

  1. Leaderboards - Create a widget with the top players in the Leaderboard. You can edit the widget’s title, description, and CTA buttons in the HTML editor, under the <!--Static Content-- > section.

  1. Mini-games with spins - Create a widget showcasing all mini-games where the user has available spins or attempts. You can edit the widget’s title, description, and CTA buttons in the HTML editor, under the <!--Static Content-- > section.

  1. Store

  • Store items for Current balance - Create a widget with all the items that the user can afford to buy from the Store. The widget displays the user's current balance and item prices. If no items are available, a message will appear: "No items available for purchase". You can edit the widget’s title, the “No items available for purchase” message, and CTA buttons in the HTML editor, under the <!--Static Content-- > section.

  • Store items History - Create a widget that shows all items purchased by the user within a specific period. You can select from three periods: today, this week, or this month. The default period is set to this week. If no items were bought during the specified period, a message will appear: “You haven't bought anything this week". You can edit the widget’s title, the “You haven't bought anything this week” message, and CTA buttons in the HTML editor, under the <!--Static Content-- > section.

    The period can be changed in the Liquid template inside the HTML editor to the following values only:

    • completed_this_month

    • completed_this_week

    • completed_today

  1. Levels list - Create a widget that shows all the completed levels and the current level for the user. You can edit the widget’s title and CTA button in the HTML editor, under the <!--Static Content-- > section.

  1. Inbox unread - Create a widget that shows all the unread messages for the user. In case there is no unread message a message will appear: "You have no unread messages". You can edit the widget’s title, description, the “You have no unread messages” message, and CTA buttons in the HTML editor, under the <!--Static Content-- > section.

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

  • Show a list of recently completed Badges for the user on your website.

  • Show a list of the top 5 players for the weekly leaderboard.

  • Show a list of the mini-games where the user has available spins or attempts.

  • Build a mail campaign, sending a list of items in the store that a particular user can afford to purchase.

  • Build a Journey campaign that sends a list of all the completed missions by the user for the current month.

  • During a specific tournament period, send a mail focusing on the Tournament Lobby and all the rules and details.

Managing UI Widgets

UI Widgets can be managed in the Tools tab in the Smartico BackOffice.

To create a new UI widget, you need to have knowledge of Liquid HTML, 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 (inline) and keep them as simple as possible due to the limitations of different mail clients.

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.

We are using a Liquid template engine for rendering UI based on your template. This template engine provides powerful possibilities to build a rich UI. You can refer to https://shopify.dev/docs/api/liquid for more details about using the engine.

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.

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 Tools tab -> Translation \ Values section

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


<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:

◾Override translations on Label/Brand Level

Widget Caching

All the widgets are personalized for the user who is accessing them.

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

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.

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:

_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. 

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

You can also check an example of using JavaScript on our demo page https://demo.smartico.ai/tests/landing-demo-inline-w.html

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 the special tag to embed it in the HTML of the mail resource. The tag is located in the UI Widget template in the BO and can be easily copied from there and pasted into the HTML of the mail resource.

Usage Limits

Widget 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.

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

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.

Last updated