npm package: @m430/capacitor-app-install
Description: Capacitor plugin for APK installation and permission management - Android only (Web and iOS not supported)
Author: Andy Zheng
Latest version: 0.0.3

# @m430/capacitor-app-install

**Android Only** - A Capacitor plugin for APK installation and permission management on Android devices. This plugin provides essential functionality for app installation, including permission checks and APK installation capabilities.

> ⚠️ **Platform Support**: This plugin only supports Android. iOS and Web platforms are not supported.

## Features

- ✅ Check install unknown apps permission
- ✅ Open install unknown apps settings
- ✅ Install APK files
- ✅ Android only (Web and iOS platforms not supported)
- ✅ TypeScript support

## Install

```bash
npm install @m430/capacitor-app-install
npx cap sync
```

## Android Configuration

### 1. Add FileProvider to AndroidManifest.xml

Add the following to your `android/app/src/main/AndroidManifest.xml` inside the `<application>` tag:

```xml
<provider
    android:name="androidx.core.content.FileProvider"
    android:authorities="${applicationId}.fileprovider"
    android:exported="false"
    android:grantUriPermissions="true">
    <meta-data
        android:name="android.support.FILE_PROVIDER_PATHS"
        android:resource="@xml/file_paths" />
</provider>
```

### 2. Create file_paths.xml

Create `android/app/src/main/res/xml/file_paths.xml`:

```xml
<?xml version="1.0" encoding="utf-8"?>
<paths xmlns:android="http://schemas.android.com/apk/res/android">
    <external-path name="external_files" path="." />
    <external-cache-path name="external_cache" path="." />
    <files-path name="files" path="." />
    <cache-path name="cache" path="." />
</paths>
```

### 3. Add Permissions

Add the following permissions to your `android/app/src/main/AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
```

## Usage

```typescript
import { AppInstallPlugin } from '@m430/capacitor-app-install';

// Check if app can install unknown apps
const { granted } = await AppInstallPlugin.canInstallUnknownApps();
if (!granted) {
  // Open settings to allow install from unknown sources
  await AppInstallPlugin.openInstallUnknownAppsSettings();
}

// Install APK
try {
  const result = await AppInstallPlugin.installApk({
    filePath: '/path/to/your/app.apk'
  });
  console.log('Installation result:', result.message);
  if (result.completed) {
    console.log('APK installation started successfully');
  }
} catch (error) {
  console.error('Failed to install APK:', error);
}
```

## API

<docgen-index>

* [`canInstallUnknownApps()`](#caninstallunknownapps)
* [`openInstallUnknownAppsSettings()`](#openinstallunknownappssettings)
* [`installApk(...)`](#installapk)
* [Interfaces](#interfaces)

</docgen-index>

<docgen-api>
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->

### canInstallUnknownApps()

```typescript
canInstallUnknownApps() => Promise<PermissionResult>
```

Check if the app can install unknown apps (install from unknown sources)

**Returns:** <code>Promise&lt;<a href="#permissionresult">PermissionResult</a>&gt;</code>

--------------------


### openInstallUnknownAppsSettings()

```typescript
openInstallUnknownAppsSettings() => Promise<void>
```

Open the settings page for installing unknown apps

--------------------


### installApk(...)

```typescript
installApk(options: InstallApkOptions) => Promise<InstallApkResult>
```

Install an APK file

| Param         | Type                                                            | Description                            |
| ------------- | --------------------------------------------------------------- | -------------------------------------- |
| **`options`** | <code><a href="#installapkoptions">InstallApkOptions</a></code> | - The options containing the file path |

**Returns:** <code>Promise&lt;<a href="#installapkresult">InstallApkResult</a>&gt;</code>

--------------------


### Interfaces


#### PermissionResult

| Prop          | Type                 | Description                       |
| ------------- | -------------------- | --------------------------------- |
| **`granted`** | <code>boolean</code> | Whether the permission is granted |


#### InstallApkResult

| Prop            | Type                 | Description                                         |
| --------------- | -------------------- | --------------------------------------------------- |
| **`completed`** | <code>boolean</code> | Whether the installation was completed successfully |
| **`message`**   | <code>string</code>  | Message describing the installation result          |


#### InstallApkOptions

Capacitor App Install Plugin Definitions

⚠️ Platform Support: This plugin only supports Android platform.
iOS and Web platforms are not supported.

| Prop           | Type                | Description                         |
| -------------- | ------------------- | ----------------------------------- |
| **`filePath`** | <code>string</code> | The file path of the APK to install |

</docgen-api>

## Platform Support

| Platform | Supported |
| -------- | --------- |
| Android  | ✅        |
| iOS      | ❌        |
| Web      | ❌        |

## Error Handling

The plugin throws errors in the following cases:

- **File not found**: When the specified APK file doesn't exist
- **Permission denied**: When required permissions are not granted
- **Platform not supported**: When called on non-Android platforms

## License

MIT

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project.