How to Build a User Achievement System with Badges in FlutterFlow

In Firestore, create a badge_definitions collection with fields: name (String — e.g., 'Workout Warrior'), description (String — 'Complete 10 workouts'), iconUrl (String — badge image URL), category (String — fitness, social, learning), criteria (Map with type: 'count', field: 'workouts_completed', threshold: 10), and order (Integer for display sorting). Add 5-8 badge definitions with varied thresholds: First Workout (threshold: 1), Workout Warrior (threshold: 10), Fitness Master (threshold: 50), Social Butterfly (5 posts), Knowledge Seeker (3 courses completed). Store badge images in Firebase Storage or use external icon URLs. Set Firestore rules: public read, admin-only write.

On each user document in the users collection, add counter fields that match your badge criteria fields: workouts_completed (Integer, default 0), posts_created (Integer, default 0), courses_completed (Integer, default 0). Create a subcollection users/{uid}/earned_badges with fields: badgeId (String — reference to badge_definitions doc), badgeName (String — denormalized), badgeIconUrl (String — denormalized), and earnedAt (Timestamp). These counters are incremented by Cloud Functions whenever the user completes a relevant action. The earned_badges subcollection records which badges the user has unlocked and when.

Deploy a Cloud Function triggered by Firestore onCreate on the workouts collection. When a new workout is created, the function: (1) reads the workout's userId, (2) increments the user's workouts_completed field by 1 using FieldValue.increment(1), (3) reads all badge_definitions where criteria.field == 'workouts_completed', (4) for each badge, checks if the user's new count >= badge threshold, (5) checks if the badge is already in the user's earned_badges subcollection, and (6) if the user just crossed the threshold and has not earned it yet, creates an earned_badge document and optionally creates a notification. Deploy similar functions for other event types (posts, courses). This server-side approach is secure — users cannot fake badge awards.

1// Cloud Function: onWorkoutCreated
2const functions = require('firebase-functions');
3const admin = require('firebase-admin');
4admin.initializeApp();
5
6exports.onWorkoutCreated = functions.firestore
7  .document('workouts/{workoutId}')
8  .onCreate(async (snap) => {
9    const userId = snap.data().userId;
10    const userRef = admin.firestore().collection('users').doc(userId);
11    // Increment counter
12    await userRef.update({
13      workouts_completed: admin.firestore.FieldValue.increment(1)
14    });
15    // Check badge criteria
16    const userDoc = await userRef.get();
17    const count = userDoc.data().workouts_completed;
18    const badges = await admin.firestore().collection('badge_definitions')
19      .where('criteria.field', '==', 'workouts_completed')
20      .where('criteria.threshold', '<=', count).get();
21    for (const badge of badges.docs) {
22      const existing = await userRef.collection('earned_badges')
23        .where('badgeId', '==', badge.id).get();
24      if (existing.empty) {
25        await userRef.collection('earned_badges').add({
26          badgeId: badge.id,
27          badgeName: badge.data().name,
28          badgeIconUrl: badge.data().iconUrl,
29          earnedAt: admin.firestore.Timestamp.now(),
30        });
31      }
32    }
33  });

Create a BadgesPage with a GridView (crossAxisCount: 3) bound to a Backend Query on badge_definitions ordered by order ascending. Also run a second Backend Query on users/{currentUser.uid}/earned_badges to get the user's earned badge IDs. For each badge in the grid, create a Container card with: an Image widget for the badge icon, a Text for the badge name, and conditional styling — if the badge ID exists in the earned badges list, show the image at full opacity with a gold border and a checkmark overlay; if not earned, apply 0.3 opacity (greyed out) with a lock Icon overlay. Use a Stack widget to layer the badge image, the lock/checkmark overlay, and optionally a CircularPercentIndicator at the bottom showing progress (e.g., currentCount / threshold). Tap an earned badge to show a BottomSheet with the full description and earned date.

For unearned badges, calculate progress by reading the user's counter field matching the badge's criteria.field and dividing by the threshold. Pass this to a CircularPercentIndicator (from the percent_indicator package) placed below each locked badge card. Set lineWidth to 4, radius to 20, progressColor to primary, and the center Text to the fraction (e.g., '7/10'). For badge award notifications, have the Cloud Function also create a document in users/{uid}/notifications with the badge name and a congratulatory message. On the DashboardPage or AppBar, show a pop-up celebration when a new badge is earned — query earned_badges where earnedAt > lastCheckedTime, and if any exist, show a custom SnackBar or Dialog with the badge image and 'Achievement Unlocked!' text.