Installation

Choose your platform

Quest Hunter is built with Expo and React Native, providing a native experience on iOS and Android, plus web support for desktop browsing. Select your platform to get started.

iOS

Android

Web

iOS installation

Requirements

Before installing Quest Hunter on iOS, ensure you have:

iOS device running iOS 13.0 or later
Apple ID for App Store access
At least 100 MB of free storage

Quest Hunter supports both iPhone and iPad with optimized layouts for tablets.

Download from App Store

Search for “Quest Hunter” in the App Store or use the direct link:

App Bundle ID: com.levinbaenninger.questhunter
Publisher: Levin Baenninger

Tap Get to download and install the app.

Grant permissions

On first launch, Quest Hunter requests:Location permissions: Required to show your position on maps and help you navigate to quest locations.The permission request shows: “Allow Quest Hunter to use your location”Camera permissions: Required to capture photos at quest checkpoints.

Without location and camera permissions, you won’t be able to complete quests. You can grant these permissions later in iOS Settings > Quest Hunter.

Launch Quest Hunter and sign in with your Google account. See the Quickstart guide for authentication details.

iOS-specific features

Edge-to-edge display

Quest Hunter uses React Native’s safe area context to provide an edge-to-edge experience on devices with notches and dynamic islands, while keeping content in safe viewing areas.

App scheme

The custom URL scheme questhunter:// allows deep linking into specific quests and locations from external sources.

Dark mode support

Quest Hunter automatically adapts to your iOS appearance settings (Light/Dark/Auto) using the userInterfaceStyle: automatic configuration.

Android installation

Requirements

Before installing Quest Hunter on Android, ensure you have:

Android device running Android 6.0 (API 23) or later
Google Play account
At least 100 MB of free storage
Google Play Services installed (for authentication)

Download from Play Store

Search for “Quest Hunter” in the Google Play Store or use the direct link:

Package Name: com.levinbaenninger.questhunter
Publisher: Levin Baenninger

Tap Install to download and install the app.

Grant permissions

Quest Hunter requests two runtime permissions:Location permissions:

android.permission.ACCESS_FINE_LOCATION
android.permission.ACCESS_COARSE_LOCATION

These are required for:

Showing your position on quest maps
Calculating distance to checkpoints
Providing navigation assistance

Camera permission: Required for photo verification at quest locations.

Android 6.0+ uses runtime permissions. You’ll be prompted to grant access when starting your first quest and taking your first photo.

Launch Quest Hunter and sign in with your Google account. The app uses Google OAuth through Clerk for seamless authentication.

Android-specific features

Google Maps integration

Quest Hunter uses Google Maps on Android with API key integration for high-quality map rendering. The maps show:

Quest location markers
Your current position
Distance and directions to checkpoints

Maps are powered by the expo-maps library with native Google Maps views.

Edge-to-edge display

Quest Hunter enables Android’s edge-to-edge mode (edgeToEdgeEnabled: true) for immersive full-screen experience on modern Android devices.

Adaptive icon

The app features an adaptive icon that conforms to different device launcher styles:

Foreground image: Main app logo
Background: Custom color (#E6F4FE)
Monochrome variant: For themed icons on Android 13+

Predictive back gesture

Predictive back gestures are disabled (predictiveBackGestureEnabled: false) to provide custom back handling within quests, preventing accidental exits.

Web installation

Quest Hunter is also available as a web application for desktop and tablet browsers.

Requirements

To use Quest Hunter on the web, you need:

Modern browser (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)
JavaScript enabled
Location services enabled in browser
Camera access for photo capture

Access the web app

Navigate to the Quest Hunter web URL in your browser:

https://quest-hunter.vercel.app

The web version is a static site built with Metro bundler and optimized for performance.

Grant browser permissions

When prompted, allow:Location access: Required for map features

Click the location icon in your browser’s address bar
Select “Always allow” for best experience

Camera access: Required for photo verification

Grant access when starting photo capture
Permissions persist per browser session

Use Google OAuth to sign in. The web version uses the same authentication flow as mobile apps.

Web-specific features

Progressive Web App (PWA)

Quest Hunter can be installed as a PWA on supported browsers:

Visit the web app
Look for the install prompt in your browser
Click “Install” to add Quest Hunter to your home screen or app drawer

The PWA provides:

Offline capability for cached data
Native-like app experience
Faster subsequent loads

Responsive design

The web version adapts to different screen sizes:

Desktop: Full-width layout with optimized navigation
Tablet: Responsive card grids and comfortable touch targets
Mobile web: Native-like mobile experience

Camera support

Web browsers use the MediaDevices API for camera access. On desktop:

You’ll be prompted to select a camera
Webcam photos work for verification
Mobile web uses device cameras normally

Development setup

Developers who want to run Quest Hunter locally or contribute to the project can set up the development environment.

This section is for developers only. Regular users should install from the App Store, Play Store, or web.

Prerequisites

Install the required tools:

# Quest Hunter requires Node.js 24.14.0 or later
node --version  # Should show v24.14.0+

Clone and install

Clone the repository

git clone https://github.com/yourusername/quest-hunter.git
cd quest-hunter

Install dependencies

bun install

This installs all dependencies defined in package.json, including:

expo ~54.0.33
react-native 0.81.5
@clerk/clerk-expo ^2.19.27
convex ^1.32.0
expo-maps ~0.12.10

Configure environment

Create a .env.local file with your credentials:

.env.local

# Clerk authentication
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_key

# Convex backend
CONVEX_DEPLOYMENT=your_convex_deployment_url
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud

# Google Maps (Android)
GOOGLE_MAPS_API_KEY=your_google_maps_key

Never commit your .env.local file to version control. It contains sensitive credentials.

Start the development server

bun dev

This command runs:

expo start - Starts the Expo development server
convex dev - Starts the Convex backend in development mode

Both processes run in parallel using mprocs.

Run on devices

iOS
Android
Web

bun run:ios

This builds and runs the app on an iOS simulator or connected device. Requires:

macOS with Xcode installed
iOS simulator or physical device connected

bun run:android

This builds and runs the app on an Android emulator or connected device. Requires:

Android Studio with SDK installed
Android emulator running or physical device connected via ADB

bun web

Opens Quest Hunter in your default browser at http://localhost:8081.

Development scripts

# Run TypeScript type checker
bun typecheck

Configuration reference

app.json configuration

The app.json file configures Expo settings:

{
  "expo": {
    "name": "quest-hunter",
    "slug": "quest-hunter",
    "version": "1.0.0",
    "scheme": "questhunter",
    "newArchEnabled": true,
    "experiments": {
      "typedRoutes": true,
      "reactCompiler": true
    }
  }
}

Key features:

New Architecture: Enabled for better performance
Typed Routes: Type-safe navigation with Expo Router
React Compiler: Experimental optimizations for React 19

Plugins

Quest Hunter uses these Expo plugins:

expo-router: File-based routing
expo-splash-screen: Custom splash screen with light/dark variants
expo-web-browser: OAuth redirects
expo-maps: Native map views with location permissions

Plugins are configured in app.json under the plugins array.

Project ID

The Expo Application Services (EAS) project ID is:

05cc8c91-3a53-4658-a58d-24ec09f5b51c

This ID links the local project to EAS for builds, updates, and submissions.

Troubleshooting

Location permissions not working

iOS: Check Settings > Quest Hunter > Location. Ensure “While Using the App” is selected.Android: Go to Settings > Apps > Quest Hunter > Permissions > Location. Enable “Allow only while using the app”.Web: Click the location icon in your browser’s address bar and select “Allow”.

Camera not opening

iOS: Check Settings > Quest Hunter > Camera is enabled.Android: Go to Settings > Apps > Quest Hunter > Permissions > Camera and enable it.Web: Ensure your browser supports the MediaDevices API and you’ve granted camera access.

Google sign-in fails

Maps not loading

Android: Verify the Google Maps API key is configured correctly in app.json.iOS: Check that location permissions are granted.Web: Ensure your browser supports geolocation API.If maps still don’t load, try:

Restarting the app
Checking your internet connection
Updating to the latest app version

Real-time sync issues

If quest progress doesn’t sync:

Check your internet connection
Verify Convex deployment is running
Try force-closing and reopening the app
Check if other real-time features work (quest list updates)

Convex uses WebSockets for real-time updates, so firewall or network restrictions may interfere.

Next steps

Complete your first quest

Follow the quickstart guide to start your first adventure

Learn about features

Explore all of Quest Hunter’s capabilities

API reference

View Convex queries and mutations for developers

Contributing

Submit issues or contribute to Quest Hunter development

For the best experience, enable both location and camera permissions before starting your first quest!

Get Started

Core Features

User Guide

Choose your platform

iOS

Android

Web

iOS installation

iOS-specific features

Android installation

Android-specific features

Web installation

Web-specific features

Development setup

Prerequisites

Clone and install

Run on devices

Development scripts

Configuration reference

Troubleshooting

Next steps

Complete your first quest

Learn about features

API reference

Contributing

Build docs developers (and LLMs) love

Get Started

Core Features

User Guide

​Choose your platform

iOS

Android

Web

​iOS installation

​iOS-specific features

​Android installation

​Android-specific features

​Web installation

​Web-specific features

​Development setup

​Prerequisites

​Clone and install

​Run on devices

​Development scripts

​Configuration reference

​Troubleshooting

​Next steps

Complete your first quest

Learn about features

API reference

Contributing

Build docs developers (and LLMs) love

Choose your platform

iOS installation

iOS-specific features

Android installation

Android-specific features

Web installation

Web-specific features

Development setup

Prerequisites

Clone and install

Run on devices

Development scripts

Configuration reference

Troubleshooting

Next steps