react-native-launcher-kit

This is a React Native package for Android that provides a set of helper functions for launching apps and interacting with the launcher. It works with automatic linking on React Native versions 0.60 and higher. For older versions, manual linking is required.

Installation

npm install react-native-launcher-kit

or

yarn add react-native-launcher-kit

If you're using React Native 0.60 or higher, the package will be automatically linked for you. For older versions, you need to manually link the package.

1. In your project directory, run the following command:

react-native link react-native-launcher-kit

2. Open the android/app/build.gradle file in your project and add the following line to the dependencies section:

implementation
project(':react-native-launcher-kit')

3. Open the MainApplication.java file in your project and add the following import statement:

import com.launcherkit;

4. Add the package to the list of packages in the getPackages() method:

protected List<ReactPackage> getPackages(){
  return Arrays.asList(
  new MainReactPackage(),
  new LauncherKit() // <-- Add this line
  );
  }

Features

The features of the React Native Launcher Kit include:

1. Get all installed apps (sorted and unsorted).
2. Get the current default launcher.
3. Get the current battery percentage and whether the phone is charging or not.
4. Check if a package (bundle ID) is installed.
5. Open system settings.
6. Open "Set as default launcher" screen directly.
7. Open an app using its bundle ID with custom params.
8. Open the alarm app directly.
9. Listen for app installations and removals.
10. Get app version and color accent for each app on the installed app list.

❤️ Love this project? Consider supporting its development!

Important Note

Starting with Android 11 (API level 30), you need to add the following permission to your AndroidManifest.xml file to query package information:

<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"/>

Important Note: Google Play Store has specific policies regarding the use of QUERY_ALL_PACKAGES permission. Your app must have a core functionality that requires querying installed apps to use this permission. You may need to provide justification during the app review process. Make sure your app's use case complies with the Google Play Policy.

This permission is required for the following features in this package:

• Getting installed apps list
• Checking if a specific package is installed
• Listening for app installations and removals

Demo

Breaking History

2.1.0

Enhanced Launch Parameters:

🚀 Launch Parameter Support

• Added structured launch parameters for better app launching
• Introduced IntentAction and MimeType enums
• Enhanced type safety with LaunchParams interface

2.0.0

Breaking Changes:

🚀 Performance Optimization

• Changed getApps and getSortedApps to return Promises
• Apps are now loaded on-demand when calling getInstalledApps instead of at app startup
• This change dramatically improves initial app launch performance

🔄 API Changes

• Icon property now returns file path instead of base64 string
• Added new GetAppsOptions interface for configurable app queries
• Added support for custom parameters in launchApplication
• Moved QUERY_ALL_PACKAGES permission requirement to user's AndroidManifest.xml

  Previously this was included in the package's manifest, now users need to add it manually if their app requires querying all packages

✨ New Features

• App version and accent color support in getApps and getSortedApps
• New app installation listener with startListeningForAppInstallations
• New app removal listener with startListeningForAppRemovals

1.0.0

First release

Methods

1. getApps(options: GetAppsOptions): Promise<AppDetail[]>

Returns an array of all installed apps on the device with optional version and accent color.

import { InstalledApps } from 'react-native-launcher-kit';

const result = await InstalledApps.getApps({ includeVersion: true, includeAccentColor: true });

2. getSortedApps(options: GetAppsOptions): Promise<AppDetail[]>

Returns an array of all installed apps on the device, sorted alphabetically by app label, with optional version and accent color.

import { InstalledApps } from 'react-native-launcher-kit';

const result = await InstalledApps.getSortedApps({ includeVersion: true, includeAccentColor: true });

AppDetail Interface

interface AppDetail {
  label: string;
  packageName: string;
  icon: string;
  version?: string;
  accentColor?: string;
}

GetAppsOptions Interface

interface GetAppsOptions {
  includeVersion: boolean;
  includeAccentColor: boolean;
}

Note:

• The icon property will now return the file path of the icon image instead of the base64 encoded string as in previous versions.
• The accentColor property provides the dominant color of the app's icon for easy UI theming.

3. Enhanced App Launching launchApplication

Basic App Launch

import { RNLauncherKitHelper } from 'react-native-launcher-kit';

// Simple app launch
RNLauncherKitHelper.launchApplication('com.example.app');

Launch with Parameters

Google Maps Examples

import { RNLauncherKitHelper, IntentAction } from 'react-native-launcher-kit';
// Open specific location
RNLauncherKitHelper.launchApplication('com.google.android.apps.maps', {
  action: IntentAction.VIEW,
  data: `geo:40.7580,-73.9855?q=40.7580,-73.9855(Times Square)&z=16`
});

// Start navigation
RNLauncherKitHelper.launchApplication('com.google.android.apps.maps', {
  action: IntentAction.VIEW,
  data: `google.navigation:q=48.8584,2.2945&mode=driving`
});

Browser Examples

import { RNLauncherKitHelper, IntentAction } from 'react-native-launcher-kit';
// Open URL in Chrome
RNLauncherKitHelper.launchApplication('com.android.chrome', {
  action: IntentAction.VIEW,
  data: 'https://www.youtube.com'
});

Intent Actions

Available intent actions for enhanced app launching:

enum IntentAction {
  MAIN = 'android.intent.action.MAIN',
  VIEW = 'android.intent.action.VIEW',
  SEND = 'android.intent.action.SEND'
}

MIME Types

Common MIME types for content handling:

enum MimeType {
  ALL = '*/*',
  GENESIS_ROM = 'application/x-genesis-rom',
  PSX_ROM = 'application/x-playstation-rom',
  PDF = 'application/pdf',
  TEXT = 'text/plain',
  HTML = 'text/html'
}

Launch Parameters Interface

interface LaunchParams {
  action?: IntentAction | string;
  data?: string;
  type?: MimeType | string;
  extras?: Record;
}

Important Notes

• The enums (IntentAction and MimeType) are optional helpers
• You can use any valid Android intent action string directly
• You can use any valid MIME type string directly
• The extras object accepts any key-value pairs needed by the target app
• Always check if the target app is installed before launching

4. checkIfPackageInstalled: Promise<boolean>

Checks if an app with the given bundle ID is installed on the device.

import { RNLauncherKitHelper } from 'react-native-launcher-kit';

const result = await RNLauncherKitHelper.checkIfPackageInstalled(
  'com.android.settings',
);
console.log(result); // true or false.

5. getDefaultLauncherPackageName: Promise<string>

Checks the default launcher app on the device.

import { RNLauncherKitHelper } from 'react-native-launcher-kit';

const result = await RNLauncherKitHelper.getDefaultLauncherPackageName();
console.log(result);

6. openSetDefaultLauncher: Promise<boolean>

Opens the "Set Default Launcher" screen on the device.

import { RNLauncherKitHelper } from 'react-native-launcher-kit';

const result = await RNLauncherKitHelper.openSetDefaultLauncher();
console.log(result); // true or false.

7. getBatteryStatus: Promise<BatteryStatus>

Returns the current battery status of the device and if the phone is currently charging or not.

import { RNLauncherKitHelper } from 'react-native-launcher-kit';

const result = await RNLauncherKitHelper.getBatteryStatus();
console.log(result); // {"isCharging": false, "level": 100}

BatteryStatus Interface

interface AppDetail {
  level: number;
  isCharging: boolean;
}

8. openAlarmApp: boolean

Opens the default alarm app on the device.

import { RNLauncherKitHelper } from 'react-native-launcher-kit';

const result = await RNLauncherKitHelper.getBatteryStatus();
console.log(result);

9. goToSettings

Opens the settings screen of the device.

import { RNLauncherKitHelper } from 'react-native-launcher-kit';

RNLauncherKitHelper.goToSettings();

10. Start listening for new App installations

Listens for app installations and provides app details when an app is installed.

import { InstalledApps } from 'react-native-launcher-kit';
import { useEffect, useState } from 'react';

const App = () => {
  const [apps, setApps] = useState<AppDetail[]>([]);

  const initApp = async () => {
    const appsList = await InstalledApps.getApps({
      includeVersion: true,
      includeAccentColor: true,
    });
    setApps(appsList);
  }
  useEffect(() => {
    InstalledApps.startListeningForAppInstallations((app) => {
      setApps((prev) => [app, ...prev]);
    });

    return () => {
      InstalledApps.stopListeningForAppInstallations();
    };
  }, []);

  return (
    // Your component rendering logic
  );
};

11. Start listening for an App removal

Listens for app removals (uninstallations) and provides the package name when an app is removed.

import { InstalledApps } from 'react-native-launcher-kit';
import { useEffect, useState } from 'react';

const App = () => {
  const [apps, setApps] = useState<AppDetail[]>([]);

  const initApp = async () => {
    const appsList = await InstalledApps.getApps({
      includeVersion: true,
      includeAccentColor: true,
    });
    setApps(appsList);
  }
  useEffect(() => {
    InstalledApps.startListeningForAppRemovals((packageName) => {
      setApps((prev) =>
        prev.filter((item) => item.packageName !== packageName)
      );
    });

    return () => {
      InstalledApps.stopListeningForAppRemovals();
    };
  }, []);

  return (
    // Your component rendering logic
  );
};

Demo App

React-Native-Launcher-Kit has been utilized for testing purposes on a launcher known as NoPhoneLauncher. You can experience its functionality in real-time by accessing it on Google Play via the following link.

Example App

You can experience the functionality of the code by exploring the examples provided in our GitHub repository, which can be accessed from the following link.

License

MIT