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

### 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 -** <https://expo.smartico.ai/widgets/api_custom_lvl_map>

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-2112608ff331e6d912cf6f0320dd830d06774d03%2Fimage.png?alt=media" alt="" width="563"><figcaption><p>Custom levels UI with additional fields/attributes</p></figcaption></figure>

By default, player levels only include:

* Name
* Description
* Image
* Progress information

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-5c8646953a7f7e7e25357243cf72cdc8a27ef0e6%2Fsmartico.ai%20%40%20EU4%202025-02-05%2018-59-39.png?alt=media" alt=""><figcaption><p>Default attributes of levels</p></figcaption></figure>

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

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-6193ebd645fa13eb5139d90530716986b7273111%2Fsmartico.ai%20%40%20EU4%202025-02-05%2019-00-21.png?alt=media" alt=""><figcaption><p>Custom attributes</p></figcaption></figure>

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
* Jackpots
* Raffles
* Levels
* Missions & Badges
* Mini-Game templates and mini-game prizes
* Store Items

Custom fields can be set up in the following communication resources:

* Inbox

{% 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 ](https://help.smartico.ai/welcome/technical-guides/secured-messaging-gateways-email-sms-im#custom-im-via-api-supplied-by-customer)concept implementation, which is flexible in terms of defining custom fields.
{% endhint %}

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' | 'int' | 'float' | 'options-single' | 'options-multi' | 'bool' | 'image' | 'timestamp';
    // 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?: bool;
    // if the field is multi-lingual, it will show multiple fields for different languages
    translatable?: bool;
    // 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
javascriptCopyEditsmartico.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. 🚀