A Location-Based Treasure Hunt and Rewards Gaming Platform

Delivered remotely for a business based in Helsinki, Finland. Names withheld by agreement.

Project Overview

Industry: Location-based entertainment and experiential marketing.

Type of solution: A consumer gaming platform: a REST API and administrative event-authoring back office, with two fully native mobile applications — one for each platform — built around continuous positioning, mapping, in-app purchase and push notification.

Business context: Physical treasure hunts work as an engagement format because they get people out of the house and into places. That is exactly why local businesses will pay to be part of one, and why brands and organisations want to host their own. The obstacle has never been demand; it has been operations. A manual hunt cannot verify that anyone reached a location, cannot rank finishers reliably, cannot prove to a sponsor that anyone walked through their door, and cannot be run twice without doing all the work twice.

General users: Players and teams; event authors and administrators who design and schedule hunts; participating businesses whose locations and offers appear inside the game; hosting organisations running private branded events; and on-call marshals who adjudicate live issues during an event.

General purpose: To make a physical, real-world game run itself — automatic location verification, sequenced clue progression, an authored content tree that can be cloned and rescheduled, sponsor visibility that is actually measurable, and rewards that resolve without anyone settling up by hand.

The Business Challenge

Proving someone actually got there. The entire premise depends on physical arrival at a coordinate. Consumer GPS is imprecise, degrades between tall buildings, behaves differently on each mobile platform and varies by handset. A radius too tight blocks honest players; too loose and there is no game. Getting this to feel fair is the product.

A hunt is a deep content tree, not a form. An event is a sequence of clues, each carrying ordered hints, map-placed destinations, associated offers, media and narration, wrapped in scheduling, reward structure and messaging. Authoring that through generic admin screens would take a day per event and nobody would do it twice.

Nothing was reusable. The same sponsor locations recur across events in a city. The same event format recurs month after month. Without reuse, every hunt is authored from nothing and the platform never gets operationally cheaper to run.

Teams have to stay in step. People play in groups, but each member carries their own device. When one member reaches a location, everyone's game has to advance at once — and every member's device has to find out immediately, without any of them ending up on a different clue from their teammates.

Finishing order decides outcomes. At a live event several teams can finish within seconds of each other, and position determines what each receives. Ordering has to be correct under that pressure, not approximately correct.

Sponsors want evidence, not exposure. A business paying to be a destination in a game does not want a logo placement. It wants to know how many people arrived and how many redeemed the offer.

Events are scheduled in local time, everywhere. Start times, reminders, countdowns and closing windows all run in the participant's local time across multiple timezones, with daylight saving moving the goalposts twice a year.

Two platforms, no shortcuts. Continuous positioning, background operation, map rendering, audio playback, foreground services and two separate store billing systems. Both clients needed deep platform integration.

When a hunt is live, problems are commercial. A participant stuck at a location with a countdown running and prizes on the line cannot wait for a support ticket. The platform needed a human escape hatch that resolves in minutes.

Our Approach

Build an authoring studio, not an admin panel. We built a staged event-builder wizard that walks an author through identity, scheduling, the clue sequence, destinations and offers, reward structure and notification copy — with reordering, media handling, cropping and per-stage saving throughout. The back office is where the product's real complexity lives, and it was treated as a product in its own right.

Make content reusable at the library level. Participating business locations and redeemable offers are authored once into shared libraries and attached to any number of events. A destination added for one hunt is available to every hunt afterwards, with its artwork, description and address intact.

Make an event a template. A complete event — every clue, hint, destination, offer and reward setting — can be cloned into a new scheduled instance. A hunt that worked becomes an asset that runs again next month rather than a one-off.

Put arrival detection on the device and authority on the server. Both clients run their own positional loop and report arrival when the player is inside a short radius of the active target. The server decides everything that follows: which clue comes next, what the team's shared state becomes, what the participant has earned, and where they placed. The device reports; the server rules.

Align the player, the sponsor and the platform in one mechanic. Hints — the thing a stuck player wants most — can either be earned by physically discovering a participating business's location, or purchased outright. That single design choice means the player gets help, the sponsor gets a real visit they can count, and the platform has a currency worth buying.

Synchronise teams explicitly and notify immediately. Progress is written across every team member's record as a single operation, with push notifications fanned out to the rest of the team so everyone's device reflects the same state within seconds of one member arriving.

Design a human back into an automated game. Participants who believe they have arrived but have not been credited can raise a request that carries their position and measured distance. It alerts an on-call marshal roster by SMS, and an approval replays the normal completion path exactly — so an adjudicated arrival is indistinguishable from an organic one in progress, notifications and reward eligibility.

Let each brand sound like itself. Event authors can supply their own push notification copy with placeholder substitution, and the platform falls back to sensible defaults when they do not.

Ship server changes without breaking installed apps. The API identifies the calling app's version and build and gates behaviour accordingly, so new server capability can go live while older releases still in the field keep working.

Go native on both platforms. Given continuous positioning, foreground and background operation, map rendering, audio and two different store billing systems, each client was built natively rather than through a shared abstraction.

The Solution

Event authoring studio. A staged builder covering event identity, category, difficulty, scheduling with explicit timezone handling, duration limits, imagery and audio, the full clue sequence, destinations, offers, reward structure and notification copy — with drag-reordering, cropping and media management throughout.

Reusable destination and offer libraries. Participating business locations and redeemable offers exist as shared records with their own artwork, descriptions, addresses and validity, attachable to any event.

Event cloning. An entire event content tree replicated into a new scheduled instance in a single action.

Public, private and paid events. Open events discoverable by anyone nearby; private events unlocked by a PIN for a specific audience; and paid events purchased through the platform store.

Location-aware discovery. Players see events within their chosen distance radius, filtered by their difficulty preference and by whether an event is upcoming, running or open, with search.

The live hunt. A map-centred play experience with custom styling, the player's live position, the active clue, discovered destinations, countdown timers, audio narration with transport controls, image galleries and screen-idle suppression so the display stays awake while playing.

Automatic arrival detection. Each client continuously evaluates its position against the active clue and nearby destinations and reports arrival automatically when the player is close enough — no button to press, no code to type.

Sequenced clue progression. The server determines the next clue in sequence and records progression, so the route cannot be skipped or reordered from the client.

Hints, earned or purchased. Hints attached to a clue unlock in order. They can be obtained by physically discovering a participating destination or by spending credits, with a full history the player can review afterwards.

Rewards wallet. Offers collected during play are held in the player's wallet with validity and redemption state, and are redeemed from within the app.

Team play. Teams can be created, joined, switched and left, with a captain. Progress, hint spending, leaderboard position and rewards are all team-aware, and every member is notified as the team advances.

Leaderboards. A finishing-order leaderboard for completed events and a live progress leaderboard computed from clue completion during play.

Prizes on completion. A reward structure configured per event resolves automatically when a participant or team completes it, with the outcome recorded, communicated and tracked through to claim.

Participant support with human adjudication. Stuck requests routed to an on-call marshal roster by SMS, with administrative approval that replays the normal completion path.

Notifications. Push delivery to both platforms with a multi-device registry per player, retry on transient failure, automatic pruning of dead tokens, per-event message copy, and administrative broadcast to everyone, to one event's participants, or to an individual.

Sponsor reporting. Destination visits and offer redemptions tracked and reportable by destination and by event.

Administrative platform. Event, taxonomy, business, participant, team and winner management; prize and purchase reporting; role and permission control with a hierarchy; a database-driven navigation builder; a media library; and email templating.

Key Features

Automatic arrival detection Continuous positional evaluation against the active clue and nearby destinations, so reaching a location is recognised automatically rather than self-reported.

Staged event-authoring studio A multi-step builder for the full event tree — clues, ordered hints, destinations, offers, reward structure, scheduling, media and messaging — with reordering and per-stage saving.

Reusable destination and offer libraries Participating business locations and redeemable offers authored once and attached to any event, so operational cost falls with every hunt rather than repeating.

One-action event cloning A complete event content tree replicated into a new scheduled instance, turning a successful hunt into a repeatable format.

Team-synchronised gameplay Shared team progress advanced by whichever member arrives first, written across all member records and pushed to every teammate's device immediately.

Dual-path hint economy Hints earned by discovering participating destinations or purchased with credits — aligning the player's need for help with the sponsor's need for verified visits.

Human adjudication built into an automated game Stuck requests carrying position and distance, escalated to an on-call marshal roster by SMS, with approval that replays the standard completion path rather than patching state.

Reward wallet and lifecycle Collected offers and won prizes held with validity, redemption and claim state, with unclaimed value ageing out on a managed schedule rather than accumulating indefinitely.

Private and paid event modes PIN-gated private events for a specific audience and paid entry through platform in-app purchase, alongside open public events.

Sponsor visit and redemption reporting Destination visits and offer redemptions tracked per destination and per event, giving participating businesses measurable outcomes rather than impressions.

Technical Architecture

Mobile clients. Two fully native applications built independently against a shared API contract. Each runs its own positional loop against the platform's location services, renders the live hunt on a native map with custom styling, plays audio narration, handles in-app purchase through its platform store, receives push notifications, and reports crashes. Android additionally runs a foreground location service for the duration of a hunt; iOS uses background modes and significant-change monitoring.

API layer. A token-authenticated REST API over OAuth2 bearer tokens, with controllers partitioned into a player-facing tree and an administrative tree. The API parses the calling app's version and build and gates behaviour so releases already in the field continue to work against a newer server.

Game state layer. The server owns clue sequencing, team state fan-out, credit balances, offer issuance and claim rules, finishing order and reward resolution. Client-reported arrival is an input to that state machine, never a substitute for it.

Authoring back office. A server-rendered administrative application built on an open-source component framework, providing the staged event builder, taxonomy and library management, participant and team views, reporting grids, media handling with cropping, role and permission control and a database-driven navigation model.

Notification layer. Push delivered through a managed messaging service using service-account-signed requests, with a multi-device token registry per player, retry on transient failure and automatic pruning of permanently invalid tokens. SMS escalation runs through a managed telephony provider against a maintained recipient roster.

Scheduled processing. Console commands on short intervals handle event lifecycle transitions, reminders, participation counts and reward lifecycle ageing, keeping this work off the request path.

Media layer. Uploaded imagery, artwork and audio are pushed to cloud object storage and served from there, keeping the application tier free of file state.

Data layer. A relational database covering events, clue and hint trees, destinations, offers, reward and prize records, teams and membership, participation and progress, visit and redemption tracking, purchase records and request logs — evolved through a long migration history spanning several years of continuous development.

Flow: Native mobile client (positional loop) → Token-authenticated API → Server-side game state and sequencing → Relational database → Scheduled lifecycle processing → Push and SMS notification → Administrative authoring studio and sponsor reporting

Technology Stack

Technical Challenges & Solutions

Security & Reliability

Token-based authentication. OAuth2 bearer tokens for all player API access, with registration, social and platform-native sign-in, password recovery and account deletion flows.

Role-based administration. The authoring back office is authenticated and role-gated, with a permission model and role hierarchy determining what each administrative user can reach, and a database-driven navigation model that reflects those permissions.

Server-side game authority. Clue sequencing, team state, credit balances, offer issuance, claim eligibility and finishing order are all resolved server-side. The client reports observations; it does not decide outcomes.

Controlled event access. Private events are gated behind a PIN, and paid events behind a completed platform purchase, so access to an event's content is an explicit grant.

Reward integrity rules. One-claim-per-player enforcement on offers, explicit lifecycle states for collected rewards and won prizes, and scheduled ageing of unclaimed value so entitlement is bounded and auditable.

Auditable play history. Participation, progress, hint usage, destination visits, offer redemptions and prize outcomes are all retained, so a disputed result during a timed event can be reconstructed from record rather than recollection.

Content safety during live events. Game content uses soft deletion and explicit removal flags, so editing or retiring content does not corrupt an event that is currently running or already completed.

Crash and delivery monitoring. Crash reporting on both mobile platforms, request logging with device and client version capture on the server, and notification delivery outcomes recorded rather than assumed.

Human escalation path. A marshal roster and an adjudication workflow provide a reliable resolution route for live-event failures that automation cannot cover.

Scalability & Performance

Bounded discovery queries. Event discovery is constrained by distance radius, difficulty preference and lifecycle state at the database level, so a player never receives the full catalogue regardless of how large it grows.

Media served from object storage. All imagery, artwork and audio are held in cloud object storage and delivered from there, keeping the application tier stateless and free of file-serving load.

Client-side caching on both platforms. Image loading and caching libraries on each client keep repeated map artwork, destination icons and event imagery off the network during play.

Scheduled batch processing. Event lifecycle transitions, reminders, participation counts and reward ageing all run as scheduled commands rather than on the request path, so background work never competes with live gameplay.

Delegated notification infrastructure. Push delivery runs through a managed messaging service, scaling with participant volume without the business operating messaging infrastructure.

Positional polling rather than streaming. Clients evaluate position locally on an interval and call the API only when something has actually happened, so a live event with many concurrent participants generates traffic proportional to progress rather than to time.

Stateless application tier. Token authentication and externalised media keep application instances free of local state and horizontally replaceable.

Sound and screen behaviour tuned for play. Audio feedback, idle-timer suppression and foreground service handling are managed per platform so a hunt survives a long session on a real handset.

Business Outcomes

• A physical game runs itself. Arrival is detected automatically, progression is sequenced by the platform, and results resolve on completion — removing the marshalling, adjudication and manual settlement that made the format unscalable.
• Events became reusable assets. Cloning an authored event and reusing shared destination and offer libraries means each hunt costs less to produce than the one before it.
• Participating businesses get measurable outcomes, with destination visits and offer redemptions tracked and reportable rather than inferred from impressions.
• Player help and sponsor value come from the same mechanic, because hints can be earned by physically discovering a participating destination as well as purchased.
• Groups can play together properly, with team progress synchronised across devices and every member notified as the team advances.
• Events can be public, private or paid, so the same platform serves open consumer hunts, branded private events and paid entry without separate builds.
• Live-event failures have a resolution path, with stuck participants escalated to a marshal within minutes and adjudicated outcomes indistinguishable from organic ones.
• Every result is reconstructable, with participation, progress, rewards and outcomes retained as record for a format where prizes make disputes inevitable.

Why it worked

Location-based games look like map applications and are not. A mapping app that is slightly wrong is mildly annoying; a game that is slightly wrong tells an honest player standing in exactly the right place that they have not arrived — while a prize goes to someone else and a countdown runs down. The engineering problem is not drawing the map. It is deciding what to trust, how quickly to respond, and what to do when the physical world does not cooperate.

Our team built for that reality. We put detection on the device for responsiveness and kept authority on the server for correctness, because those are different problems with different right answers. We modelled team play as genuinely shared state rather than several parallel single-player games, because that is what people actually do. We designed a human adjudication path into an automated system and made its outcome identical to the automated one, because at a live event with prizes, "the system says no" is not an acceptable final answer. And we treated the authoring studio as a product rather than an afterthought, with reusable libraries and event cloning, because a platform that makes every event as expensive as the first one is not a platform.

Our teams work across Laravel and modern PHP, REST API design for long-lived mobile contracts, native Android and native iOS development with deep location, mapping, background execution and store billing integration, push and SMS infrastructure, and administrative platforms complex enough to be products in their own right.

Final Summary

A real-world treasure hunt is a genuinely good experience and a genuinely bad operation. Clues have to be hidden, marshals stationed, arrivals adjudicated, finishing order tracked and prizes settled — and when it is over, none of it can be reused. Sponsors who paid to be part of it have no idea whether anyone actually came.

Our team built a platform that turns the format into software. Event authors design a hunt in a staged studio — the clue sequence, the ordered hints, the destinations along the route, the offers those destinations issue, the reward structure, the scheduling and the messaging — drawing on shared libraries of participating locations and offers so recurring content is attached rather than rebuilt. A finished event can be cloned into a new scheduled instance in one action, which is what turns a good hunt into a format that runs again.

On the ground, two native mobile applications run the game live: a map-centred play experience with countdown timers, audio narration and continuous positioning that recognises arrival automatically, with the server retaining authority over what comes next, what the team's shared state becomes, what the player has earned and where they placed. Teams stay in step because progress is written across every member and pushed to every device. Hints can be earned by physically discovering a participating business or purchased outright — one mechanic serving the player, the sponsor and the platform at once. Rewards land in a wallet with real validity and redemption rules, prizes resolve on completion, and destination visits and redemptions are tracked so a sponsoring business gets a number rather than an impression.

And when the physical world misbehaves — as it does, in doorways and underpasses and dense city blocks — a participant can escalate, a marshal is alerted by SMS, and an approved adjudication replays the normal completion path exactly. That last detail is the one that matters most: it is the difference between a game people trust and a game people argue with.