Skip to main content

Treasure Hunts

A treasure hunt is a multi-clue activation where members solve clues in order, with each correct clue awarding points. Completing the final clue unlocks a completion bonus and optionally an exclusive badge.

When to use it​

  • An in-store activation: clues are posted around the venue and members scan QR codes or answer questions to progress.
  • A location-based campaign: clues are GPS coordinates and members get points for visiting each one.
  • A trivia campaign with a narrative arc: questions get harder as the hunt progresses.

How it works​

A treasure hunt is a parent TreasureHunt row with a list of ordered TreasureHuntClues. The hunt has its own status (Draft / Active / Ended), a loyalty program (where the points go), a completion reward (points + optional badge) and an optional end date.

Each clue has:

  • Order number — clues are solved in sequence, no skipping ahead.
  • Type — one of Question, Code, Location, QR scan, or Photo.
  • Points for clue — awarded on success.
  • Answer fields — type-specific.

When a member submits an attempt, the engine validates the answer against the clue and either awards the points (and unlocks the next clue) or returns "Incorrect answer. Try again!" with no penalty. On the last clue, the engine also awards the completion bonus and badge.

Clue types​

Question / Code​

A free-text answer (case-insensitive, trimmed). Use Question for narrative clues ("What's the name of the painter in the lobby?") and Code for unlock codes printed on packaging.

Location​

GPS-based. Configure latitude, longitude, and radius (metres) — defaults to 50 m. The member's submitted coordinates pass if their distance to the target (great-circle / Haversine) is within the radius. Use it for "go to this address" clues.

QR scan​

The scanned QR code must equal the configured code exactly (case-sensitive). Print QR codes on physical objects (posters, packaging, in-store signs) and use this type to verify the scan.

Photo​

Currently a placeholder — any submitted answer passes. Don't rely on this for hunts that actually need photo verification; it will be hooked up to an external validator in a later release.

Step-by-step​

Create the hunt​

  1. Go to Gamification → Treasure hunts and click Create hunt.
  2. Fill in:
    • Name and optional end date.
    • Loyalty program (where awarded points go).
    • Completion reward points and optional completion badge.
  3. Save. Status starts as Draft.

Add clues​

  1. On the hunt detail page, open the Clues tab.
  2. Add clues in the order you want members to solve them. Each clue has its own points for clue.
  3. Fill the type-specific fields (answer text / GPS / QR code).
  4. Reorder clues by editing the Order number.

Publish​

  1. When the clue list is ready, set Status to Active. Only active hunts accept attempts.
  2. Communicate the hunt to your audience — the first clue is presented in the member portal as soon as the hunt is active.

Limits and gotchas​

  • GPS accuracy varies. A radius of 50 m is reasonable for outdoor clues; indoors, GPS can drift by 30 m or more — bump the radius accordingly. Members on phones with low GPS accuracy can be frustrated by tight radii.
  • QR scans are case-sensitive. "INCENTIA-42" and "incentia-42" are different codes.
  • No retry penalty. Incorrect attempts don't cost the member anything. Don't lean on the hunt for fraud-resistance — it's an engagement tool.
  • Sequential only. There's no branching (solve any 3 of 5 to win). The whole hunt is one ordered path.
  • Photo clues are a placeholder. Don't promise real photo validation until that lands.
  • Campaign multipliers apply. If an active campaign multiplies points in context TreasureHunt, the clue and completion bonuses are multiplied.
  • Permission: Pages.Gamification.TreasureHunts.