Gamification

Integrate Smartico gamification features into your brand.

Prerequisites

• An active Smartico account with keys provided by the Cactus team
• Keys: labelKey, brandKey, saltKey (and optionally visitor keys)

Configuration

Configure by file (base + brand override):

File	Purpose
app/config/gamification/gamification.ts	Provider keys, naming, module toggles (gamificationConfig)
app/config/gamification/gamification.server.ts	Server-only salt-key fallback (smarticoHashConfig)
app/config/gamification/gamification-ui.ts	Visual knobs for the gamification pages (gamificationUiConfig)

Each one is brand-overridable at overrides/<brand-key>/app/config/gamification/<file>.ts.

<brand-key> is derived from ORIGIN_DOMAIN — lowercase, dots replaced with hyphens (minhamarca.com → minhamarca-com).

Edit app/config/gamification/gamification.ts:

export const gamificationConfig: GamificationConfig = {
  enabled: true,
  provider: 'smartico',
  smartico: {
    labelKey: 'your_label_key',
    brandKey: 'your_brand_key',
    // ...
  },
  // ...
};

:::danger Overrides replace the whole file A brand override is a complete file replacement, not a deep merge. Copy the base file into your override directory and edit the values — anything you leave out arrives as undefined. :::

Server-side salt key

The saltKey used for user hash generation is a server-side secret and must be configured via the SMARTICO_SALT_KEY environment variable (.dev.vars for local dev, Cloudflare secret for production).

The app/config/gamification/gamification.server.ts file still exists as a fallback, but the environment variable takes priority:

1. SMARTICO_SALT_KEY env var (Cloudflare secret / .dev.vars)
2. smarticoHashConfig.saltKey in app/config/gamification/gamification.server.ts (fallback — empty in the base)

cuidado

Never commit real salt keys in override files. Use the environment variable instead. The Cactus team will configure the Cloudflare secret for your brand.

informação

Gamification/Smartico settings are driven by config overrides per brand.

Enabling / disabling modules

Each gamification feature is toggled in the modules block of app/config/gamification/gamification.ts. These are the base defaults — note that four modules ship off:

modules: {
  missions:      { enabled: true,  native: true, public: true },
  tournaments:   { enabled: true,  native: true, public: true },
  store:         { enabled: true,  native: true },
  miniGames:     { enabled: true,  native: true, showInactive: true },
  levels:        { enabled: true,  native: true },
  profile:       { enabled: true,  native: true },
  notifications: { enabled: true,  native: true },
  badges:        { enabled: false, native: true },
  bonuses:       { enabled: false, native: true },
  jackpots:      { enabled: false, native: true },
  raffles:       { enabled: false, native: true },
}

Field	Effect
enabled: true	Module is active
enabled: false	Module is completely hidden (no buttons, no pages)
native: true	Uses the template's React UI (recommended)
native: false	Uses Smartico's built-in overlay widget
public: true	Listing is browsable by logged-out visitors (see "Visitor mode" below)
showInactive: true	Also lists items the provider marked as inactive

Available routes

When modules are enabled with native: true, these pages are available. The paths shown below are the defaults — they are configurable via the Route Registry.

Key	Default path	Description
gamification	/vip	Gamification hub
gamification.missions	/vip/missions	Missions listing with filters
gamification.tournaments	/vip/tournaments	Tournaments listing with filters
gamification.tournament	/vip/tournaments/:id	Tournament detail (leaderboard, prizes)
gamification.store	/vip/store	Store with filters
gamification.miniGames	/vip/mini-games	Mini-games listing
gamification.levels	/vip/levels	Level progress timeline
gamification.badges	/vip/badges	Badges listing
gamification.bonuses	/vip/bonuses	Bonuses listing
user.notifications	/user/notifications	Notifications inbox

dica

Brands can customise all gamification paths — a Spanish-language brand might map gamification.missions to /gamificacion/misiones instead of /vip/missions. Always use routeHref("gamification.missions") for links, never hardcoded paths. See Routes.

Visitor mode

Modules marked public: true (missions and tournaments in the base) have browsable listings for logged-out visitors. When a visitor tries to open a detail page, they are prompted to log in.

Customization tips

• Naming: Change naming.programName and naming.coinsName in the config to match your brand
• Sidebar buttons: The VIP highlight buttons in the sidebar can be styled via your theme tokens
• Disable specific modules: Set enabled: false for modules you don't need
• Use Smartico UI for everything: Set native: false on all modules to use Smartico's built-in overlays instead of custom React pages