@capawesome/capacitor-app-launcher 0.0.1 → 0.1.0

package/README.md

@@ -20,9 +20,14 @@ Capacitor plugin to check if an app can be opened and to open it.
 
 Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!
 
-## Newsletter
+## Use Cases
 
-Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+The App Launcher plugin is typically used to hand the user over to another app, for example:
+
+- **App-to-app navigation**: Open a companion or partner app directly from your app via its URL scheme or package name.
+- **Graceful fallbacks**: Check whether an app can be opened first and show an alternative if it is not installed.
+- **Composing emails**: Open the user's mail app with a `mailto:` URL.
+- **Launching Android apps by package name**: Open a specific app such as Gmail (`com.google.android.gm`) on Android.
 
 ## Compatibility
 
@@ -93,6 +98,12 @@ No configuration required for this plugin.
 
 ## Usage
 
+The following examples show how to check whether an app can be opened and open another app.
+
+### Check if an app can be opened
+
+Check whether an app can be opened before trying to open it. On iOS, the URL must be a URL scheme (e.g. `mailto:`); on Android, it can be a URL scheme or a package name (e.g. `com.google.android.gm`). Remember to declare every scheme and package name you check (see [Installation](#installation)), otherwise this method always resolves with `value: false`:
+
 ```typescript
 import { AppLauncher } from '@capawesome/capacitor-app-launcher';
 
@@ -100,6 +111,14 @@ const canOpenUrl = async () => {
   const { value } = await AppLauncher.canOpenUrl({ url: 'mailto:' });
   return value;
 };
+```
+
+### Open an app
+
+Open another app with the given URL. On Android, the URL can also be a package name. The result tells you whether the app was opened successfully:
+
+```typescript
+import { AppLauncher } from '@capawesome/capacitor-app-launcher';
 
 const openUrl = async () => {
   const { completed } = await AppLauncher.openUrl({ url: 'mailto:' });
@@ -209,6 +228,43 @@ This plugin is a drop-in replacement for the official `@capacitor/app-launcher`
 
 On Android, the `url` may be a URL scheme or a package name for both `canOpenUrl(...)` and `openUrl(...)`.
 
+## FAQ
+
+### How is this plugin different from other similar plugins?
+
+It lets you both check whether an app can be opened and open it, and on Android the target can be a URL scheme or a package name, so you can launch a specific app like Gmail directly by its package. It uses only official platform APIs, keeping it safe for App Store and Google Play submissions, and pairs cleanly with the Maps Launcher and Settings Launcher plugins for a complete launching story. The API is fully typed, supports both CocoaPods and Swift Package Manager on iOS, and is actively maintained against the latest Capacitor and OS versions.
+
+### Why does `canOpenUrl` always return `false`?
+
+This usually means the URL scheme or package name is not declared in your app. On Android 11 (API level 30) and above, every package name and URL scheme must be declared in the `<queries>` element of your `AndroidManifest.xml`. On iOS, every URL scheme must be declared in the `LSApplicationQueriesSchemes` key of your `Info.plist`. See the [Installation](#installation) section for examples.
+
+### Can I open an app by its package name?
+
+Yes, but only on Android, where the `url` option accepts a URL scheme (e.g. `mailto:`) or a package name (e.g. `com.google.android.gm`). On iOS, only URL schemes are supported.
+
+### How can I check if an app is installed?
+
+Use `canOpenUrl(...)` with the app's URL scheme or, on Android, its package name. Make sure the scheme or package name is declared as described in the [Installation](#installation) section. Note that on the Web, this method always resolves with `value: true` because the browser cannot determine whether a URL can be opened.
+
+### How is this plugin different from the official `@capacitor/app-launcher` plugin?
+
+This plugin is a drop-in replacement with an identical API, so you only need to change the import and installation. In addition, on Android the `url` may also be a package name for both `canOpenUrl(...)` and `openUrl(...)`. See the [migration section](#migrating-from-capacitorapp-launcher) for details.
+
+### Can I use this plugin with Ionic, React, Vue or Angular?
+
+Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.
+
+## Related Plugins
+
+- [Maps Launcher](https://capawesome.io/docs/sdks/capacitor/maps-launcher/): Launch navigation apps with turn-by-turn directions.
+- [Settings Launcher](https://capawesome.io/docs/sdks/capacitor/settings-launcher/): Open native settings screens.
+- [Android Intent Launcher](https://capawesome.io/docs/sdks/capacitor/android-intent-launcher/): Launch arbitrary Android intents.
+- [Phone Dialer](https://capawesome.io/docs/sdks/capacitor/phone-dialer/): Open the native phone dialer prefilled with a phone number.
+
+## Newsletter
+
+Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+
 ## Changelog
 
 See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-launcher/CHANGELOG.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@capawesome/capacitor-app-launcher",
-  "version": "0.0.1",
-  "description": "Capacitor plugin to check if an app can be opened and to open it.",
+  "version": "0.1.0",
+  "description": "Capacitor plugin to check if an app can be opened and to open it on Android, iOS, and Web.",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",
   "types": "dist/esm/index.d.ts",
@@ -39,7 +39,14 @@
     "plugin",
     "native",
     "app launcher",
-    "deep link"
+    "deep link",
+    "capacitor-plugin",
+    "open app",
+    "launch app",
+    "url scheme",
+    "package name",
+    "open external app",
+    "can open url"
   ],
   "scripts": {
     "verify": "npm run verify:ios && npm run verify:android && npm run verify:web",