Permissions

The fluxy_permissions module provides a centralized, reactive engine for managing system permissions without writing platform-specific boilerplate.

[GUIDE] Industrial Step-by-Step

1. Installation (via CLI)

Add the permissions module using the Fluxy CLI to maintain architectural integrity.

fluxy module add permissions

2. Managed Boot Sequence

Ensure your main.dart is configured with the mandatory three-step boot sequence.

import 'package:fluxy/fluxy.dart';
import 'core/registry/fluxy_registry.dart'; 

void main() async {
  await Fluxy.init();
  Fluxy.registerRegistry(() => registerFluxyPlugins()); 
  Fluxy.autoRegister(); // Boots permission watcher and engine
  runApp(MyApp());
}

3. Usage (Unified API)

Access the module through the stable Fx.platform gateway.

// Request single permission
final status = await Fx.platform.permissions.request(FluxyPermission.camera);

// Reactive Status Watching
Fx(() {
  final status = Fx.platform.permissions.statusOf(FluxyPermission.camera).value;
  return Fx.text("Camera Status: ${status.name}");
});

Core Functionality

1. Batch Requests

Request multiple necessary permissions at once. Fluxy provides a clean map-based response.

final results = await Fx.platform.permissions.requestAll([
  FluxyPermission.notification,
  FluxyPermission.location,
]);

2. Zero-Config Manifests (Android)

Fluxy's build engine automatically injects required XML entries (e.g., Internet, Notifications) into your AndroidManifest.xml during compilation.

The Wrong Way vs. The Right Way

Pitfalls & Troubleshooting

1. "Request returns denied without showing a popup"

• The Cause: The user previously selected "Don't ask again" or permanently denied.
• The Fix: Use openSettings() to guide them to manually enable it.

2. "Status signal doesn't update when I change settings"

• The Cause: Lack of an AppResume observer.
• The Fix: Fluxy automatically refreshes permissions when the app resumes. Ensure UI is in Fx().

3. "The Android Manifest entry is missing"

• The Cause: Manual manifest editing forgotten.
• The Fix: Use the Fluxy CLI to add modules—it handles injection automatically.

Upcoming CLI Features

In future releases, the Fluxy CLI will provide automated manifest synchronization to prevent "Missing Permission" errors during development.

1. Architectural Health Check

Run a deep scan of your platform requirements against your native manifests (Android/iOS).

fluxy doctor --fix

2. Manual Permission Sync

Automatically inject missing <uses-permission> tags or Info.plist keys based on your installed Fluxy modules.

fluxy permissions sync

Best Practices

1. Contextual Requests: Ask for permissions only when the user triggers a feature (e.g., Camera inside the scan view).
2. Handle "Permanently Denied": Use openSettings() to guide users if they have denied multiple times.
3. Use the Watcher: Leverage statusOf().listen() in your controllers to adjust background service behavior.