bubble_accessibility #

A Flutter plugin that shows a draggable floating bubble when your app is backgrounded or killed. Tap the bubble to re-open the app. Incoming notifications stream through to Dart so you can decide exactly what to do.

Works on all Android versions ≥ 5.0 (API 21+) via two independent permission modes:

Mode	Permission needed	Works without user granting the other
`accessibilityService`	Accessibility Service	✅
`foregroundService`	Display over other apps	✅
`auto` (default)	Either one	✅ uses whichever is available

Features #

🫧 Draggable, styled bubble with configurable size, colour, and icon
⚡ Zero host-app boilerplate — manifest and Kotlin merge automatically
🔔 Stream notification payloads (title, text, extras) to Dart
🖱️ Stream bubble tap events to Dart
🛣️ Custom tap intents: open a specific route or send any Android intent
⏱️ Optional auto-open with configurable delay on notification arrival
🔧 Two independent permission modes (accessibility or foreground service)
📦 Works on Android 5.0+ (API 21+)

Installation #

dependencies:
  bubble_accessibility: ^0.1.1

That's it. No Android file edits, no AndroidManifest.xml changes, no Kotlin.

Quick Start #

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await BubbleAccessibility.configure(); // defaults are fine

  runApp(MyApp());
}

Then ask the user to enable the permission (once):

// Check and prompt
final enabled = await BubbleAccessibility.isEnabled;
if (!enabled) {
  await BubbleAccessibility.openSettings(); // opens the right screen automatically
}

The bubble appears as soon as the user presses Home or switches apps, and disappears when they return.

Configuration #

Call configure() once before runApp (calling it again at any time updates live config):

await BubbleAccessibility.configure(
  const BubbleConfig(
    // ── Permission mode ──────────────────────────────────────────────
    mode: BubbleMode.auto,           // auto | accessibilityService | foregroundService

    // ── Style ────────────────────────────────────────────────────────
    sizeDp: 62,
    backgroundColor: 0xFF2196F3,     // ARGB colour int
    iconDrawableName: null,          // null = app launcher icon; or "my_drawable"
    closeButtonColor: 0xFFE53935,
    showCloseButton: true,
    initialPosition: BubblePosition(x: 20, y: 300),

    // ── Notification auto-open ────────────────────────────────────────
    autoOpenOnNotification: true,    // open app when notification arrives
    autoOpenDelayMs: 1500,           // delay before opening (ms)

    // ── Custom tap intent ─────────────────────────────────────────────
    tapIntent: BubbleIntent(
      route: '/home',                // passed as 'route' extra
      extras: {'tab': 'chat'},       // any additional String extras
    ),

    // ── Foreground-service status-bar notification ────────────────────
    persistentNotificationTitle: 'My App',
    persistentNotificationText: 'Running in background',
    persistentNotificationChannelId: 'my_bubble_channel',
    persistentNotificationChannelName: 'Bubble Overlay',
  ),
);

Receiving Notifications #

Listen to BubbleAccessibility.onNotification to receive notification payloads while your app is backgrounded:

BubbleAccessibility.onNotification.listen((BubbleNotification n) {
  print('${n.title} — ${n.text}');

  // Route based on data
  if (n.extras['type'] == 'chat') {
    openChatScreen();
  }
});

Set autoOpenOnNotification: false to handle navigation yourself instead of auto-opening.

Bubble Tap Events #

BubbleAccessibility.onBubbleTap.listen((_) {
  print('User tapped the bubble');
});

Manual Control #

await BubbleAccessibility.show(); // show manually
await BubbleAccessibility.hide(); // hide manually

Permissions #

Mode: `accessibilityService` (no overlay needed) #

User opens Settings → Accessibility → Downloaded apps → Your App.
Toggles the service on.

await BubbleAccessibility.openAccessibilitySettings();

Mode: `foregroundService` (overlay permission) #

User opens Settings → Apps → Your App → Display over other apps.
Toggles it on.

await BubbleAccessibility.openOverlaySettings();

Mode: `auto` (recommended) #

Opens the appropriate screen automatically:

await BubbleAccessibility.openSettings();

Check permissions at runtime #

final accOk     = await BubbleAccessibility.isAccessibilityEnabled;
final overlayOk = await BubbleAccessibility.isOverlayPermissionGranted;
final anyOk     = await BubbleAccessibility.isEnabled; // respects current mode

API Reference #