◼️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.
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.
Implementation Guide
Before diving into the detailed configurations, follow these high-level steps to activate and test the Clan ecosystem on your label:
Request Activation: Submit a request to Customer Support to enable the Clan product for your specific label.
Clan Creation: Create your initial set of Clans, ensuring you maintain consistent user segmentation across them.
Tournament Alignment: Create at least one Clan Tournament. Ensure its visibility and registration segmentation matches the segments used for your Clans.
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.
The maximum recommended capacity for a clan is 100,000 members. Setting a higher limit is not advised, as optimal system performance cannot be guaranteed beyond this threshold.
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
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:
Clans: Users compete as a collective unit; scores are aggregated per Clan.
Individual Players: The standard "every player for themselves" format.
Note: All other tournament settings (duration, games, etc.) remain identical to standard setups.
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:
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.
Example: 100 points for positions 1–4 = 25 points per player.
Based on Score (Weighted): Rewards are distributed proportionally based on score contribution.
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.
Note: You cannot overlap prize ranges. A user in rank 1-3 cannot also be included in a separate 1-10 prize entity simultaneously.
*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
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.
It's highly recommended to set the in the tournament segment conditions "Core: wallet currency" to be defined
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.
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.
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:
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 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
Clan Members tab
Located within the Clan section of the BO, this tab allows you to manually add or kick out members.
Player profile
You can directly observe and manage a specific user's clan status on their profile page.
Change Clan: Move a player to a different Clan (bypasses entry fees).
Kick Out: Remove a player to make them "Clan-less."
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
User cannot join a Clan due to insufficient points/gems/diamonds
User cannot join as he has a cooldown due to recent clan switch
User cannot join as the Clan is full
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.
User is already part of that Clan
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.
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:
Assign to Clan: Moves the user into a clan defined by you.
Remove from Clan: Triggers the user's exit from their current clan.
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.
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/WSAPIClans.md#getclans
Clans data in DWH
Smartico's Data Warehouse gives you direct SQL access to the following clan data via BigQuery:
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
Last updated
Was this helpful?