Self Launcher Package

A lightweight Flutter plugin that enables Android apps to bring themselves to the foreground or reopen when closed. Simple, minimal, and focused on core app launching functionality.

Features

  • ✅ Bring app to foreground when running in background
  • ✅ Reopen app when completely closed
  • ✅ Zero permissions required - Uses only standard Android intents
  • ✅ Lightweight implementation with minimal code
  • ✅ Modern Flutter plugin architecture with null safety

Requirements

  • Flutter SDK: >=3.13.0
  • Dart SDK: >=3.1.0 <4.0.0
  • Android: API level 21+ (Android 5.0+)
  • Target SDK: 34 (Android 14)

Installation

Add this package to your pubspec.yaml:

dependencies:
  self_launcher: ^1.0.0

Run:

flutter pub get

Android Setup

No additional setup required! The plugin uses standard Android intents that don't require special permissions.

Usage

Quick Start

import 'package:self_launcher/self_launcher.dart';

// Simple one-liner to bring app to foreground
final success = await SelfLauncher.bringToForeground();

Basic Example with Error Handling

import 'package:self_launcher/self_launcher.dart';

// Bring app to foreground or reopen if closed
try {
  final success = await SelfLauncher.bringToForeground();
  if (success) {
    print('App brought to foreground successfully!');
  } else {
    print('Failed to bring app to foreground');
  }
} catch (e) {
  print('Error: $e');
}

Complete Example

import 'package:flutter/material.dart';
import 'package:self_launcher/self_launcher.dart';

class LaunchButton extends StatefulWidget {
  @override
  _LaunchButtonState createState() => _LaunchButtonState();
}

class _LaunchButtonState extends State<LaunchButton> {
  bool _isLoading = false;
  String _message = '';

  Future<void> _bringToForeground() async {
    setState(() {
      _isLoading = true;
      _message = '';
    });

    try {
      final success = await SelfLauncher.bringToForeground();
      setState(() {
        _message = success 
          ? 'App brought to foreground successfully!' 
          : 'Failed to bring app to foreground';
      });
    } catch (e) {
      setState(() {
        _message = 'Error: $e';
      });
    } finally {
      setState(() {
        _isLoading = false;
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        ElevatedButton(
          onPressed: _isLoading ? null : _bringToForeground,
          child: _isLoading 
            ? CircularProgressIndicator()
            : Text('Bring to Foreground'),
        ),
        if (_message.isNotEmpty)
          Padding(
            padding: EdgeInsets.all(16),
            child: Text(_message),
          ),
      ],
    );
  }
}

API Reference

Methods

SelfLauncher.bringToForeground()

Brings the app to the foreground if it's running in the background, or reopens it if it's completely closed.

  • Returns: Future<bool> - true if successful, false otherwise
  • Throws: PlatformException if there's an error launching the app

Example:

final success = await SelfLauncher.bringToForeground();
if (success) {
  // App is now in foreground
}

How It Works

The plugin uses Android's standard PackageManager.getLaunchIntentForPackage() method to get the app's launch intent, then starts the activity with appropriate flags:

  • FLAG_ACTIVITY_NEW_TASK: Allows starting from non-activity context
  • FLAG_ACTIVITY_CLEAR_TOP: Brings existing activity to front
  • FLAG_ACTIVITY_SINGLE_TOP: Prevents creating duplicate activities

This approach is reliable, lightweight, and doesn't require any special permissions.

Testing Your Implementation

Manual Testing Steps

  1. Background Test:

    • Open your app
    • Tap the "Bring to Foreground" button
    • Press the home button to minimize the app
    • Tap the button again - app should come to foreground

  2. Closed App Test:

    • Open your app
    • Completely close the app (swipe away from recent apps)
    • Use a timer or external trigger to call bringToForeground()
    • App should reopen and come to foreground

  3. Integration Test:

    testWidgets('SelfLauncher brings app to foreground', (WidgetTester tester) async {
  // Test your implementation
  final result = await SelfLauncher.bringToForeground();
  expect(result, isTrue);
});

Common Use Cases

Timer-based Foreground

// Bring app to foreground after a delay
Timer(Duration(seconds: 10), () async {
  await SelfLauncher.bringToForeground();
});

Background Task Completion

// Bring app to foreground when background work is done
void onBackgroundTaskComplete() async {
  final success = await SelfLauncher.bringToForeground();
  if (success) {
    // Show results to user
    showCompletionDialog();
  }
}

Push Notification Handler

// Bring app to foreground when notification is tapped
void onNotificationTap() async {
  await SelfLauncher.bringToForeground();
  // Navigate to specific screen
  Navigator.pushNamed(context, '/notification-details');
}

Platform Support

Platform Support Notes
Android ✅ Full support API level 21+ (Android 5.0+)
iOS ❌ Not supported iOS doesn't allow apps to bring themselves to foreground
Web ❌ Not applicable Browser security restrictions
Desktop ❌ Not implemented Could be added in future versions

Troubleshooting

App doesn't come to foreground

  • Ensure your app is not being killed by aggressive battery optimization
  • Check that the app package name is correct
  • Verify the app is properly installed

Permission errors

  • This plugin doesn't require any special permissions
  • If you see permission errors, they might be from other plugins

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Libraries

self_launcher