ADVANCED
Achievements
Track your inventory management progress with the achievement system — milestones, categories, legendary rewards and automatic progress tracking.
Overview
The Invenicum achievement system gamifies your inventory management experience by recognizing milestones and accomplishments. As you use the platform, you’ll unlock achievements that showcase your progress and expertise.
Achievement System
How Achievements Work
STEP 01
Monitors Activity
Tracks every action you perform in the app
STEP 02
Checks Conditions
Evaluates if achievement criteria are met
STEP 03
Unlocks Automatically
Awards achievements the moment you earn them
STEP 04
Persists to Cloud
Saves your achievement state securely
Future<void> fetchAchievements(BuildContext context) async {
_isLoading = true;
notifyListeners();
try {
// Get user progress from server
final List<Map<String, dynamic>> serverData =
await _service.getAchievements();
// Merge with static definitions (icons, text)
final staticDefs = AppAchievements.getDefinitions(context);
_achievements = staticDefs.map((staticDef) {
final serverMatch = serverData.firstWhere(
(s) => s['id'].toString() == staticDef.id,
orElse: () => {},
);
return AchievementDefinition(
id: staticDef.id,
title: staticDef.title,
desc: staticDef.desc,
icon: staticDef.icon,
category: staticDef.category,
isLegendary: staticDef.isLegendary,
unlocked: serverMatch['unlocked'] ?? false,
unlockedAt: serverMatch['unlockedAt'] != null
? DateTime.parse(serverMatch['unlockedAt'])
: null,
);
}).toList();
} finally {
_isLoading = false;
notifyListeners();
}
}Achievement Structure
Metadata
- Unique ID
- Title and description
- Category classification
- Legendary status
Progress
- Locked / Unlocked status
- Unlock timestamp
- Progress percentage (for tracked achievements)
Achievement Categories
General
Core milestones in using Invenicum
- Creating your first collection
- Adding your first item
- Completing your profile
- Using the mobile app
Collections
Collection management achievements
- Create multiple collections
- Set up collection goals
- Share collections with others
- Organize with custom fields
Items
Inventory item milestones
- Add specific quantities of items
- Use barcode scanning
- Attach images to items
- Complete detailed item info
Valuation
Value tracking progress
- Record purchase prices
- Track value changes over time
- Reach collection value milestones
- Use pricing integrations
Organization
Organizational achievements
- Use locations and containers
- Create custom asset types
- Implement tagging systems
- Set up hierarchical structures
Social
Community participation
- Share templates
- Publish plugins
- Help other users
- Contribute to marketplace
Legendary
Rare, difficult achievements — designed to be meaningful
Major milestones
1,000+ items
Perfect organization
100% completion
Community recognition
High download count
Long-term dedication
1+ year active
Viewing Achievements
Open Achievements
Navigate to Profile → Achievements.
View Progress
See your overall completion percentage at a glance:
int get unlockedCount => _achievements.where((a) => a.unlocked).length; double get progressPercentage => _achievements.isEmpty ? 0 : (unlockedCount / _achievements.length);
Browse Categories
Filter achievements by category to focus on specific areas of progress.
Check Details
Tap any achievement to see full information:
Achievement Cards
Unlocked
First Steps
Added your very first item to the inventory.
Unlocked · 15 Jan. 2025
Locked
Serious Collector
Reach 100 items in your inventory.
47 / 100
Legendary
Museum Curator
Reach 1,000 items in your inventory.
Unlocked · 3 Mar. 2026
Unlocking Achievements
Automatic Unlocking
Most achievements unlock automatically when you meet the criteria. The backend handles everything silently:
Future<void> triggerAction(
String actionType, dynamic value) async {
try {
await _dio.post('/achievements/check', data: {
'action': actionType,
'value': value,
});
} catch (e) {
// Silent error to not interrupt UX
}
}Manual Checks
Force a status refresh when needed:
Future<void> checkAchievementsStatus(
BuildContext context) async {
await fetchAchievements(context);
}Use after:
Achievement Types
Threshold Achievements
Unlocked when reaching specific numbers
First Steps
Add your first item
Growing Collection
Reach 10 items
Serious Collector
Reach 100 items
Museum Curator
Reach 1,000 items
Legendary Archive
Reach 10,000 items
Action Achievements
Unlocked by performing specific actions
Photographer
Add an image to an item
Scanner
Use barcode scanning
Organizer
Create a location hierarchy
Valuation Expert
Track price changes
Collaborator
Share a collection
Time-Based Achievements
Unlocked based on duration or dates
Dedicated User
Use app 7 days in a row
Monthly Regular
Use app every month for 6 months
Anniversary
Use app for 1 year
Early Adopter
Create account in the first month
Completionist Achievements
Unlocked by finishing comprehensive tasks
Profile Complete
Fill all profile fields
Collection Master
Complete all fields for every item
Full Documentation
Add images to all items
Perfect Organization
Assign locations to all items
Social Achievements
Unlocked through community interaction
Template Publisher
Publish a template
Plugin Creator
Create a plugin
Community Helper
Template downloaded 100 times
Popular Creator
Plugin used by 50+ users
Achievement Progress Tracking
Progress Indicators
Some achievements show progress before unlocking:
// Track progress toward "100 Items" achievement final currentCount = 47; final requiredCount = 100; final progress = currentCount / requiredCount; // 0.47 → 47%
Formatted Dates
Unlock dates are displayed in user-friendly format:
String getFormattedDate(String achievementId) {
try {
final ach = _achievements
.firstWhere((a) => a.id == achievementId);
if (ach.unlockedAt == null) return '';
return DateFormat.yMMMd().format(ach.unlockedAt!);
} catch (e) {
return '';
}
}
// Example output: "24 Feb. 2024"Achievement Model
class AchievementDefinition {
final String id;
final String title;
final String desc;
final IconData icon;
final String category;
final bool isLegendary;
final bool unlocked;
final DateTime? unlockedAt;
const AchievementDefinition({
required this.id,
required this.title,
required this.desc,
required this.icon,
this.category = 'general',
this.isLegendary = false,
this.unlocked = false,
this.unlockedAt,
});
}Best Practices
Natural Progression
Don't focus too heavily on achievements. Let them unlock naturally as you use Invenicum effectively.
Quality Over Quantity
Rather than rushing to unlock achievements, focus on organizing your inventory well.
Explore Features
Achievements highlight app features you might not have discovered yet — use them as a guide.
Share Success
Legendary achievements are worth celebrating with the community!
Tips for Achievement Hunters
Start with Basics
- Complete your profile
- Create your first collection
- Add your first items
- Upload your first images
- Set up basic organization
Explore All Features
- Try barcode scanning
- Set up integrations
- Use locations and containers
- Create custom fields
- Share with others
Be Consistent
- Open the app daily
- Make incremental progress
- Update collections regularly
- Engage with community
Quality Documentation
- Add images to all items
- Fill custom fields completely
- Write detailed descriptions
- Organize with locations
Legendary Achievements
The most prestigious milestones — rare and meaningful
Legendary achievements often require significant dedication, major milestones, or exceptional contributions. They’re designed to be rare and meaningful.
Characteristics
- Difficult criteria (e.g. 10,000+ items)
- Long-term commitment required
- Significant community contribution
- Perfect completion metrics
- Rare circumstances or timing
Special Recognition
- Golden border and effects
- Profile badge display
- Community leaderboard presence
- Exclusive features or cosmetics (future)
Troubleshooting
Achievement Not Unlocking
- 1. Refresh — pull down on the achievements screen to sync
- 2. Check Criteria — verify you’ve actually met all requirements
- 3. Wait — some achievements have a brief processing delay
- 4. Reconnect — ensure you have internet connectivity
- 5. Contact Support — report it if the issue persists
Progress Not Updating
- 1. Force Refresh — use the manual refresh button
- 2. Check Sync — ensure data has synced to cloud
- 3. Restart App — close and reopen the application
- 4. Verify Data — confirm your actions are being recorded
Missing Achievements
- 1. Update App — ensure you have the latest version
- 2. Check Category — look in the correct category filter
- 3. Feature Access — some achievements require specific features or integrations
- 4. Account Status — verify your account is in good standing
Future Achievement Updates
The achievement system is regularly updated with:
Stay tuned for announcements about new achievements!
Next Steps
Custom Fields
Section complete