Engagement features
reasons to come back.
Season pass, achievements, the check-in calendar, events, teams, friends, a second referral level, the mystery box, mini-games, the rewards store, the inbox and promo codes. This page lists what you configure for each one, where, and with which defaults.
01Switches and where content lives
Every feature has a switch in console → Features, on by default (admin/src/manifest.ts). A feature without content (no season, no events, no store items) shows nothing to users. All rewards are points or cosmetics. None of these features pays money or anything of cash value.
| Feature | Switch | Content and settings | Out of the box |
|---|---|---|---|
| Season pass | Season pass | Settings → Season pass | No season runs (id and dates empty) |
| Achievements | Achievements | Settings → Achievements | 8 achievements |
| Check-in calendar | Check-in calendar | Settings → Rewards economy | Active, 31 rewards |
| Events and tournaments | Events and tournaments | Page → Events | No events |
| Teams | Teams | Settings → Mystery box and mini-games (team size), page → Teams | Active, max 30 members |
| Friends | Friends | none | Active |
| Second referral level | Invite friends | Settings → Rewards economy | Off (0 points) |
| Mystery box | none (own toggle) | Settings → Mystery box and mini-games | Off |
| Mini-games | Mini-games | Settings → Mystery box and mini-games | Active |
| Rewards store | Rewards store | Page → Rewards store | No items |
| Inbox | Notifications inbox | Filled by push campaigns and event prizes | Active, empty |
| Promo codes | Promo codes | Page → Promo codes | No codes |
No feedback loops. Points from the season, events, achievements, promo codes, the mystery box and point packs do not count as "earned". They never raise season XP, event standings, team points or the velocity check (NOT_EARNED in firebase/functions/src/credit.ts).
02Season pass
Console → Season pass. One season at a time. Season XP = points earned during the season (not admin adjustments). Each level unlocks a free reward and a VIP reward.
| Setting | Default | Notes |
|---|---|---|
| Season id | empty | Short and unique, e.g. s2026-11. A new id starts a new season, and XP starts at 0. |
| Season name | empty | Shown in the app. |
| Starts (UTC), Ends (UTC) | empty | YYYY-MM-DD or YYYY-MM-DDTHH:MM. At most 180 days. No season runs while the id or a date is empty or invalid. |
| XP per level | 1000 | 10 to 1000000 |
| Tiers | 5 levels | One per line: level|free points|free cosmetic id|VIP points|VIP cosmetic id, e.g. 3|40||80|my-gold-frame. A cosmetic id is the Id of an avatar, frame or theme on the Rewards store page. Leave a part empty for none. Levels ascend, at most 100. The default tiers are points only: 1|20||40|, 2|30||60|, 3|40||80|, 4|50||100|, 5|60||120|. |
Users claim a tier while the season runs and up to 7 days after it ends (claimSeasonTier). The VIP column needs an active VIP subscription.
A cosmetic reward puts that id into the user's inventory, and the app draws cosmetics from active store items. The console creates a store item's id from its title plus a random suffix (e.g. gold-frame-3fa9c1, admin/src/data-core.ts). Copy it from the Id column of console → Rewards store. The same applies to cosmetic:<id> mystery-box prizes and to event prizes. The Status page check "Season, mystery box and event cosmetics exist in the Rewards store" warns about any id that matches no avatar, frame or theme in the store.
03Achievements
Console → Achievements, one per line: id|title|metric|target|points. Metrics: ads, spins, quizzes, streak, referrals, points, games. Several lines on the same metric make tiers. A user claims each achievement once (claimAchievement).
Default list: ads_10 (watch 10 videos, 50), ads_100 (100 videos, 300), spins_25 (100), quizzes_10 (100), streak_7 (100), referrals_1 (100), points_1000 (100), games_10 (100). Never change an id once users have claimed it. An empty list means no achievements.
04Check-in calendar
A monthly calendar. A user checks in once per UTC day (checkIn). Checking in also claims today's daily streak, so the streak logic is unchanged.
Console → Rewards economy → Check-in calendar rewards: up to 31 whole numbers, one per line. The default is 10 for the first six check-ins, 50 for the 7th, then 15/75, 20/100 and 25/150 in the same weekly pattern, and 30 for the last three.
Line n pays the user's n-th check-in of the UTC month, whatever the date. A missed day does not skip a line, so a user who skips a day does not lose the bigger 7th reward (firebase/functions/src/callables/progression.ts). With fewer than 31 lines the last value repeats. The VIP or booster multiplier applies.
05Events and tournaments
Console → Events. An event ranks users by points earned while it runs. Fields: title, starts and ends (UTC), active, and prize rows rank from – rank to → points plus an optional cosmetic id.
- Live standings (top 100) are on the event's page in the console and in the app.
- The scheduled job
settleEvents(every 15 minutes) pays prizes once after the end and puts a message in each winner's inbox. - The console never edits a settled event and deletes only events that have not started.
- Prizes are points and cosmetics only. Real-world prizes turn an event into a contest under store rules and local law (Policy and compliance).
06Teams
Users create a team (name 3 to 24 characters, tag 2 to 5 letters or digits) or join one by tag. Team points add up members' earned points, and there are all-time and weekly team leaderboards. When the owner leaves, the oldest member takes over. When the last member leaves, the team is deleted.
Settings: Team size (most members), default 30 (2 to 500), in the Mystery box and mini-games section. Console → Teams: search by tag, see the members, and disband a team with a reason of 8 or more characters. Disbanding removes the team and its leaderboard entries and clears each member's team.
07Friends
Users add a friend with the friend's referral code (addFriend, both sides, at most 200 friends). The friends leaderboard compares this week's points from public profiles. The operator configures nothing. Deleting an account removes it from friends' lists.
08Second referral level
Console → Rewards economy → Second-level invite bonus (points), default 0 = off. When an invited user reaches the unlock amount, the inviter gets the usual inviter bonus, and the inviter's own inviter gets this bonus at the same moment (ledger type referral).
The code pays at most two levels, by design. Do not extend it: multi-level reward chains look like pyramid schemes to stores and users.
09Mystery box
Console → Mystery box and mini-games. The box is opened with points only, never with money, and the app shows the odds of every prize before opening.
| Setting | Default | Allowed |
|---|---|---|
| Mystery box | off | |
| Cost in points | 50 | 1 to 1000000 |
| Most opened per day (per user) | 10 | 0 to 1000 |
| Prizes | 10|40, 25|30, 50|18, 100|9, 500|3 | One per line as points|weight or cosmetic:<id>|weight. 1 to 20 prizes, weight above 0. |
The odds shown are each prize's weight ÷ the sum of weights. Prize points add to the spendable balance only, not to lifetime points or leaderboards. If you sell point packs, read Store policy.
10Mini-games
A memory game and a word game. The server creates each game, keeps the solution and checks the result before it credits: every move must be valid, the solution correct, and the play time plausible. A game expires after 30 minutes (startGame / finishGame).
| Setting | Memory | Word |
|---|---|---|
| Points per win | 20 | 15 |
| Credited wins per day | 5 | 5 |
| VIP only | off | off |
| Minimum seconds (backend default, not in the console) | 10 | 3 |
After a game result the app may offer a rewarded interstitial or count a natural break for interstitials (Placements).
11Rewards store
Console → Rewards store. Users buy items with points (buyStoreItem, ledger type store).
| Kind | Asset id | What happens |
|---|---|---|
| Avatar | Required: rocket cat star bolt crown ghost leaf music planet heart diamond game | Goes to the inventory and can be equipped. The equipped avatar shows on the user's leaderboard, event and team rows. |
| Frame | Required: gold neon silver fire ice rainbow | Same as avatars: the equipped frame is drawn around the avatar on leaderboard, event and team rows. |
| Theme | Required: ocean sunset forest grape rose gold | An equipped theme recolours the app. |
| Perk | Optional | Goes to the inventory. |
| Operator reward (reviewed) | none | Creates a redemption in console → Redemptions. Fulfil once you delivered it, or Reject, which refunds the points by default. |
Other fields: title (up to 80), cost (1 to 10000000 points), stock (empty = unlimited), active. The asset ids are the drawings built into the app (docs/CONTRACT-3.1.md §11). The table's Id column shows each item's id, which you use for season, mystery-box and event cosmetic prizes.
Avatars and frames on ranking rows. The server stores the equipped avatar and frame (avatarId, frameId) on leaderboard entries, event entries and team members whenever it credits earned points, and when a user creates or joins a team (firebase/functions/src/credit.ts, callables/social.ts). The app draws them on leaderboard, event standings and team member rows: other users' rows show what they had equipped at their last credit, and the user's own row always follows what is equipped now.
Good examples are the console's own: a shout-out in your community, a profile badge you award by hand, early access to a feature. The console refuses titles that name cash, money, gift cards, vouchers, crypto or a currency sign. Points come from ads, so AdMob's rewards policy applies. Read Operator rewards before you add one.
12Notifications inbox
Each user has an inbox in the app. Push campaigns put a copy there (Push campaigns), and so do event prizes. The user can mark messages as read. The operator has nothing else to configure.
13Promo codes
Console → Promo codes: code (3 to 32 characters, A–Z, 0–9, _, -, upper case), points, most uses across all users, optional expiry (UTC). Each user can redeem a code once. Deactivate stops a code at once. Promo points do not count as earned. See also Growth.