◼️Liquid Section

Overview

The Liquid Custom Section allows you to create fully customized layouts and content within the gamification widget using the Liquid templating language.

With this section type, you can:

• Build a personalized overview page.

• Display only the data you need (e.g., missions, tournaments, mini-games, store items).

• Choose from predefined templates or start from scratch with your own Liquid code.

In a nutshell, to build a Liquid template, you need to create HTML that looks like this:

<!-- 
  Missions array contains both missions and badges, 
  Here we filter missions only
-->



<div>
  <!-- Iterate over missions -->

  

</div>

In terms of setup, the Liquid Section works similarly to other custom section types; you can configure its name, icon, visibility period, and target user segment, just as you do for any other custom section.

You can start from one of the following templates:

• Overview Template – A general layout using Missions, Store Items, and Mini-Games.

• Missions Template – Focused on displaying and customizing mission content.

• Level Map Template – Used for building and styling a level map with position and background customization.

• Custom Template – A blank canvas where you build the section from scratch.

💡 These Templates serve as a starting point. You can modify them as needed.

To work effectively with Liquid-based templates, a solid understanding of HTML and CSS is required. Familiarity with JavaScript is also helpful. We also recommend reviewing the official Liquid documentation to gain a comprehensive understanding of the templating engine’s capabilities.

You can use the following gamification entities in your Liquid templates:

• Missions

• Store Items

• Tournaments

• Mini-Games

• Levels

• Jackpots

• Bonuses

• Leaderboards

• Badges

• And user profile data, including the number of points, gems, diamonds, nickname, avatar, number of unread inbox messages, and the user's current level

Important note: Ensure that you apply your brand styles by replacing all default colors, fonts, and visual elements.

How to Create a Liquid Custom Section

1. Create the Section

• Go to Custom Sections and select ‘Create Liquid Section’.

• The Core Setup works the same as in other section types.

1. Choose a Template

• In the Section Setup, select a predefined template or start with a blank custom template.

• In the Entity Data dropdown, choose which data types to include (e.g., missions, store items).

⚠️ If using a predefined template and adding more data types, you'll need to manually update the Liquid code to display the new data. ⚠️

1. Build the Content

   • Go to the Page Content tab to preview and edit the layout.

   • Choose a user to preview how data will appear.

4. Finalize

• Once your design is complete, save the section and enable it under Label Settings.

Templates

Overview Template

With the ‘Overview Template’, you can customize the overview screen by selecting which data to display (e.g., Locked Missions, Free-to-Play Mini-Games), adjusting visual elements such as text, colors, and chip shapes, and deciding what content to show or hide. The default data sources for this template are Missions, Store items, and Minigames; however, you can replace any of these with other data types, such as tournaments. For example, you can show Missions, Store items, and Tournaments.

Keep in mind that to expose mini-games in the overview, the mini-game must have a Promo image and promo text set.

Missions Template

Use the ‘Missions Template’ to build and personalize the Missions section by selecting specific missions to display, customizing mission card design (colors, shapes, layout), and modifying and configuring tabs.

Level Map Template

Use this template to design a visual Level Map. You can adjust the positions of the levels as needed, customize the colors, upload background images for both desktop and mobile devices, and tailor the level pop-up display. You can also hide the level name from the map or move the level name of the top, for example.

• Keep in mind that when uploading a background image for the map, you need to populate the correct aspect ratio of the uploaded image in the Liquid (for both desktop and mobile).

• The desktop image should be 800px wide, and the height is not limited, as end-users can scroll down to see levels. The mobile image should be 800px wide and at least 2000px high.

Puzzle Template

The Puzzle template lets you create a custom puzzle in which each piece is revealed as players complete specific badges. Each puzzle piece is actually a badge image. Once all required badges are completed, the full puzzle image is revealed.

Key details:

• The puzzle grid always displays 5 images per row.

• For best visual results, we recommend using a 5×5 grid.

• All images should be square.

• Each badge represents one puzzle piece, so badges and images must be prepared in advance.

Preparing Puzzle Images (Photoshop Guide)

Follow these steps to split your image into puzzle pieces using Photoshop:

1. Open the image you want to turn into a puzzle.

2. Go to View → Guides → New Guide Layout.

1. Set the number of columns and rows (columns must be 5).

1. Select the Slice Tool.

1. Click Slice from Guides to automatically create image slices.

1. Go to File → Export → Save for Web….

1. Choose the desired format and save the images.

After exporting:

• A folder named “images” will be created.

• Each image will be named after the original file, followed by _# to indicate its position in the grid.

Setting up the Puzzle

To configure the Puzzle template:

1. Create badges and assign each one a corresponding puzzle image.

2. Add a priority to each badge so you can control the image order and ensure the puzzle pieces are arranged correctly.

3. Create a Custom Section with type Badges.

4. Add all puzzle-related badges to this Custom Section.

5. Enable “Show only in Custom section” for these badges.

6. Create a Liquid Custom Section.

7. Select the Puzzle template.

   1. Enter the Custom Section ID that contains the puzzle badges.

{% assign target_section_id = 1234 %}

1. Activate the Liquid Custom Section.

Note: The Badge Custom Section itself does not need to be active.

Liquid Data Keys

Use these keys to access gamification data in your Liquid code:

Data Type	Name of object/array variable	Documentation about structure
For Missions	missions	https://github.com/smarticoai/public-api/blob/main/docs/api/interfaces/TMissionOrBadge.md
For Badges	badges	https://github.com/smarticoai/public-api/blob/main/docs/api/interfaces/TMissionOrBadge.md
Badge Categories * Badges categories become automatically available when Badges are selected as Liquid entity data.	badgeCategories	https://github.com/smarticoai/public-api/blob/main/docs/api/interfaces/TAchCategory.md
Store Items	storeItems	https://github.com/smarticoai/public-api/blob/main/docs/api/interfaces/TStoreItem.md
Store Categories * Store categories become automatically available when store items are selected as Liquid entity data.	storeCategories	https://github.com/smarticoai/public-api/blob/main/docs/api/interfaces/TStoreCategory.md
Tournaments	tournaments	https://github.com/smarticoai/public-api/blob/main/docs/api/interfaces/TTournament.md
Tournament Instance	singleTournament	https://github.com/smarticoai/public-api/blob/main/docs/api/interfaces/TTournamentDetailed.md
Mini-Games	miniGames	https://github.com/smarticoai/public-api/blob/main/docs/api/interfaces/TMiniGameTemplate.md
Levels	levels	https://github.com/smarticoai/public-api/blob/main/docs/api/interfaces/TLevel.md
Bonuses	bonuses	https://github.com/smarticoai/public-api/blob/main/docs/api/interfaces/TBonus.md
Jackpots	jackpots	https://github.com/smarticoai/public-api/blob/main/docs/api/interfaces/JackpotDetails.md
Raffles	raffles	https://github.com/smarticoai/public-api/blob/main/docs/api/interfaces/TRaffle.md
Raffle Instance	singleRaffle	https://github.com/smarticoai/public-api/blob/main/docs/api/interfaces/TRaffle.md

You can refer to the documentation for each data key to understand what kind of "properties" you have for each object.

For example, for "mission" we have id and name, and they can be used in the following way

<div>
  <!-- Iterate over missions -->
  {% for mission in missions %}
    <!-- Show mission name as a link that will trigger an overlay popup with details -->
    <div onclick="openMission({{ mission.id }})">
      {{ mission.name }}
    </div>
  {% endfor %}
</div>

User Info Access

User info is always available. Use the following to access balances:

Points   → {{ userInfo.ach_points_balance }}
Gems     → {{ userInfo.ach_gems_balance }}
Diamonds → {{ userInfo.ach_diamonds_balance }}

To Access the User info:

Username → {{ userInfo.public_username }}
Smartico User ID → {{ userInfo.userId }}
External User ID → {{ userInfo.extUserId }}
User Hash → {{ userInfo.user_hash }} 
Avatar image → {{ userInfo.avatar_url }}
Current level name → {{ userInfo.ach_level_current }}
Unread inbox count → {{ userInfo.core_inbox_unread_count }}
Current level image for user → {{ userInfo.currentLevel.level_public_meta.image_url }}
User's diamonds balance -> {{ userInfo.ach_diamonds_balance }}
User's gems balance -> {{ userInfo.ach_gems_balance }} 
User's current level ID (number) -> {{ userInfo.ach_level_current_id }}
User's current points balance -> {{ userInfo.ach_points_balance }} 
User's points collected ever -> {{ userInfo.ach_points_ever }} 
Unread count of user's inbox messages -> {{ userInfo.core_inbox_unread_count }}
Status of user's account -> {{ userInfo.core_is_test_account }} 
JS markers of user's profile -> {{ userInfo.core_public_tags }}
User's registration date -> {{ userInfo.core_registration_date }}
User's language -> {{ userInfo.core_user_language }}
User's wallet currency -> {{ userInfo.core_wallet_currency }}
User's country -> {{userInfo.user_country }}

Note: userInfo.user_hash is the value passed by the platform on the front-end, as explained in Protecting user identification on the public front-end

Examples

Avatar:

<div>
    <img class="user-avatar" src="{{userInfo.avatar_url}}" width="100px" height="auto"/>
  </div> 

Current level image:

<div>
    <img src="{{userInfo.currentLevel.level_public_meta.image_url}}" width="100px" height="100px"/>
  </div>

Functions

For each entity's data, you can use targeted functions to open an overlay popup with details of the entity or to be navigated to the page (such as tournaments):

• Missions: openMission({{ mission.id }})

Example: <div class="missions" onclick="openMission({{ mission.id }})">

• Badges: openBadge({{ badge.id }})

Example:  <div class="badges" onclick="openBadge({{ badge.id }})">

⚠️For Missions and Badges, you will need to specify the type:

{% assign missions = missions | where: "type", 'mission' %}
{% assign badges = badges | where: "type", 'badge' %}

• Store: openStore({{ item.id }})

Example: <div class="store-item" onclick="openStore({{ item.id }})">

• Levels: openLevel({{level.id}})

Example: <div class="levels" onclick="openLevel({{level.id}})">

• Bonuses: openBonus({{ bonus.bonus_id }})

Example: <div class="bonuses" onclick="openBonus({{ bonus.bonus_id }})">

• Tournaments: openTournament({{ tournament.instance_id}})

Example: <div class="tournament-card" onclick="openTournament({{ tournament.instance_id }})">

• Tournament Instance: tournamentOptIn({{ tournament.instance_id }})

{% assign tournament = singleTournament %}
{% assign user_registered = tournament.is_user_registered %}
<div 
      class="tour-reg-button {% if user_registered %}registered{% else %}not-registered{% endif %}" 
      onclick="tournamentOptIn({{ tournament.instance_id }})">
      {% if user_registered %}
        You are registered
      {% else %}
        Join tournament
      {% endif %}
    </div>

This allows you to show only one specific tournament and makes it easy to highlight only the tournament leaderboard, prize pool, or related games, or a combination of all of them.

How it works:

• Select ‘Tournament Instance’ – Choose the newly added entity data called ‘Tournament instance’.

• Select the Tournament – Once a tournament is selected, the system automatically chooses the appropriate run based on the status of the run:

  • Started: The highest priority run is selected.

  • Open for registration: If no run is in the 'Started' status, the run with the 'Open for registration' status will be displayed.

  • Last finished: If there are no Started or Open for registration runs, the last finished run is used.

  • Both Started and Open for registration exist: The Started run takes priority.

• Mini-games: openMiniGame({{ game.id }})

Example: <div class="mini-game-card" onclick="openMiniGame({{ game.id }})">

• Jackpots: openJackpot({{ jackpot.jp_template_id }})

Example: <div class="jackpot-card" onclick="openJackpot({{ jackpot.jp_template_id }})">

• Raffles: openRaffle({{ raffle.id }})

Example: <div class="raffles">
  {% assign myRaffles = raffles %}
  {% for r in myRaffles limit: 3 %}
    <div class="raffle-card" onclick="openRaffle({{ r.id }})">
      <div class="raffle-top" style="background-image: url({{ r.image_url }})">
      <div class="raffle-overlay"></div>
      <div class="raffle-texts">
      <div class="raffle-title">{{ r.name }}</div>
      </div>
    </div>
    </div>
  {% endfor %}
</div>

Show only specific Raffle:
{% assign section_raffles_123 = raffles | where: "custom_section_id", 123 %}

• Raffle Instance: raffleDrawOptIn({{ draw.id }})

Example: <div class="asset-header">Single Raffle</div>
{% assign raffle = singleRaffle %}
<div class="raffle">
  <div class="raffle-name">{{ raffle.name }}</div>
   <div class="raffle-image" style="background-image: url({{ raffle.image_url }})"></div>

  {% if raffle.description %}
    <div class="raffle-description">{{ raffle.description }}</div>
  {% endif %}

  <div class="raffle-tickets">Max tickets count: {{ raffle.max_tickets_count }}</div>

  {% assign sorted_draws = raffle.draws | sort: "execution_ts" %}

  <div class="raffle-draws">Raffle draws</div>
  <div class="draws-containers">
    {% for draw in sorted_draws %}
   {% assign user_optedIn = draw.user_opted_in %}

      <div class="draw-container">
        <div class="draw-image" style="background-image: url({{ draw.image_url }})"></div>
        <div class="draw-name">{{ draw.name }}</div>
        {% if draw.requires_optin %}
         <div 
            class="draw-btn {% if user_optedIn %}opted{% else %}not-opted{% endif %}" 
            onclick="raffleDrawOptIn({{ draw.id }})">
            {% if user_optedIn %}
              Opted in
              {% else %}
              Opt in
              {% endif%}
          </div>
          {% endif%}
      </div>
    {% endfor %}
  </div>
</div>

Liquid Params

Liquid Params is a parameter for deep links used in Liquid Custom Sections. This allows you to pass custom parameters via deep links and access them directly inside your Liquid code.

Example of deep-link using liquidParams:

• dp:gf_section&id=123&liquidParams={"instance_id":21,"register":true}

This deep link opens the tournament with ID 21 and automatically registers the user.

You can find more deep link examples in the deep link documentation.

The liquidParams object is parsed and exposed inside the Liquid custom section. It is available in raw Liquid data -> ‘Show data source’ and in the liquid code. You can pass different parameters such as "instance_id": 704519, "section": "players" .

Use the following script in your Liquid code to read and apply these parameters:

• For newly created Liquid Custom Sections, this script is added automatically, so no action is needed.

• For existing Liquid Custom Sections, you’ll need to add the script manually to the Liquid code.

<script>
document.addEventListener('DOMContentLoaded', function () {
  window.liquidParams = {{ liquidParams | json }}
  const liquidParams = window.liquidParams;

  if (liquidParams) {
    const { mission_id, optIn, instance_id, future, register, section, category, tournament_id } = liquidParams;
    if (mission_id) {
      openMission(mission_id);
    }
    if (mission_id && optIn === true) {
      openMission(mission_id, { "optIn": optIn });
    }
    if (instance_id && !register && !section) {
      openTournament(instance_id);
    }
    if (instance_id && register === true) {
      openTournament(instance_id, { "register": register });
    }
    if (instance_id && section) {
      openTournament(instance_id, { "section": section });
    }
    if (category) {
      openTournaments({ "category": category });
    }
    if (tournament_id && !future) {
       openTournaments({ "tournament_id": tournament_id })
    }
    if (tournament_id && future === true) {
      openTournaments({ "tournament_id": tournament_id, "future": future })
    }
  }
});
</script>

Deep link usage:

You can trigger deep links using the dp() function in HTML elements like buttons:

<button onclick="dp('dp:gf_store')">Open Store</button>

You can see all deep links here

Client action usage in the Liquid section:

You can configure a 'Client action' event to trigger, for example, an automation rule and give points/games to the players.

clientAction(actionValue, payload)
where actionValue is a string (name of the action)
payload - object, you can pass anything you want here

Example in HTML:
 <div class="test-button" onclick="clientAction('TEST_LIQUID_ACTION')">Click here</div>

Read more about 'Client action' event here

Smartico API usage in the Liquid section:

You can access the Smartico API directly within Liquid Custom Sections. This allows you to build a fully customized UI for gamification features, including mini-games, missions, badges, tournaments, and in-store items. By leveraging the API within your Liquid code, you have complete creative control over how these features are presented and integrated into your site.

API documentation: https://github.com/smarticoai/public-api/blob/main/docs/api/classes/WSAPI.md

try {
      const miniGames = await _smartico.api.getMiniGames();
      console.log('MiniGames:', miniGames);

      const profile = await _smartico.api.getUserProfile();
      console.log('Profile:', profile);

      const tournaments = await _smartico.api.getTournamentsList();
      console.log('Tournaments:', tournaments);

      const tournamentInstanceInfo = await _smartico.api.getTournamentInstanceInfo(707553);
      console.log("tournamentInstanceInfo", tournamentInstanceInfo);

      const storeItemsHistory = await _smartico.api.getStorePurchasedItems({limit: 20, offset: 0});
      console.log("storeItemsHistory", storeItemsHistory);

       const miniGamesHistory = await _smartico.api.getMiniGamesHistory({limit: 20, offset: 0});
      console.log("miniGamesHistory", miniGamesHistory);
} catch (err) {
      console.error('API error:', err);
}