Achievements & Badges

Document Version: 1.0
Last Updated: January 2026
Audience: Youth Ministry Leaders, Church Administrators, Super Admins

---

Table of Contents

1. Overview
2. Achievement Structure
3. Creating Achievements
4. Auto-Award Configuration
5. Manual Award Process
6. XP System Management
7. Bulk Operations
8. Troubleshooting
9. Best Practices

---

Overview

Purpose

The Achievements system provides a gamified recognition framework that:

• Celebrates student milestones and spiritual growth
• Creates clear progression paths with tangible rewards
• Encourages consistent engagement through XP accumulation
• Enables leaders to recognize both automatic and manual accomplishments

Key Components

Component	Description
Badges	Visual representations of achievements
Color Levels	Tier system (White, Blue, Yellow, Gold)
XP Points	Experience currency earned through activities
Auto-Award	Automatic badge grants based on criteria
Manual Award	Leader-initiated badge grants
Scope	Visibility levels (Global, Church, Group)

---

Achievement Structure

Required Fields

Field	Type	Description	Validation
name	String	Achievement title	3-100 characters
description	String	What the achievement represents	10-500 characters
category	String	Grouping category	Required
colorLevel	Enum	Difficulty tier	White, Blue, Yellow, Gold
xpRequired	Number	XP value of achievement	1-10,000

Optional Fields

Field	Type	Description
badgeIcon	URL	Custom badge image
scope	Enum	Visibility level (default: church)
autoAward	Boolean	Enable automatic granting
criteriaType	Enum	Type of auto-award trigger
criteriaValue	Number	Threshold for auto-award

Color Level Guidelines

Level	XP Range	Use Case
White	10-50	First-time accomplishments, easy wins
Blue	51-150	Moderate effort, week-long goals
Yellow	151-400	Significant commitment, month-long goals
Gold	401-10,000	Elite achievements, exceptional dedication

---

Creating Achievements

Step-by-Step Process

1. Navigate to Achievement Management

• Access Admin Panel → Achievements
• Click “Create New Achievement”

1. Enter Basic Information

   Name: [Descriptive title, 3-100 chars]
   Description: [What student accomplished, 10-500 chars]
   Category: [Select or create category]

3. Set Difficulty Level

• Choose Color Level based on effort required
• Set appropriate XP value within tier range

3. Configure Scope

• Global: Available to all users (Super Admin only)
• Church: Available to your church members
• Group: Available to specific group only

3. Optional: Configure Auto-Award

• Toggle “Enable Auto-Award”
• Select criteria type
• Set criteria value threshold

3. Save Achievement

Category Recommendations

Category	Example Achievements
Scripture	Bible Reader, Verse Explorer, Book Completer
Memorization	First Words, Memory Champion, Walking Bible
Quizzes	Quiz Starter, Perfect Score, Quiz Master
Streaks	Daily Devotion, Weekly Warrior, Monthly Master
Community	Team Player, Group Leader, Fellowship Builder
Challenges	Challenge Accepted, Challenger, Champion
Special	Baptism, Camp Attendee, Mission Trip

---

Auto-Award Configuration

Available Criteria Types

Criteria Type	Trigger Event	Example Use
quiz_count	Quiz completion	“Complete 10 quizzes”
streak_days	Daily activity check	“7-day login streak”
verse_count	Verse read tracking	“Read 100 verses”
verse_memorized_count	Memorization completion	“Memorize 25 verses”
memorization_streak_days	Daily memorization	“14-day practice streak”
xp_total	XP accumulation	“Earn 1000 total XP”
plan_complete	Reading plan finish	“Complete 5 plans”
group_join	Group membership	“Join 3 groups”
manual	Leader-initiated	Custom awards

Trigger Events

The system checks for achievement eligibility when these events occur:

Event	Fires When
verse_read	Student reads scripture
quiz_complete	Quiz submitted
streak_update	Daily login detected
group_join	Student joins group
plan_complete	Reading plan finished
xp_update	XP points awarded
verse_memorized	Verse memorization completed
memorization_streak	Memorization streak updated
verse_verified	Leader verifies memorization

Configuration Example

Achievement: “Quiz Champion”

Name: Quiz Champion
Description: Complete 25 quizzes to prove your knowledge
Category: Quizzes
Color Level: Yellow
XP Required: 200
Auto-Award: Enabled
Criteria Type: quiz_count
Criteria Value: 25

---

Manual Award Process

When to Use Manual Awards

• Service projects and community involvement
• Leadership and mentorship activities
• Event attendance (camps, retreats, mission trips)
• Personal milestones (baptism, salvation)
• Custom recognition not trackable by system

Award Procedure

1. Locate Student

• Navigate to Members → Search student name
• Open student profile

1. Initiate Award

• Click “Award Achievement” button
• Select achievement from dropdown

1. Add Context (Optional)

• Enter award reason/note
• This appears in student’s achievement history

1. Confirm Award

• Review selection
• Click “Award” to grant

1. Notification

• Student receives in-app notification
• Achievement appears on their profile

Award Verification

For sensitive achievements:

• Document reason for award
• Consider requiring secondary approval
• Maintain consistency across similar situations

---

XP System Management

XP Award Events

Activity	Base XP	Notes
Daily login	5	Once per day
Verse read	10	Per verse
Quiz complete	15-50	Based on difficulty
Quiz perfect score	+25 bonus	Added to base
Verse memorized	25	Upon completion
Verified memorization	50	Leader confirmed
Challenge complete	20-100	Based on challenge
Reading plan day	10	Per day completed
Reading plan complete	30 bonus	On plan finish

User Level Progression

Level	XP Required	Streak Bonus
Bronze	0	–
Silver	100	3+ days
Gold	500	7+ days
Platinum	1,500	14+ days
Diamond	3,000	21+ days
Master	5,000	30+ days
Grandmaster	10,000	60+ days

XP Adjustments

Leaders can manually adjust XP through:

1. Navigate to student profile
2. Click “Adjust XP”
3. Enter adjustment amount (+/-)
4. Provide reason
5. Confirm change

---

Bulk Operations

Bulk Import Achievements

1. Prepare CSV File

   name,description,category,colorLevel,xpRequired,autoAward,criteriaType,criteriaValue
   "First Steps","Begin your journey",Basics,White,10,false,manual,0
   "Weekly Warrior","7-day streak",Streaks,Blue,100,true,streak_days,7

2. Import Process

• Navigate to Achievements → Import
• Upload CSV file
• Review parsed entries
• Confirm import

2. Validation

• System validates all fields
• Errors displayed for correction
• Partial imports possible

Bulk Award

For awarding achievements to multiple students:

1. Select students from member list
2. Choose “Bulk Actions” → “Award Achievement”
3. Select achievement
4. Add optional note
5. Confirm award to all selected

---

Troubleshooting

Common Issues

Issue	Cause	Solution
Auto-award not triggering	Criteria not met	Verify criteria value and type
Achievement not visible	Wrong scope	Check scope matches user’s church/group
Duplicate unlock attempts	Rapid triggers	System prevents duplicates automatically
XP not updating	Event not firing	Check activity triggers in logs
Badge image not showing	Invalid URL	Verify URL is accessible and correct format

Diagnostic Steps

1. Verify Achievement Configuration

• Check all required fields are set
• Confirm auto-award criteria is valid

1. Check User Eligibility

• Verify user hasn’t already unlocked
• Confirm user’s church/group matches scope

1. Review Trigger Events

• Confirm triggering activity occurred
• Check event logs for errors

1. Test Manually

• Award manually to verify achievement works
• If manual works, issue is with auto-award config

---

Best Practices

Achievement Design

1. Clear Names: Use action-oriented, descriptive titles
2. Achievable Goals: Mix easy and challenging achievements
3. Progressive Tiers: Create bronze/silver/gold versions of achievements
4. Visual Distinction: Use clear badge imagery
5. Meaningful Descriptions: Explain what the achievement represents

Engagement Strategies

1. Celebrate Publicly

• Announce achievements during gatherings
• Display leaderboards
• Create “Achievement of the Week” highlights

1. Create Urgency

• Seasonal/limited-time achievements
• Event-specific badges
• Countdown challenges

1. Social Elements

• Group achievements requiring collaboration
• Mentor/mentee paired achievements
• Team milestones

1. Surprise & Delight

• Hidden achievements discovered through exploration
• Random bonus XP events
• Unexpected recognition

Maintenance Schedule

Task	Frequency
Review unlock rates	Weekly
Adjust difficult achievements	Monthly
Create seasonal achievements	Quarterly
Archive unused achievements	Annually
Audit XP economy balance	Quarterly

---

Quick Reference

Achievement Creation Checklist

• [ ] Name (3-100 characters)
• [ ] Description (10-500 characters)
• [ ] Category selected
• [ ] Color level appropriate to difficulty
• [ ] XP value within tier range
• [ ] Scope correctly set
• [ ] Auto-award configured (if applicable)
• [ ] Badge icon uploaded (optional)
• [ ] Tested with sample user

Criteria Type Quick Reference

I want to award when…	Use Criteria Type
Student completes X quizzes	quiz_count
Student maintains X-day streak	streak_days
Student reads X verses	verse_count
Student memorizes X verses	verse_memorized_count
Student earns X total XP	xp_total
Student completes X reading plans	plan_complete
Student joins X groups	group_join
I want to award manually	manual

---

Support

For additional assistance:

• Review in-app help documentation
• Contact church administrator
• Submit support ticket for technical issues

---

This SOP should be reviewed and updated quarterly to reflect feature changes and ministry needs.