@capgo/capacitor-intent-launcher

Launch Android intents and open system settings screens on Android and iOS from your Capacitor app.

Why Capacitor Intent Launcher?

A simple, free, and lightweight intent launcher plugin for both Android and iOS:

• System settings access - Open any Android settings screen (WiFi, Bluetooth, Location, etc.) or iOS settings screens
• iOS settings support - Open iOS settings screens including app settings, WiFi, Bluetooth, notifications, and more
• App launching - Open any installed application by package name (Android)
• App icon retrieval - Get application icons as base64-encoded images (Android)
• Full intent support - Pass extras, flags, data URIs, and MIME types (Android)
• Activity results - Receive result codes and data from launched activities (Android)
• Zero dependencies - Minimal footprint, no bloat

Perfect for apps that need to guide users to system settings on both platforms.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/intent-launcher/

Install

npm install @capgo/capacitor-intent-launcher
npx cap sync

Android

Works out of the box. No additional configuration required.

Opening Android Settings Screens

The plugin provides access to all Android system settings screens through the ActivityAction enum. Here are common examples:

import { IntentLauncher, ActivityAction } from '@capgo/capacitor-intent-launcher';

// Open main settings screen
await IntentLauncher.startActivityAsync({
  action: ActivityAction.SETTINGS
});

// Open WiFi settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.WIFI_SETTINGS
});

// Open Bluetooth settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.BLUETOOTH_SETTINGS
});

// Open Location settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.LOCATION_SOURCE_SETTINGS
});

// Open Display settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.DISPLAY_SETTINGS
});

// Open Sound settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.SOUND_SETTINGS
});

// Open Notification settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.NOTIFICATION_SETTINGS
});

Opening App-Specific Settings

You can open settings for a specific app by passing the package name:

// Open your app's settings page
await IntentLauncher.startActivityAsync({
  action: ActivityAction.APPLICATION_DETAILS_SETTINGS,
  data: 'package:com.yourapp.package'
});

// Open notification settings for your app
await IntentLauncher.startActivityAsync({
  action: ActivityAction.APP_NOTIFICATION_SETTINGS,
  extra: {
    'android.provider.extra.APP_PACKAGE': 'com.yourapp.package'
  }
});

Launching Other Apps

// Open an app by package name
await IntentLauncher.openApplication({
  packageName: 'com.google.android.gm' // Gmail
});

// Get an app's icon
const { icon } = await IntentLauncher.getApplicationIconAsync({
  packageName: 'com.google.android.gm'
});
// icon is a base64-encoded PNG: 'data:image/png;base64,...'

Advanced Intent Options

You can pass additional options like extras, flags, and MIME types:

// Open a content picker
await IntentLauncher.startActivityAsync({
  action: ActivityAction.GET_CONTENT,
  type: 'image/*',  // MIME type
  category: 'android.intent.category.OPENABLE'
});

// Open a URL in the browser
await IntentLauncher.startActivityAsync({
  action: ActivityAction.VIEW,
  data: 'https://example.com'
});

// Send text to another app
await IntentLauncher.startActivityAsync({
  action: ActivityAction.SEND,
  type: 'text/plain',
  extra: {
    'android.intent.extra.TEXT': 'Hello World!'
  }
});

// Make a phone call (requires CALL_PHONE permission)
await IntentLauncher.startActivityAsync({
  action: ActivityAction.CALL,
  data: 'tel:+1234567890'
});

// Open the dialer with a number (no permission required)
await IntentLauncher.startActivityAsync({
  action: ActivityAction.DIAL,
  data: 'tel:+1234567890'
});

Handling Activity Results

The startActivityAsync method returns a result with status information:

const result = await IntentLauncher.startActivityAsync({
  action: ActivityAction.LOCATION_SOURCE_SETTINGS
});

console.log('Result code:', result.resultCode);
// resultCode: -1 = Success, 0 = Canceled, 1+ = Custom user codes

if (result.data) {
  console.log('Data URI:', result.data);
}

if (result.extra) {
  console.log('Extra data:', result.extra);
}

Common Use Cases

Guide users to enable permissions:

// Location permission
await IntentLauncher.startActivityAsync({
  action: ActivityAction.LOCATION_SOURCE_SETTINGS
});

// Battery optimization settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.IGNORE_BATTERY_OPTIMIZATION_SETTINGS
});

// Overlay permission (draw over other apps)
await IntentLauncher.startActivityAsync({
  action: ActivityAction.MANAGE_OVERLAY_PERMISSION,
  data: 'package:com.yourapp.package'
});

Network settings:

// WiFi settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.WIFI_SETTINGS
});

// Mobile data settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.DATA_USAGE_SETTINGS
});

// Airplane mode settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.AIRPLANE_MODE_SETTINGS
});

Security settings:

// Biometric enrollment
await IntentLauncher.startActivityAsync({
  action: ActivityAction.BIOMETRIC_ENROLL
});

// Fingerprint settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.FINGERPRINT_SETTINGS
});

// Security settings
await IntentLauncher.startActivityAsync({
  action: ActivityAction.SECURITY_SETTINGS
});

Android Version Compatibility

Some settings actions are only available on specific Android versions. The plugin includes platform version information in the ActivityAction enum comments (e.g., @platform Android 12+). If you use an action that's not available on the device's Android version, the intent may fail or fall back to a general settings screen.

Error Handling

Always wrap intent calls in try-catch blocks:

try {
  await IntentLauncher.startActivityAsync({
    action: ActivityAction.WIFI_SETTINGS
  });
} catch (error) {
  console.error('Failed to open settings:', error);
  // Handle error - e.g., show a message to the user
}

iOS

Works out of the box. Use the openIOSSettings() method to open iOS settings screens.

Important: The only officially supported option by Apple is IOSSettings.App which opens your app's settings page. Other options use undocumented URL schemes (App-prefs:) that may break in future iOS versions or could potentially cause App Store rejection.

Note: The iOS Simulator will sometimes only open the Settings app, instead of the specified option. Test on a real device for accurate behavior.

import { IntentLauncher, IOSSettings } from '@capgo/capacitor-intent-launcher';

// Open app settings (officially supported by Apple)
await IntentLauncher.openIOSSettings({ option: IOSSettings.App });

// Open WiFi settings (may not work in all iOS versions)
await IntentLauncher.openIOSSettings({ option: IOSSettings.WiFi });

Web

Not supported. This plugin uses native platform APIs.

API

• startActivityAsync(...)
• openIOSSettings(...)
• openApplication(...)
• getApplicationIconAsync(...)
• getPluginVersion()
• Interfaces
• Type Aliases
• Enums

Capacitor Intent Launcher Plugin for launching Android intents and opening system settings on both Android and iOS.

startActivityAsync(...)

startActivityAsync(options: IntentLauncherParams) => Promise<IntentLauncherResult>

Starts an Android activity for the given action.

| Param | Type | Description | | ------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- | | options | IntentLauncherParams | - The intent launch options including action and optional parameters |

Returns: Promise<IntentLauncherResult>

Since: 1.0.0

openIOSSettings(...)

openIOSSettings(options: IOSSettingsParams) => Promise<IOSSettingsResult>

Opens iOS settings screen.

Note: The only officially supported option by Apple is App which opens your app's settings page. Other options may work but are not guaranteed and could break in future iOS versions or cause App Store rejection.

Also note that the iOS Simulator will sometimes only open the Settings app, instead of the specified option.

| Param | Type | Description | | ------------- | --------------------------------------------------------------- | --------------------------------- | | options | IOSSettingsParams | - The iOS settings option to open |

Returns: Promise<IOSSettingsResult>

Since: 8.2.0

openApplication(...)

openApplication(options: OpenApplicationOptions) => Promise<void>

Opens an application by its package name.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------- | --------------------------------------------- | | options | OpenApplicationOptions | - The package name of the application to open |

Since: 1.0.0

getApplicationIconAsync(...)

getApplicationIconAsync(options: GetApplicationIconOptions) => Promise<GetApplicationIconResult>

Gets the application icon as a base64-encoded PNG string.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------------- | ------------------------------------- | | options | GetApplicationIconOptions | - The package name of the application |

Returns: Promise<GetApplicationIconResult>

Since: 1.0.0

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 1.0.0

Interfaces

IntentLauncherResult

Result from starting an activity.

| Prop | Type | Description | Since | | ---------------- | ---------------------------------------------------------------- | --------------------------------------------- | ----- | | resultCode | ResultCode | The result code returned by the activity. | 1.0.0 | | data | string | Optional data URI returned by the activity. | 1.0.0 | | extra | Record<string, unknown> | Optional extra data returned by the activity. | 1.0.0 |

IntentLauncherParams

Options for starting an activity.

| Prop | Type | Description | Since | | ----------------- | ---------------------------------------------------------------- | ------------------------------------------------------------- | ----- | | action | string | The action to perform. Use values from ActivityAction enum. | 1.0.0 | | category | string | Optional category to add to the intent. | 1.0.0 | | className | string | Optional class name for the component to launch. | 1.0.0 | | data | string | Optional URI data for the intent. Must be a valid URI. | 1.0.0 | | extra | Record<string, unknown> | Optional extra data to pass to the intent as key-value pairs. | 1.0.0 | | flags | number | Optional intent flags as a bitmask. | 1.0.0 | | packageName | string | Optional package name for the component. | 1.0.0 | | type | string | Optional MIME type for the intent data. | 1.0.0 |

IOSSettingsResult

Result from opening iOS settings.

| Prop | Type | Description | Since | | ------------- | -------------------- | ---------------------------------------------------- | ----- | | success | boolean | Whether the settings screen was successfully opened. | 8.2.0 |

IOSSettingsParams

Options for opening iOS settings.

| Prop | Type | Description | Since | | ------------ | ------------------- | -------------------------------------------------------------------- | ----- | | option | string | The iOS settings screen to open. Use values from IOSSettings enum. | 8.2.0 |

OpenApplicationOptions

Options for opening an application.

| Prop | Type | Description | Since | | ----------------- | ------------------- | -------------------------------------------- | ----- | | packageName | string | The package name of the application to open. | 1.0.0 |

GetApplicationIconResult

Result from getting an application icon.

| Prop | Type | Description | Since | | ---------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----- | | icon | string | The application icon as a base64-encoded PNG string prefixed with 'data:image/png;base64,'. Empty string if the icon is not available. | 1.0.0 |

GetApplicationIconOptions

Options for getting an application icon.

| Prop | Type | Description | Since | | ----------------- | ------------------- | ------------------------------------ | ----- | | packageName | string | The package name of the application. | 1.0.0 |

Type Aliases

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

Enums

ResultCode

| Members | Value | Description | | --------------- | --------------- | -------------------------------------- | | Success | -1 | The activity completed successfully. | | Canceled | 0 | The activity was canceled by the user. | | FirstUser | 1 | First custom user-defined result code. |

Credit

Based on the (Expo plugin)[https://docs.expo.dev/versions/latest/sdk/intent-launcher/]