# Clans & Clan Tournaments

The Clans product is a powerful social layer designed to transform individual gameplay into a community-driven experience. By allowing operators to group players into competitive clans, you can leverage group dynamics to boost retention, increase tournament activity, and create targeted segments for specific player bases. 

{% hint style="info" %}
**Note**: To ensure full control over your brand’s social ecosystem, all Clans are operator-managed. This means only Back Office users can initiate new Clans and define their parameters. 
{% endhint %}

## Implementation Guide

Before diving into the detailed configurations, follow these high-level steps to activate and test the Clan ecosystem on your label:

1. **Request Activation**: Submit a request to **Customer Support** to enable the Clan product for your specific label.
2. **Clan Creation**: Create your initial set of Clans, ensuring you maintain consistent user segmentation across them.
3. **Tournament Alignment**: Create at least one **Clan Tournament**. Ensure its visibility and registration segmentation matches the segments used for your Clans.
4. **Expose & Test**: Navigate to **Label Settings** to expose the Clan section in the Gamification (GF) widget. We recommend enabling this for **Test Users** first to verify your configuration and prize logic before going live.

With these basics covered, let’s dive deep into the specific setup process and the available functionalities.

## Clan setup

### General setup

* **Clan Name** - This name is both internal in BO and external for the gamification
* **Status:**
  * **Draft**: Initial state on creation (not visible to players)
  * **Active**: Live and joinable.
  * **Archived**: A final state, where no further changes or members are allowed.
* **Image** - The visual avatar representing the Clan across the platform.
* **Entry fee** - Define whether joining is Free or requires a specific cost (e.g., Points, Gems, or Diamonds). 
* **Capacity** - Set the maximum member limit. 
  * **Note**: You cannot set capacity lower than the current member count. 
* **Segmentation**:
  * **Who can see** - Visibility Segment of users who can see the Clan in their list.
  * **Who can join** - Eligibility Segment of users who are permitted to join

<div data-with-frame="true"><img src="/files/zixkAYt7lMR8oIfJ0Jly" alt="BO: Example of Clan setup"></div>

## Clan Tournaments setup

### General setup

When creating a new tournament, you must define the **Ranking Type**. This setting determines the fundamental structure of the competition and **cannot be changed once the tournament is created**:&#x20;

<div data-with-frame="true"><figure><img src="/files/npnuk3AV4wHe2HAXcexP" alt=""><figcaption></figcaption></figure></div>

* **Clans**: Users compete as a collective unit; scores are aggregated per Clan.
* **Individual Players**: The standard "every player for themselves" format.

{% hint style="info" %}
**Note**: All other tournament settings (duration, games, etc.) remain identical to standard setups.
{% endhint %}

<div data-with-frame="true"><img src="/files/zAROlEmpy7Kgv7Ii9PvH" alt="Gamification: The Clan board in a Clan Tournament along with the Prize pool"></div>

### Prize Pool setup

First, determine which **Clan Rank** placements (e.g., 1st through 3rd place Clans) will receive rewards. Then, configure how those prizes are distributed among the individual players within those winning Clans:

<div data-with-frame="true"><img src="/files/4PCQrVmgwakiHvb7plsC" alt="BO: Example of Prize setup for Clan Tournament"></div>

* **Fixed Prizes**: The same amount of prize (Bonus, Tangible item, etc.) is awarded to every user within a defined rank range.
  * *Example*: A "Laptop" prize for placements 1–3 means all three top contributors in the Clan receive a laptop.
* **Dynamic Prizes**: A prize pool (e.g. 1,000 points or \*currency) distributed among a range of users.
  * **Equally Split**: The pool is divided evenly.&#x20;
    * *Example*: 100 points for positions 1–4 = 25 points per player.&#x20;
  * **Based on Score (Weighted)**: Rewards are distributed proportionally based on score contribution.&#x20;
    * *Example*: A 100-point pool for positions 1–2. If 1st place has 40 points and 2nd place has 10 points (a 4:1 ratio), 1st place receives 80 points and 2nd place receives 20 points.&#x20;

{% hint style="info" %}
**Note**: You cannot overlap prize ranges. A user in rank 1-3 cannot also be included in a separate 1-10 prize entity simultaneously.
{% endhint %}

**\*Currency Prizes**: It is possible to distribute money-based prizes via dynamic distribution; however, this requires your Bonus API to support dynamic amounts to function correctly

{% hint style="warning" %}
**Note**: Clans with a money-based bonus prize should only be exposed to players with a known currency. If the currency is unknown, the player will still win, but the bonus prize will not be issued.&#x20;

It's highly recommended to set the in the tournament segment conditions "Core: wallet currency" to be defined
{% endhint %}

## Other settings

### Clan Rating scoring

Global Clan rankings are calculated based on performance in all completed clan tournaments over a defined window (e.g., last 30 days) by using an **ascending (lower is better) point system**:

* **1st Place**: 1 point
* **2nd Place**: 2 points
* **3rd Place**: 3 points
* **Any other placements**: 4 points
* **Not participating (Penalty)**: 5 points (default)

**Final Global Rating**: Clans are ranked by the **sum** of these points. The Clan with the lowest total score is ranked #1.

As you can see we are using an inverted rank scoring logic and we do so due to the following advantages:

* **No Negative Numbers**: Instead of taking points away and showing minus signs (like -5), this system keeps all scores positive. It looks cleaner and prevents clans from dropping into a negative total score, which hurts player morale.
* **Punishment for Inactivity**: In traditional systems, skipping a tournament gives you 0 points, which allows top clans to win once and then safely stay inactive. In this system, skipping a tournament gives a 5-point penalty, requiring clans to stay active to maintain their lead.
* **The Illusion of a Closer Race**: Because the point system uses small numbers (1 to 5), the gaps between clans look much smaller. This prevents top clans from building an unbeatable lead, keeping mid-tier clans motivated because the next ranking clan always feels within reach.

<div data-with-frame="true"><img src="/files/T9sEVqe8J3hrqnHFNGG7" alt="Gamification: Clan page"></div>

Both the **calculation window for clan rating** (max. 90 days) and the **penalty points amount on tournament skip** are configurable via label settings. For any adjustments, contact your Success Manager.

<div data-with-frame="true"><img src="/files/WaAs7d5ARY2lJebmn7BB" alt="BO: Label settings for the Global Clan rating period"></div>

<div data-with-frame="true"><img src="/files/MHVHmnxxR0DnZDtIiNAe" alt="BO: Label settings for the Penalty points on Clan tournament skip"></div>

### Clan Switching Rules

To maintain fair competition and prevent players from "jumping" to winning Clans just before a tournament ends, the following rules apply:

* **Cooldown Period**: Users cannot voluntarily switch Clans within **Y days** (Default: 7) of their last change.
  * The period can be defined via label settings. Contact your Success Manager to change it:

<div data-with-frame="true"><img src="/files/f6FsJBCvcGHc9nl09Usa" alt="BO: Label settings for the cooldowl period on clan switch"></div>

* **Tournament Protection**: If a user switches Clans, they are prohibited from participating in any Clan tournaments that were already underway when they joined and his points for all tournaments he participated in will be either deducted from the clans total or preserved based on the label setting, explained in [Leaving behavior](#leaving-behavior).
* **Leaving a Clan**: Users cannot voluntarily become "Clan-less." They must either switch to a new Clan or be removed by an operator/automation.

### Member Control & Management&#x20;

#### Clan Members tab

Located within the Clan section of the BO, this tab allows you to manually **add** or **kick out** members.&#x20;

<div data-with-frame="true"><img src="/files/jOp5GFE2WVEwzGJzxg1u" alt="BO: The members tab from the Clan setup"></div>

#### Player profile

You can directly observe and manage a specific user's clan status on their profile page.

![BO: The Clan section in the player profile](/files/SRp4sPTYumpegtlOcJZb)

* **Change Clan**: Move a player to a different Clan (bypasses entry fees).&#x20;

<div data-with-frame="true"><img src="/files/IkrdpitEHiMQ7ildW1aM" alt="BO: The change clan pop-up in Player profile"></div>

* **Kick Out**: Remove a player to make them "Clan-less."

<div data-with-frame="true"><img src="/files/Qn8hndwKpEFj03FIZT5y" alt="BO: The kick-out from clan pop-up in Player profile"></div>

#### User control from Gamification

User can join or switch clans freely from the Gamification but there are different states based on the different situations:

* User can join Clan for free

<figure><img src="/files/7ty6l6zwJYxY98jg8uqj" alt=""><figcaption></figcaption></figure>

* User cannot join a Clan due to insufficient points/gems/diamonds

<figure><img src="/files/8baa3uDqxN2YmDpHx5bK" alt=""><figcaption></figcaption></figure>

* User cannot join as he has a cooldown due to recent clan switch

<figure><img src="/files/LP4cFSjJrfonguLjHMwN" alt=""><figcaption></figcaption></figure>

* User cannot join as the Clan is full

<figure><img src="/files/Qlc9aulBbQMYvSNiihnX" alt=""><figcaption></figcaption></figure>

* User cannot join as he doesn't match the set conditions. This occurs when the user is part of the segmentation criteria for visibility but not for joining, so he sees the clan but can't become a member.

<figure><img src="/files/biQWj9BVIrkPV8scQShf" alt=""><figcaption></figcaption></figure>

* User is already part of that Clan

<figure><img src="/files/3ZeCW7ks7QOjALlpdxAj" alt=""><figcaption></figcaption></figure>

#### Leaving behavior

You can define the user leaving behavior in label settings. Choose whether to **keep** or **deduct** a user's accumulated tournament score if they leave a Clan while the clan tournament is ongoing.

<div data-with-frame="true"><img src="/files/5aZZD6ahvwUynGkODBIy" alt="BO: Label settings for the post-behavior when a member leaves a Clan"></div>

### Cross-brand setup & segmentation warning

It is critical that you maintain consistent segmentation conditions across both **Clans** and **Clan Tournaments** to ensure the intended user experience, especially in multi-brand environments.

* **Isolated Brand Strategy**: If you operate multiple brands and wish to keep Clan activity restricted to a single brand, you must synchronize your segments. Ensure that the **Visibility/Join segments** for a Clan match the **Tournament segments**.
  * Example: If a tournament is open to Brand A and Brand B, but Clans are only segmented for Brand A, users from Brand B will see a tournament they cannot effectively participate in, or vice versa.
* **Preventing Data Exposure**: If a Clan Tournament is accidentally set to "All Users," players from Brand B could potentially join using their own Clans, exposing Clan names or rankings across brands where they were intended to be hidden.
* **Cross-Brand Strategy**: If your goal is to have a shared community, ensure that both the Clans and the Clan Tournaments have broad segmentation rules that encompass all relevant brands.

### Clan Activities

You can use these two activities in campaign journeys to manage Clan memberships:

<div data-with-frame="true"><img src="/files/ro9vjVuPzHAKlh64nhqo" alt="BO: Example of Clan activities in Campaign journey"></div>

* **Assign to Clan**: Moves the user into a clan defined by you.

<div data-with-frame="true"><img src="/files/FTQj8XOjf9ExRenExJ2V" alt="BO: &#x22;Assign to Clan&#x22; activity configuration in Campaign journey"></div>

* **Remove from Clan**: Triggers the user's exit from their current clan.

<div data-with-frame="true"><img src="/files/Jxz3YDq4uT6MWBdyQ2cd" alt="BO: &#x22;Remove from Clan&#x22; activity configuration in Campaign journey"></div>

### Clan events

Smartico emits two events when a player's clan membership changes.

* **core\_clan\_joined:** Player joins a clan for the first time or switches from one clan to another - regardless of how the join happened (manual, deep-link, operator action, automation rule)
* **core\_clan\_kicked\_out:** Player is forcibly removed from a clan by an operator (via the CRM player profile), by an automation rule using the "Empty" assignment action, or when an operator archives a clan. This event is also triggered when the user is switching clans.&#x20;

### Clans public API

If you want to present Clans in a fully custom interface rather than using the Smartico gamification widget, you can do so through the public-api SDK

<https://github.com/smarticoai/public-api/blob/main/docs/api/classes/WSAPI.md#getclans>&#x20;

### Clans data in DWH

Smartico's Data Warehouse gives you direct SQL access to the following clan data via BigQuery:&#x20;

#### 1. Clan Catalogue (dm\_ach\_clans)

One snapshot record per clan — name, description, image, capacity, entry fee (if any), and current status (active / archived / draft). Think of it as your clan directory. It also carries the entry and visibility rules: which player segments can join or even see a given clan.

#### 2. Clan Rankings Over Time (g\_clans\_ranks)

Every time the system recalculates clan standings, it writes a snapshot: each clan's rank points, how many members contributed, and their global position in the table. Because every recalculation is kept (not overwritten), you can trace a clan's rise or fall over any period — similar to a Formula 1 constructors' championship history.

#### 3. Clan Tournament Results (g\_tournament\_winners)

The tournament prize-distribution record is the richest clan fact. For every player who finishes a clan-based tournament, the record carries not just their individual place but also: which clan they were in, where that clan placed, the clan's total score, how many clan members competed, and the player's rank within their own clan. This is the primary source for cross-referencing individual and team performance.

#### 4. Join and kickout transactions (tr\_core\_clan\_joined, tr\_core\_clan\_kicked\_out)

These tables represent all the facts when users joined or kicked out (left) clans


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.smartico.ai/welcome/products/tournaments/clans-and-clan-tournaments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.