AudiOhm/frontend/INTEGRATION_CHECKLIST.md

Settings Page Integration Checklist

Setup Steps

1. Install Dependencies

cd frontend
flutter pub get

Required dependencies (already added to pubspec.yaml):

• ✅ package_info_plus: ^5.0.1
• ✅ image_picker: ^1.0.7
• ✅ shared_preferences: ^2.2.2 (already present)
• ✅ path_provider: ^2.1.2 (already present)

2. Platform Configuration

Android (android/app/src/main/AndroidManifest.xml)

Add these permissions inside <manifest> tag:

<!-- For image picker -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" android:minSdkVersion="33"/>

<!-- For cache management -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

iOS (ios/Runner/Info.plist)

Add these keys:

<key>NSPhotoLibraryUsageDescription</key>
<string>We need access to your photo library to let you select a profile picture.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>We need access to save photos to your library.</string>

3. Import the Settings Page

import 'package:spotify_le_2/presentation/pages/settings/settings_page.dart';

4. Add Navigation Route

Option A: Direct Navigation

// In your home page, profile button, etc.
onPressed: () {
  Navigator.push(
    context,
    MaterialPageRoute(
      builder: (context) => const SettingsPage(),
    ),
  );
}

Option B: Go Router

// In router configuration
GoRoute(
  path: '/settings',
  builder: (context, state) => const SettingsPage(),
),

Option C: Bottom Navigation

NavigationBar(
  destinations: const [
    NavigationDestination(icon: Icon(Icons.home), label: 'Home'),
    NavigationDestination(icon: Icon(Icons.search), label: 'Search'),
    NavigationDestination(icon: Icon(Icons.settings), label: 'Settings'),
  ],
  onDestinationSelected: (index) {
    if (index == 2) { // Settings tab
      // Navigate to settings or show as current page
    }
  },
)

5. Provider Setup (Already Done)

The settingsProvider is already set up in: frontend/lib/presentation/providers/settings_provider.dart

It automatically:

• Initializes SharedPreferences
• Loads settings on app start
• Watches AuthApiService for user data
• Persists all settings changes

6. Test the Integration

Manual Testing Checklist

Profile Section:

• Avatar displays correctly (default or from URL)
• Display name and email show
• Premium badge appears for premium users
• Edit Profile button opens dialog
• Display name can be edited
• Image picker opens (requires device/emulator)

Audio Quality:

• All four quality options display
• Selection works correctly
• Premium lock shows for non-premium users
• Settings persist after app restart

Playback Settings:

• Crossfade toggle works
• Duration slider appears when enabled
• Gapless playback toggle works
• Normalize volume toggle works
• All settings persist

Downloads:

• Mobile data toggle works
• Explicit content toggle works
• Settings persist after restart

Cache Management:

• Cache size displays (may show "0 MB" initially)
• Clear cache button works
• Confirmation dialog appears
• Success snackbar shows
• Cache size updates after clearing

About Section:

• App version displays correctly
• Licenses page opens
• License information loads

Logout:

• Logout button works
• Confirmation dialog appears
• User is logged out
• Redirected to login page

Error Handling:

• Network errors display
• Error messages are clear
• Error dismiss button works
• Retry possible

7. Optional Enhancements

Add Settings Icon to App Bar

AppBar(
  title: Text('Home'),
  actions: [
    IconButton(
      icon: Icon(Icons.settings),
      onPressed: () => Navigator.push(
        context,
        MaterialPageRoute(builder: (_) => const SettingsPage()),
      ),
    ),
  ],
)

Add Settings to Drawer Menu

Drawer(
  child: ListView(
    children: [
      DrawerHeader(...),
      ListTile(
        leading: Icon(Icons.settings),
        title: Text('Settings'),
        onTap: () {
          Navigator.pop(context); // Close drawer
          Navigator.push(
            context,
            MaterialPageRoute(builder: (_) => const SettingsPage()),
          );
        },
      ),
    ],
  ),
)

Add to User Profile Menu

PopupMenuButton<String>(
  onSelected: (value) {
    if (value == 'settings') {
      Navigator.push(
        context,
        MaterialPageRoute(builder: (_) => const SettingsPage()),
      );
    }
  },
  itemBuilder: (context) => [
    PopupMenuItem(value: 'settings', child: Text('Settings')),
  ],
)

8. Verification Commands

# Check if all files exist
ls -la frontend/lib/presentation/providers/settings_provider.dart
ls -la frontend/lib/presentation/pages/settings/settings_page.dart
ls -la frontend/lib/presentation/widgets/settings/*.dart

# Verify dependencies
flutter pub deps | grep -E "(package_info_plus|image_picker)"

# Run the app
flutter run

# Build for testing
flutter build apk --debug
flutter build ios --debug

9. Common Issues & Solutions

Issue: Image picker doesn't open

• Solution: Add permissions to AndroidManifest.xml and Info.plist
• Real device required (doesn't work on some emulators)

Issue: Cache size shows "Unknown"

• Solution: Normal on first launch or if no cache exists
• Cache will accumulate as app is used

Issue: Settings don't persist

• Solution: Ensure SharedPreferences is initialized
• Check for storage permissions on older Android versions

Issue: Premium features not unlocking

• Solution: Ensure backend correctly sets is_premium flag
• Check user data is loaded from API

Issue: Avatar upload doesn't work

• Solution: Server-side upload endpoint required
• Current implementation only selects local image
• Implement multipart/form-data upload on backend

10. Next Steps

1. Backend: Implement avatar upload endpoint
2. Testing: Test on real devices (iOS and Android)
3. Polish: Add loading skeletons during initial load
4. Analytics: Track settings changes
5. A/B Testing: Test default settings values
6. Documentation: Add user-facing help text
7. Localization: Add translations for all text

Support Files Created

• ✅ SETTINGS_PAGE_README.md - Complete implementation guide
• ✅ SETTINGS_PREVIEW.md - Visual design documentation
• ✅ settings_page_example.dart - Integration examples
• ✅ INTEGRATION_CHECKLIST.md - This file

Quick Reference

Files Created:

• frontend/lib/presentation/providers/settings_provider.dart
• frontend/lib/presentation/pages/settings/settings_page.dart
• frontend/lib/presentation/widgets/settings/settings_tile.dart
• frontend/lib/presentation/widgets/settings/profile_section.dart
• frontend/lib/presentation/widgets/settings/audio_quality_selector.dart
• frontend/lib/presentation/widgets/settings/cache_management_tile.dart
• frontend/lib/presentation/widgets/settings/edit_profile_dialog.dart

Import Path:

import 'package:spotify_le_2/presentation/pages/settings/settings_page.dart';

Provider Access:

final settingsState = ref.watch(settingsProvider);
final settingsNotifier = ref.read(settingsProvider.notifier);

Navigation:

Navigator.push(context, MaterialPageRoute(builder: (_) => const SettingsPage()));

---

All files created and ready for integration! 🚀