Skip to main content
This quickstart assumes you already have Quest Hunter installed. If not, visit the installation guide first.
Get up and running with Quest Hunter in just a few minutes. This guide walks you through signing up, finding your first quest, and completing your first location.

​
Sign up and authenticate

1

Launch Quest Hunter

Open the Quest Hunter app on your device.
2

Sign in with Google

Tap Sign in with Google on the welcome screen. Quest Hunter uses Clerk for secure authentication.You’ll be redirected to Google’s OAuth consent screen. Authorize Quest Hunter to access your email and basic profile information.
3

Complete your profile

After authentication, your account is automatically created with your Google profile information (name, email, profile photo).
Quest Hunter uses Clerk for authentication, ensuring your credentials are secure and never stored directly in the app.

​
Browse and discover quests

1

Open the Quests tab

After signing in, you’ll land on the Quests screen, which shows three tabs:
  • Empfohlen (Recommended) - All available quests you haven’t completed yet
  • Neu (New) - Recently added quests from the last 7 days
  • Fertig (Done) - Your completed quests
2

Browse available quests

Scroll through the recommended quests. Each quest card displays:
  • Quest name and image
  • Category (adventure, history, culture, nature, food, drink)
  • Difficulty level (easy, medium, hard)
  • Estimated completion time
  • XP reward
3

Select a quest

Tap any quest card to view its detailed information, including:
  • Full description
  • All location checkpoints
  • Map preview of locations
  • Quest requirements
Start with an “einfach” (easy) difficulty quest for your first experience. These typically have fewer locations and are designed to be completed quickly.

​
Start your first quest

1

Review quest details

On the quest detail screen, review:
  • The quest description and objectives
  • Number of locations to visit
  • Estimated time to complete
  • XP you’ll earn upon completion
2

Start the quest

Tap the Quest starten (Start quest) button. This creates a userQuest record tracking your progress.
// Behind the scenes
await ctx.db.insert("userQuests", {
  userId: user._id,
  questId: questId,
  startedAt: Date.now(),
});
3

View locations

You’ll see all quest locations displayed in order. The map shows each checkpoint with its coordinates.

​
Complete your first location

1

Navigate to the location

Tap the first location to open its detail screen. You’ll see:
  • Location name and description
  • Interactive map with GPS coordinates
  • Distance from your current position
  • Navigation button
2

Travel to the checkpoint

Use the navigation feature or your preferred maps app to reach the location. The map updates in real-time as you move.
3

Take a verification photo

When you arrive at the location:
  1. Tap the Foto aufnehmen (Take photo) button
  2. Grant camera permissions if prompted
  3. Capture a photo of the location
  4. Review and confirm the photo
The photo is uploaded to Convex storage for verification:
// Upload flow
const uploadUrl = await convex.mutation(api.locations.generateUploadUrl);
const result = await fetch(uploadUrl, {
  method: "POST",
  body: photoBlob,
});
const { storageId } = await result.json();
4

Complete the location

After uploading your photo, tap Standort abschliessen (Complete location). The app validates:
  • You’ve started the quest
  • The location belongs to this quest
  • You haven’t already completed this location
  • The photo was successfully uploaded
await convex.mutation(api.locations.complete, {
  questId,
  locationId,
  photoStorageId: storageId,
});
Your location completion is immediately synced to Convex, so your progress is saved even if you close the app.

​
Continue and complete the quest

1

Visit remaining locations

Repeat the photo verification process for each remaining location in the quest. You can complete locations in any order, though they’re numbered for suggested routing.
2

Track your progress

The quest detail screen shows which locations you’ve completed with checkmarks. Your progress is saved in real-time.
3

Complete the quest

After completing all locations, the app automatically validates your quest completion:
const [questLocations, completedLocations] = await Promise.all([
  ctx.db.query("locations").withIndex("by_quest", q => q.eq("questId", questId)).collect(),
  ctx.db.query("userLocations").withIndex("by_user_and_quest", q => 
    q.eq("userId", user._id).eq("questId", questId)
  ).collect(),
]);

// Verify all locations are completed
if ([...requiredIds].some((id) => !completedIds.has(id)))
  throw new ConvexError("Quest not finished");

// Mark quest complete
await ctx.db.patch(userQuest._id, { completedAt: Date.now() });
4

Earn your XP

You’ll see a completion dialog showing:
  • XP earned
  • Quest completion time
  • Photos you captured
Your total XP is updated and the quest moves to your Fertig (Done) tab.

​
Next steps

Explore quest categories

Learn about different quest types and how to find quests that match your interests

Track your progress

Understand the XP system and how to view your quest statistics

Location features

Deep dive into GPS tracking and photo verification

User guide

Complete guide to all Quest Hunter features
Quest categories:
  • abenteuer - Adventure quests
  • geschichte - Historical quests
  • kultur - Cultural experiences
  • natur - Nature exploration
  • essen - Culinary quests
  • trinken - Beverage tours
Difficulty levels:
  • einfach - Easy (fewer locations, shorter time)
  • mittel - Medium (moderate complexity)
  • schwer - Hard (many locations, longer quests)
Quest states:
  • Not Started - Available in Recommended/New tabs
  • In Progress - Started but not all locations completed
  • Completed - All locations verified and XP awarded

Build docs developers (and LLMs) love

Get started for freeTalk to us