Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/louaysleman/react-native-launcher-kit

React Native Launcher Kit is a comprehensive package for building launchers in React Native.
https://github.com/louaysleman/react-native-launcher-kit

android launcher reactnative

Last synced: 6 months ago
JSON representation

React Native Launcher Kit is a comprehensive package for building launchers in React Native.

Awesome Lists containing this project

README 

          
# 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



```sh

npm install react-native-launcher-kit

```

or

```sh

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.



  Manual Linking



  



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



```sh

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:



```typescript

implementation

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

```



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



```java

import com.launcherkit;

```



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



```java

protected List 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!**



  

    Become a Patron

  




## 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:



```xml



 ```

**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](https://github.com/louaySleman/react-native-launcher-kit/releases/tag/2.1.0)

**Enhanced Launch Parameters:**



🚀 **Launch Parameter Support**

- Added structured launch parameters for better app launching

- Introduced [`IntentAction`](#intent-actions) and [`MimeType`](#mime-types) enums

- Enhanced type safety with [`LaunchParams`](#launch-parameters-interface) interface



### [2.0.0](https://github.com/louaySleman/react-native-launcher-kit/releases/tag/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](https://github.com/louaySleman/react-native-launcher-kit/releases/tag/1.0.4)

First release



## Methods



### 1. `getApps(options: GetAppsOptions): Promise`



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



```typescript

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



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

```



### 2. `getSortedApps(options: GetAppsOptions): Promise`



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



```typescript

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



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

```



#### `AppDetail Interface`



```typescript

interface AppDetail {

  label: string;

  packageName: string;

  icon: string;

  version?: string;

  accentColor?: string;

}

```

#### `GetAppsOptions Interface`



```typescript

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

```typescript

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



// Simple app launch

RNLauncherKitHelper.launchApplication('com.example.app');

```



#### Launch with Parameters



Google Maps Examples

```typescript

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

```typescript

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:

```typescript

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:

```typescript

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

```typescript

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`



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



```typescript

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



const result = await RNLauncherKitHelper.checkIfPackageInstalled(

  'com.android.settings',

);

console.log(result); // true or false.

```



### 5. `getDefaultLauncherPackageName: Promise`



Checks the default launcher app on the device.



```typescript

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



const result = await RNLauncherKitHelper.getDefaultLauncherPackageName();

console.log(result);

```



### 6. `openSetDefaultLauncher: Promise`



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



```typescript

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



const result = await RNLauncherKitHelper.openSetDefaultLauncher();

console.log(result); // true or false.

```



### 7. `getBatteryStatus: Promise`



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



```typescript

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



const result = await RNLauncherKitHelper.getBatteryStatus();

console.log(result); // {"isCharging": false, "level": 100}

```



#### `BatteryStatus Interface`



```typescript

interface AppDetail {

  level: number;

  isCharging: boolean;

}

```



### 8. `openAlarmApp: boolean`



Opens the default alarm app on the device.



```typescript

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



const result = await RNLauncherKitHelper.getBatteryStatus();

console.log(result);

```



### 9. `goToSettings`



Opens the settings screen of the device.



```typescript

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.



```jsx

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

import { useEffect, useState } from 'react';



const App = () => {

  const [apps, setApps] = useState([]);



  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.



```jsx

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

import { useEffect, useState } from 'react';



const App = () => {

  const [apps, setApps] = useState([]);



  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](https://nophonelauncher.canguru.au).



## 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](https://github.com/louaySleman/react-native-launcher-kit/tree/main/example).



## License



MIT