> 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/tools-and-guides/custom-fields-attributes.md). # Custom fields/attributes Smartico allows you to extend any gamification element with **custom fields**, enabling you to add additional data that enhances your custom UI. ## What Are Custom Fields? Custom fields are **user-defined attributes** that can be attached to various gamification and communication elements, such as Tournaments, Missions, Badges, Levels, Mini-Games, Store Items and Inbox. These fields are **not used** by Smartico’s internal logic or the default Gamification widget, but they are available for use in custom UIs built with Smartico APIs. For player-level custom attributes used in segmentation and message personalization tags, see [User markers (tags)](/welcome/products/tools-and-guides/user-markers-tags.md). ### Example Use Case Suppose you want to classify tournaments as **VIP** or **Regular**. You can add a custom field to a Tournament to store this information and then use it in your **own UI** to visually distinguish VIP tournaments. Another example can be seen on our **Expo page -**

Custom levels UI with additional fields/attributes

By default, player levels only include: * Name * Description * Image * Progress information

Default attributes of levels

However, many casino and sportsbook operators associate player levels with perks such as **cashback percentages, rakeback, or VIP status**. To showcase this, we added custom fields like: * **Cashback (%)** * **Monthly Rakeback (%)** * **VIP Club Membership**

Custom attributes

These fields are defined by the **operator in Smartico BackOffice**, and their values are fetched via the **Smartico API** to display them in a custom UI. ### Technical Details #### Defining Custom Fields Custom fields can be set up in the following gamification elements: * [Tournaments](/welcome/products/gamification-basics/tournaments.md) * [Jackpots](/welcome/products/gamification-basics/jackpots.md) * [Raffles](/welcome/products/gamification-basics/raffles.md) and raffle prizes * [Levels](/welcome/products/gamification-basics/levels.md) * [Missions](/welcome/products/gamification-basics/missions.md) & [Badges](/welcome/products/gamification-basics/badges.md) * [Mini-Game templates](/welcome/products/mini-games/game-template-setup.md) and mini-game prizes * [Store Items](/welcome/products/gamification-basics/marketplace.md) Custom fields can be set up in the following communication resources: * [Inbox](/welcome/products/crm-automation/communication-channels/inbox.md) {% hint style="warning" %} The definition of custom fields is managed by Smartico personnel.\ You will need to fill out the JIRA request by specifying the fields you would like to see for the\ required gamification blocks, and the support team will make the necessary configurations. As soon as the configurations are applied, you will see fields available for editing on the screens of gamification blocks (such as tournaments, levels, etc.).\ \ Note: custom fields can be applied to the mentioned gamification blocks, and by request, they can be added to other Gamification blocks. Custom fields **can** be applied only to the Inbox from the communication resources, while all others (SMS, Push, Email, and Popups) **cannot**. Although you can explore the [Custom IM ](/welcome/technical-guides/communication-gateways/secured-messaging-gateways-email-sms-im.md#custom-im-via-api-supplied-by-customer)concept implementation, which is flexible in terms of defining custom fields. {% endhint %} ### Fallback and Translation Behavior * **Free-form fallback:** When no structured schema is configured for an entity type, the Back-Office provides a single free-form text input where operators can store raw text or custom JSON strings. The same text input is shown when the saved value is not a JSON object or has a key that the schema does not define. * **Multi-language support:** Fields configured with `"translatable": true` automatically display language-specific tabs in the Back-Office, allowing different localized values per brand language. Custom fields are defined using **JSON format**. Below is an example: ```json [ { "name": "cashback", "field": "int", "label": "Cashback, %", "required": false }, { "name": "rakeback", "field": "int", "label": "Monthly Rakeback, %", "required": false }, { "name": "has_vip_club", "field": "bool", "label": "VIP Club", "required": true }, { "name": "reward", "field": "text", "label": "Reward", "required": false, "translatable": true }, { "name": "image_inactive", "field": "image", "label": "Image (Inactive)", "required": false }, { "name": "image_active", "field": "image", "label": "Image (Active)", "required": false } ] ``` #### The scheme definition ```typescript interface DynamicSchemaField { // type of the field field: 'text' | 'textarea' | 'number' | 'int' | 'float' | 'multi-currency' | 'options-single' | 'options-multi' | 'bool' | 'image' | 'timestamp' | 'date-range' | 'json'; // internal name of the field name: string; // name of the field in the BackOffice label: string; // additional explanation that will be visible in the backoffice hint?: string; // if the value is required required?: boolean; // if the field is multi-lingual, it will show multiple fields for different languages translatable?: boolean; // default value default?: any; // set of the options for the options-single and options-multi options?: { id: string; name: string }[]; // max value for numbers max?: number; // min value for numbers min?: number; } ``` #### Accessing Custom Field Data via API Once defined, you can access custom field values from the API like this: ```javascript _smartico.api.getLevels().then((result) => { console.log(result[0].custom_data.cashback); }); ``` This will fetch the **cashback percentage** assigned to the level and allow you to display it in your custom UI. *** By leveraging custom fields, you can **enhance user engagement** and **personalize** the gamification experience to better suit your needs. 🚀 ## Frequently Asked Questions (FAQ) ### What is the difference between gamification custom fields and user custom properties? Gamification custom fields are metadata attributes attached to gamification elements (such as levels, tournaments, and missions) to provide extra information for your custom front-end UI. In contrast, user custom properties store attributes on individual player profiles, which are used for segment rules, marketing automation triggers, and personalization tags in communications (such as first name or account attributes). ### How is custom data parsed by the Smartico SDK? When custom field values are stored as structured JSON objects, the Smartico JavaScript SDK automatically parses them into native JavaScript objects upon retrieval, making properties accessible directly (for example, `result[0].custom_data.cashback`). If raw text is stored, the SDK returns the unmodified string. ### Can custom fields trigger automated campaign rewards? No. Custom fields are intended exclusively for front-end presentation and custom UI rendering. To deliver bonuses or perks associated with gamification actions (such as leveling up), configure an automated campaign triggered by the corresponding event. --- # 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/tools-and-guides/custom-fields-attributes.md?ask=&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.