> 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/products/gamification-basics/lootbox-2.0.md).

# Lootbox 2.0

### Overview

The Lootbox is a game that offers daily rewards to players. The process is simple: players open the game daily, revealing and getting their reward. Prizes are customizable and can vary daily, including options like points, bonuses, mini-game attempts, tangible items, and more.

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-efea8de118b415d0637e5361b6249f48ea68ca3b%2Flootbox%20with%20the%20new%20changes.png?alt=media" alt=""><figcaption></figcaption></figure>

The lootbox comes with 2 different layouts - Cards and Map. With the map Lootbox layout, you can easily create a themed Advent Calendar for Christmas, Easter, or other occasions.

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-2be74ea46ffec1f7f3e3fccfccd1bcfbded09ce1%2Fmap%20email%20image%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

### Lootbox Setup

The Lootbox game must be assigned to a Custom Section, during the Lootbox setup wizard, you can set the menu image that will be displayed in the Gamification Widget. Once you click ‘Create,’ a Custom Section with the same name as the Lootbox will be automatically generated and linked to it, saving you time and effort.

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-2cb82c7962f512800bbc62452fedc492f3a07ed6%2FScreenshot_73.png?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-65c54eb4c352ee617e6415ee0ac0bf687c9cbff8%2FScreenshot_10.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}

* Each Custom Section can contain only one Lootbox game, but you can create multiple Custom Sections.
  {% endhint %}

Start by selecting the schedule and the layout of the Lootbox you want to create. Based on the schedule and duration set in the wizard, the game’s prizes will be generated automatically. You can then customize the game and the prizes by selecting prize types, adding images, updating descriptions, and more.

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-6e70bc8c0f45f3de4e9f299a15765888a57ba1e0%2FLootbox%20Mechanics%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

### How to Create a Lootbox

The Lootbox mini-game can be created in the BO under the Retention Games section.

1. Click the ‘Create’ button and set a schedule for your Lootbox. You can choose from two schedule types:
   1. **Weekdays** (Monday to Sunday): Use this option for a recurring Lootbox on specific days of the week. The start time is always midnight, and you can select a time zone to align each day with your local midnight. For example, set up a Lootbox to run only on weekdays, Monday to Friday.
   2. **Calendar Days:** Use this option for specific calendar dates. The start time is also midnight, with an adjustable time zone. For example, create a Christmas Advent Calendar running from December 1st to December 25th.

{% hint style="warning" %}
The start time of the Lootbox is by default calculated from midnight UTC.

To make the Lootbox start at midnight in your desired time zone, you can select a time zone from the 'Timezone for days boundaries' setting.
{% endhint %}

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-a55188318a4e3acbe2e1050618cb802b3caa50e5%2FScreenshot_12.png?alt=media" alt=""><figcaption></figcaption></figure>

2. Select the layout of the Lootbox
   1. **Cards** - in this layout, prizes are hidden behind cards arranged in a horizontal row. Players flip each card to reveal their rewards
   2. **Map** - this layout is used for creating an Advent Calendar for a holiday-themed experience. The prizes are hidden in a gift box that pops up with a festive animation and reveals the reward.

<div><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-93aa810240fe3ec81e3a0b94b7fea8b918044ec4%2FScreenshot_13.png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-7edc4e226c3a372ecc9233ffe741460096144d3b%2FScreenshot_14.png?alt=media" alt=""><figcaption></figcaption></figure></div>

3. Select the **‘Timezone for days boundaries’** - The Lootbox days always start at midnight. You can choose the time zone to ensure each day aligns with your local midnight. Here are the available options:

   * **Calendar days, user time zone** - When selected, prizes expire at midnight in each user’s local time zone.
   * **Calendar days** - You select a specific time zone (for example, UTC+3 or UTC−5). Prizes will then expire at midnight in the selected time zone, the same for all users.

   <figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-ffbd8d72660aeb451cdf59efcb1bd103baf97495%2Fimage.png?alt=media&amp;token=3fded3b7-9a01-4cc7-821a-cbfe21ce8260" alt=""><figcaption><p>BO: Lootbox creation wizard - 'Timezone for days boundaries'<br></p></figcaption></figure>
4. After creating the game template, you can begin customizing the game:
   1. Choose a Name
   2. Select a Skin
   3. Set Visibility: Define who can see the game
   4. Configure Game UI: Set the game rules, add a promo image and text, and customize other display elements.
   5. Select the Custom Section where the Lootbox game will be displayed

{% hint style="info" %}
For the Horizontal layout of the Lootbox the ‘Promo text’ will be displayed under the title on the UI.

<img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-a06add62ee94b04a1e9e1e16fbd0e94721d3f8b5%2FScreenshot_11.png?alt=media" alt="" data-size="original">
{% endhint %}

5. Customize the Prizes - The number of prizes will be automatically generated based on the selected schedule when the game is created.
   1. Select the prize type
   2. Enter Prize name
   3. Add Prize image - ⚠️ It is recommended to use square images ⚠️
   4. Select winning message

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-4a8deb9cb8f6f376bd5ad9470bc858b62ab1afaa%2FScreenshot_15.png?alt=media" alt=""><figcaption></figcaption></figure>

### Lootbox Skinning

To create a custom skin for the Lootbox 2.0, you can use the ‘Mini-games skin editor’, following the same approach that is used for mini-games. Here are the main steps:

* Go to the Mini-games skin editor in the BO
* Select the ‘Lootbox’ type from the creation wizard
* Enter the name of the skin
* Choose the layout - Cards or Map
* Upload the package with the images
* You can override the CSS if you want to introduce some UI changes
* Save the skin

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-585c46bb1fae976a754f40ccaf316ad7a825fecd%2FScreenshot_8.png?alt=media" alt=""><figcaption></figcaption></figure>

<mark style="color:purple;">You can find the existing packages below and create a custom one:</mark>

{% embed url="<https://help.smartico.ai/welcome/products/mini-games/custom-skins-for-mini-games/lootbox-2.0-skins>" %}

{% hint style="warning" %}
When selecting a skin for the Map layout (25 and 31 days) in the BO game template, you may need to manually adjust the positions of some prizes. The simplest way to handle this is by copying the prizes from the skin editor and pasting them directly into the game template.
{% endhint %}

Please follow these guidelines when creating a Custom Lootbox Map skin:

1. For all skins (7, 14, 25, 31 days):
   1. <mark style="color:green;">'game-bg</mark><mark style="color:blue;">'</mark> and <mark style="color:green;">'game-bg-mobile'</mark> images should be less than <mark style="color:orange;">900kb</mark>
2. For all skins (7, 14, 25, 31 days):
   1. <mark style="color:green;">'game-bg'</mark> and <mark style="color:green;">'game-bg-mobile'</mark> images should be in <mark style="color:blue;">**JPEG**</mark> format
3. For 7 days skin:
   1. The <mark style="color:green;">'game-bg'</mark> image should be exactly <mark style="color:orange;">1835x1284</mark>
   2. The <mark style="color:green;">'game-bg-mobile'</mark> image should be exactly <mark style="color:orange;">527x1072</mark>
4. For 14 days skin:
   1. The <mark style="color:green;">'game-bg'</mark> image should be exactly <mark style="color:orange;">1835x2193</mark>
   2. The <mark style="color:green;">'game-bg-mobile'</mark> image should be exactly <mark style="color:orange;">527x1622</mark>
5. For 25 and 31 days skin:
   1. The <mark style="color:green;">'game-bg'</mark> image should be exactly <mark style="color:orange;">1835x3895</mark>
   2. The <mark style="color:green;">'game-bg-mobile'</mark> image should be exactly <mark style="color:orange;">527x3260</mark>

{% hint style="warning" %}
We can provide a template for Lootbox 2.0 skins upon request.

Please note that any images exported from the template must be compressed before uploading them to the BO. You can use [\[this link\]](https://tinypng.com/) to compress your images.

For further assistance, please contact your Customer Success Manager
{% endhint %}

If you want to introduce more or less than the pre-defined prizes in the map layout you need to adjust the positions of the prizes in the CSS editor in the skin or in the game template. The maximum amount of days that can be added is 31.

{% hint style="warning" %}
Please note that you must use '!important' when adjusting CSS on the game template and skin levels.
{% endhint %}

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-b6a693568b7df4878b5bc8b7c2540ec79beaee99%2Fimage%20(6)%20(6).png?alt=media" alt=""><figcaption></figcaption></figure>

### Lootbox Specifics

* The Lootbox game should be assigned to a Custom Section.
* Each prize is linked to a specific date or day in the BO
* Each prize is created by default with ‘Surchage’ enabled and ‘Stock items = 0’, this means that the prize pool will be infinite and the prize cannot run out of stock.
* The images for the prizes should be square (example: 512x512).
* The prizes in the loot box can be won by the players only once in 24 hours.
* If a player does not play the game in 24 hours, the prize for the day will be marked as missed and cannot be won.
* Lootbox Cards - players can reopen the winning pop-up by clicking on an already opened card, allowing them to view the winning message and action buttons again.

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-93e3b00ccc24a7a9b13c36e22c2664fcb936570e%2FScreenshot_16.png?alt=media" alt=""><figcaption></figcaption></figure>

### Missions as prize type

In Lootbox 2.0, you can include missions as a prize type. When a player opens the daily box, they’ll receive a mission, and upon completing it, they’ll earn the associated reward.

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-f220e9145241fb4a0cfe7b02e5dc51fe9692e811%2FScreenshot_45.png?alt=media" alt=""><figcaption></figcaption></figure>

This mission's prize type can be configured in the BO under the Prizes tab. Note that only 'Featured Manually' missions can be selected as prizes.

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-dc23ab869e4a51636d7746f9dae0acbf56ce5e62%2Fimage%20(10).png?alt=media" alt=""><figcaption></figcaption></figure>

### Multiple prizes per day

You can assign multiple prizes per day in Lootbox 2.0. This feature works with both layouts - Cards and Map - and applies to both scheduling options: Weekdays and Calendar Days.

{% hint style="info" %}
For Calendar Days, ensure the date range for the prizes is exactly one day (e.g., Start Date: 10.10.2024, End Date: 10.10.2024).
{% endhint %}

<div><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-29f1f11edddcb741a2afa19947829e327e28c817%2FScreenshot_47.png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-08e428c47af09199cd0cb0d46f753ac843faa0b9%2FScreenshot_48.png?alt=media" alt=""><figcaption></figcaption></figure></div>

When multiple prizes are assigned to the same day, the system does not simply select one at random with equal probability. Instead, it first determines which prizes the player is eligible to win and then calculates the winning probability of each eligible prize based on its remaining stock.

1. **Eligibility Checks**

Before each draw, the system evaluates the following criteria for every prize assigned to that day:

* **Player Segment (Who can win this prize):** Determines whether the player belongs to a segment eligible for the prize, such as VIPs, new players, or high depositors.
* **Additional Rule Conditions:** Checks any configured conditions, such as minimum deposit amounts, registration country, or player level.
* **Prize Availability Window:** Checks whether the prize is currently available based on the configured date, time, and template time zone.

Prizes the player is not eligible for are excluded from that player's draw pool.

2. **How the Winning Prize Is Selected?**

After determining the eligible prizes, the system calculates the winning probability of each prize based on its remaining stock:

* **Stock-Based Probability:** A prize's probability is calculated as its remaining stock divided by the total remaining stock of all eligible prizes for that day.
* **Real-Time Stock Updates:** When a prize is won, its remaining stock decreases by 1.
* **Dynamic Probabilities:** The probabilities of the remaining eligible prizes are recalculated after each win as their stock changes.

3. **What Happens When Stock Runs Out?**

If all limited-stock prize pools for a day reach 0, the system activates the Surcharge fallback. This allows players to continue opening the box without encountering an empty-pool error. The configured Surcharge prize is not limited by the original prize stock, allowing the system to continue providing a reward or consolation message.

4. **Can I Have a Random Distribution?**

Yes, but the distribution is weighted by the remaining stock of each eligible prize rather than being an equal-probability random draw.

For example, if three prizes are available to the same player with stocks of 100, 50, and 10, their initial probabilities are:

* Prize 1: 100 / 160 = 62.5%
* Prize 2: 50 / 160 = 31.25%
* Prize 3: 10 / 160 = 6.25%

The system randomly selects one of the eligible prizes using these probabilities. As prizes are won and their stock decreases, the probabilities are recalculated dynamically.

If you want equal random chances, assign the same stock to each eligible prize. For example, three prizes with 100 units each will initially have a 33.33% probability each.

{% hint style="info" %}
Player eligibility determines which prizes can be won; remaining stock determines the probability of each eligible prize. The Surcharge provides a fallback once all limited stock for the day has been exhausted.
{% endhint %}

<details>

<summary><strong>Practical Examples:</strong></summary>

**Example 1: Segmented Daily Rewards**

**Goal:** Give VIPs a high-value reward and other players a standard reward on Day 1.

**Configuration:**

* Surcharge is enabled for both prizes.

| Prize   | Reward         | Eligible Players  | Stock  |
| ------- | -------------- | ----------------- | ------ |
| Prize A | 100 Free Spins | VIP Segment       | 10 000 |
| Prize B | 10 Free Spins  | All other players | 10 000 |

**Outcome:**

* **VIP players:** Prize B is excluded, so Prize A is selected with 100% probability.
* **Non-VIP players:** Prize A is excluded, so Prize B is selected with 100% probability.

Because each player group is eligible for only one prize, there is no random selection between the two prizes.

**Example 2: Mystery Rarity Drop**

**Goal:** Give every player a mystery box on Day 15, with a chance to win a rare jackpot.

**Configuration:**

| Prize   | Reward            | Eligible Players | Stock |
| ------- | ----------------- | ---------------- | ----- |
| Prize A | 500 Coins (Gold)  | All Players      | 50    |
| Prize B | 20 Coins (Bronze) | All Players      | 950   |

**Outcome:**

The total stock is 1,000 items, so the initial probabilities are:

* Gold: 50 / 1,000 = 5%
* Bronze: 950 / 1,000 = 95%

Each time a prize is won, its stock decreases by 1 and the probabilities are recalculated. Once all Gold rewards are depleted, Gold is removed from the draw pool and players can only receive Bronze, as long as Bronze stock remains.

**Example 3: Hybrid Rewards - Guaranteed VIP Prize and Mystery Drop for Other Players**\
\
**Goal:** Give VIPs a guaranteed cash bonus while allowing non-VIP players to participate in a weighted prize draw.\
**Configuration for Friday:**

| Prize   | Reward         | Eligible Players | Stock         |
| ------- | -------------- | ---------------- | ------------- |
| Prize 1 | VIP Cash Bonus | VIP Segment      | As configured |
| Prize 2 | 50 Free Spins  | Non-VIP Segment  | 100           |
| Prize 3 | 5 Free Spins   | Non-VIP Segment  | 900           |

**Outcome:**

* VIP players: Only Prize 1 is eligible, so they receive the VIP Cash Bonus with 100% probability.
* Non-VIP players: They are eligible for Prizes 2 and 3. Their initial probabilities are 10% for Prize 2 and 90% for Prize 3.

The probabilities for non-VIP players change as the available stock is depleted.

**Example 4: Equal Initial Probabilities**

**Goal:** Distribute three prizes with equal initial winning probabilities.

**Configuration:** Surcharge is enabled for all three prizes.

| Prize   | Reward         | Eligible Players | Stock |
| ------- | -------------- | ---------------- | ----- |
| Prize 1 | VIP Cash Bonus | All Players      | 100   |
| Prize 2 | 50 Free Spins  | All Players      | 100   |
| Prize 3 | 5 Free Spins   | All Players      | 900   |

**Outcome:**

The total stock is 300 items. Since all three prizes have the same stock, each initially has a 33.33% probability of being won.

Every time a prize is won, its remaining stock decreases by 1. The probabilities are then recalculated based on the updated stock, so they may no longer remain equal.

**What happens when all stock is depleted?**

Once all 300 items have been won, the Surcharge fallback activates. Since all three prizes have Surcharge enabled, the system randomly selects among the available Surcharge prizes with equal probability - 33.33% each - and continues doing so indefinitely.

</details>

### Prize Acknowledgment

You can configure Lootbox prizes to require players to claim them manually before they are issued. When this setting is enabled, the prize will only be awarded after the player clicks the 'Claim' button; otherwise, the prize will remain unissued.

<div><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-a42aa0ea0744f69b8d5867dcc6f0d27066cb196a%2FScreenshot_50.png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-199166e0568149c4b8dd6e957ccc66d9c628a988%2FScreenshot_49.png?alt=media" alt=""><figcaption></figcaption></figure></div>

This option can be found in the Prize Configuration screen under 'Type of Winning Message' and is labeled as 'Full message with acknowledge button.' In the 'Not Claimed Prizes' tab, you can view all unclaimed prizes. From this tab, you can also manually issue a prize to a specific player by clicking the 'Claim Manually' button. Only prizes that require acknowledgment will appear in the 'Not Claimed Prizes' tab.

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-4d46bc5dbdb7ced105858e3eddf9c9d3e0939810%2FScreenshot_52.png?alt=media" alt=""><figcaption></figcaption></figure>

### FAQ:

**Q: Is the lootbox available in standalone mode?**

**A:** Yes. You can use -> Example: \_smartico.dp('dp:gf\_section&<mark style="color:orange;">id=205</mark>\&standalone=true'); -> <mark style="color:orange;">id=205</mark> is the ID of the Custom section with the Lootbox.

<div align="left"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-a7272c5cca4a7c9957d3c33fc41fcca5e073a5a7%2Fimage.png?alt=media" alt="" width="375"><figcaption></figcaption></figure></div>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.smartico.ai/welcome/products/gamification-basics/lootbox-2.0.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
