react-native-my-app-list/README.md

Get user-facing installed apps for React Native Android using privacy-friendly queries instead of QUERY_ALL_PACKAGES permission.

# react-native-my-app-list

Get installed apps list for React Native Android applications. This package provides a simple and efficient way to retrieve information about user-facing installed applications on Android devices.

## Features

- ✅ Get list of user-facing installed applications
- ✅ Retrieve app name, package name, version name, and version code
- ✅ Android 11+ compatibility with privacy-friendly queries approach
- ✅ TypeScript support
- ✅ TurboModule implementation for better performance
- ✅ Uses intent queries instead of broad QUERY_ALL_PACKAGES permission
- ⚠️ Android only (iOS support planned for future releases)

## Installation

```sh
npm install react-native-my-app-list
```

## Android 11+ Permission Requirements

This package uses a **privacy-friendly approach** by leveraging Android's `<queries>` element instead of the broad `QUERY_ALL_PACKAGES` permission. This means:

- ✅ **No special Play Store review required**
- ✅ **Better user privacy**
- ✅ **Compliant with Android's package visibility guidelines**

### Automatic Configuration

The package automatically includes the necessary `<queries>` declarations to find user-facing apps such as:

- 📱 Launcher apps (apps with home screen icons)
- 🔗 Sharing-capable apps
- 🌐 Web browsers
- 📷 Camera apps
- 🖼️ Gallery/photo apps
- 🎵 Music/media apps

### Manual Configuration (Optional)

If you need to query specific apps beyond the default categories, you can add additional queries to your app's `android/app/src/main/AndroidManifest.xml`:

```xml
<queries>
    <!-- Query specific packages -->
    <package android:name="com.specific.app1" />
    <package android:name="com.specific.app2" />
    
    <!-- Query apps that handle specific intents -->
    <intent>
        <action android:name="com.custom.action" />
    </intent>
</queries>
```

## Important Note

This package returns **user-facing apps** rather than all system packages. This includes:
- Apps with launcher icons
- Apps that can handle common intents (sharing, browsing, etc.)
- User-installed apps
- System apps that are user-facing (like Camera, Gallery, etc.)

This approach provides better user experience and privacy compliance.

## Usage

```typescript
import { getInstalledApps, InstalledApp } from 'react-native-my-app-list';

// Get all installed apps
const fetchInstalledApps = async () => {
  try {
    const apps: InstalledApp[] = await getInstalledApps();
    console.log('Installed apps:', apps);
    
    // Each app object contains:
    // {
    //   packageName: string,    // e.g., "com.example.app"
    //   appName: string,        // e.g., "Example App"
    //   versionName: string,    // e.g., "1.2.3"
    //   versionCode: number,    // e.g., 123
    //   isSystemApp: boolean    // e.g., true for system apps, false for user-installed
    // }
  } catch (error) {
    console.error('Error fetching apps:', error);
  }
};
```

### React Component Example

```typescript
import React, { useState, useEffect } from 'react';
import { View, Text, FlatList, Alert } from 'react-native';
import { getInstalledApps, InstalledApp } from 'react-native-my-app-list';

const AppListScreen = () => {
  const [apps, setApps] = useState<InstalledApp[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    loadApps();
  }, []);

  const loadApps = async () => {
    try {
      const installedApps = await getInstalledApps();
      setApps(installedApps);
    } catch (error) {
      Alert.alert('Error', `Failed to load apps: ${error}`);
    } finally {
      setLoading(false);
    }
  };

  const renderApp = ({ item }: { item: InstalledApp }) => (
    <View style={{ padding: 10, borderBottomWidth: 1 }}>
      <Text style={{ fontWeight: 'bold' }}>{item.appName}</Text>
      <Text>{item.packageName}</Text>
      <Text>Version: {item.versionName} ({item.versionCode})</Text>
    </View>
  );

  return (
    <View style={{ flex: 1 }}>
      <FlatList
        data={apps}
        keyExtractor={(item) => item.packageName}
        renderItem={renderApp}
        refreshing={loading}
        onRefresh={loadApps}
      />
    </View>
  );
};
```

## API Reference

### `getInstalledApps(): Promise<InstalledApp[]>`

Returns a promise that resolves to an array of installed apps.

**Returns**: `Promise<InstalledApp[]>`

**Throws**: 
- Error if called on iOS
- Error if permission is denied or other Android-specific errors occur

### `InstalledApp` Interface

```typescript
interface InstalledApp {
  packageName: string;    // Unique package identifier
  appName: string;        // Display name of the app
  versionName: string;    // Version string (e.g., "1.0.0")
  versionCode: number;    // Version code number
}
```

## Compatibility

- **React Native**: 0.68+
- **Android**: API level 21+ (Android 5.0+)
- **iOS**: Not supported (throws error)

## Troubleshooting

### Permission Denied Errors

If you encounter permission denied errors on Android 11+:

1. Ensure you've added the appropriate permissions to your AndroidManifest.xml
2. If using `QUERY_ALL_PACKAGES`, be prepared to justify this usage to Google Play Store
3. Consider using specific package queries instead of broad permissions

### Build Errors

If you encounter build errors:

1. Clean your project: `cd android && ./gradlew clean && cd ..`
2. Reset Metro cache: `npx react-native start --reset-cache`
3. Rebuild: `npx react-native run-android`

## Contributing

See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.

## License

MIT

---

Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)