@capawesome/capacitor-maps-launcher 0.0.1

package/CapawesomeCapacitorMapsLauncher.podspec

@@ -0,0 +1,17 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'CapawesomeCapacitorMapsLauncher'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['repository']['url']
+  s.author = package['author']
+  s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
+  s.source_files = 'ios/Plugin/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+end

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robin Genz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Package.swift

@@ -0,0 +1,28 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "CapawesomeCapacitorMapsLauncher",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(
+            name: "CapawesomeCapacitorMapsLauncher",
+            targets: ["MapsLauncherPlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
+    ],
+    targets: [
+        .target(
+            name: "MapsLauncherPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Plugin"),
+        .testTarget(
+            name: "MapsLauncherPluginTests",
+            dependencies: ["MapsLauncherPlugin"],
+            path: "ios/PluginTests")
+    ]
+)

package/README.md

@@ -0,0 +1,292 @@
+# @capawesome/capacitor-maps-launcher
+
+Capacitor plugin to launch navigation apps with turn-by-turn directions.
+
+<div class="capawesome-z29o10a">
+  <a href="https://cloud.capawesome.io/" target="_blank">
+    <img alt="Deliver Live Updates to your Capacitor app with Capawesome Cloud" src="https://cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1" />
+  </a>
+</div>
+
+## Features
+
+- 🧭 **Navigate**: Launch a navigation app with turn-by-turn directions to a destination.
+- 🗺️ **Curated apps**: Support for Google Maps, Apple Maps (iOS) and Waze.
+- 📍 **Coordinates & addresses**: Navigate to coordinates or a plain address.
+- 🚗 **Travel modes**: Choose between driving, walking, bicycling and transit (best-effort per app).
+- ✅ **Availability**: Check which navigation apps are installed and can be launched.
+- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
+- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
+
+Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!
+
+## 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/).
+
+## Compatibility
+
+| Plugin Version | Capacitor Version | Status         |
+| -------------- | ----------------- | -------------- |
+| 0.x.x          | >=8.x.x           | Active support |
+
+## Installation
+
+You can use our **AI-Assisted Setup** to install the plugin.
+Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:
+
+```bash
+npx skills add capawesome-team/skills --skill capacitor-plugins
+```
+
+Then use the following prompt:
+
+```
+ Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-maps-launcher` plugin in my project.
+```
+
+If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:
+
+```bash
+npm install @capawesome/capacitor-maps-launcher
+npx cap sync
+```
+
+### Android
+
+The plugin declares the required [package visibility](https://developer.android.com/training/package-visibility) `<queries>` for Google Maps and Waze in its own `AndroidManifest.xml`. No additional configuration is required.
+
+### iOS
+
+#### Application Queries Schemes
+
+To detect and launch Google Maps and Waze, the following URL schemes must be added to the `LSApplicationQueriesSchemes` array in the `Info.plist` file of your app. Without them, `getAvailableApps(...)` reports those apps as unavailable and `navigate(...)` rejects with the `APP_NOT_AVAILABLE` error code.
+
+```xml
+<key>LSApplicationQueriesSchemes</key>
+<array>
+  <string>comgooglemaps</string>
+  <string>waze</string>
+</array>
+```
+
+Apple Maps is always available and does not require any configuration.
+
+## Configuration
+
+No configuration required for this plugin.
+
+## Usage
+
+```typescript
+import { MapsLauncher, NavigationApp } from '@capawesome/capacitor-maps-launcher';
+
+const getAvailableApps = async () => {
+  const { apps } = await MapsLauncher.getAvailableApps();
+  return apps;
+};
+
+const getDefaultApp = async () => {
+  const { app } = await MapsLauncher.getDefaultApp();
+  return app;
+};
+
+const navigate = async () => {
+  await MapsLauncher.navigate({
+    destination: {
+      latitude: 37.3349,
+      longitude: -122.009,
+    },
+    app: NavigationApp.GoogleMaps,
+    travelMode: 'driving',
+  });
+};
+
+const navigateToAddress = async () => {
+  await MapsLauncher.navigate({
+    destination: {
+      address: 'Apple Park, Cupertino, CA',
+    },
+  });
+};
+```
+
+## API
+
+<docgen-index>
+
+* [`getAvailableApps()`](#getavailableapps)
+* [`getDefaultApp()`](#getdefaultapp)
+* [`navigate(...)`](#navigate)
+* [Interfaces](#interfaces)
+* [Type Aliases](#type-aliases)
+* [Enums](#enums)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+### getAvailableApps()
+
+```typescript
+getAvailableApps() => Promise<GetAvailableAppsResult>
+```
+
+Get the navigation apps that are installed and can be launched.
+
+On iOS, Apple Maps is always included. Google Maps and Waze are only
+included if the corresponding `LSApplicationQueriesSchemes` entries are
+added to the `Info.plist` file of your app.
+
+Only available on Android and iOS.
+
+**Returns:** <code>Promise&lt;<a href="#getavailableappsresult">GetAvailableAppsResult</a>&gt;</code>
+
+**Since:** 0.1.0
+
+--------------------
+
+
+### getDefaultApp()
+
+```typescript
+getDefaultApp() => Promise<GetDefaultAppResult>
+```
+
+Get the navigation app that is configured as the default handler for
+navigation intents.
+
+Returns `null` if the default app is not part of the curated list of
+supported apps or if no default app is set (i.e. the system shows a
+chooser).
+
+Only available on Android.
+
+**Returns:** <code>Promise&lt;<a href="#getdefaultappresult">GetDefaultAppResult</a>&gt;</code>
+
+**Since:** 0.1.0
+
+--------------------
+
+
+### navigate(...)
+
+```typescript
+navigate(options: NavigateOptions) => Promise<void>
+```
+
+Launch a navigation app with turn-by-turn directions to a destination.
+
+If no `app` is provided, the system default behavior is used (a chooser on
+Android, Apple Maps on iOS).
+
+Only available on Android and iOS.
+
+| Param         | Type                                                        |
+| ------------- | ----------------------------------------------------------- |
+| **`options`** | <code><a href="#navigateoptions">NavigateOptions</a></code> |
+
+**Since:** 0.1.0
+
+--------------------
+
+
+### Interfaces
+
+
+#### GetAvailableAppsResult
+
+| Prop       | Type                         | Description                                                 | Since |
+| ---------- | ---------------------------- | ----------------------------------------------------------- | ----- |
+| **`apps`** | <code>NavigationApp[]</code> | The navigation apps that are installed and can be launched. | 0.1.0 |
+
+
+#### GetDefaultAppResult
+
+| Prop      | Type                                                            | Description                                                                                                                                                                    | Since |
+| --------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
+| **`app`** | <code><a href="#navigationapp">NavigationApp</a> \| null</code> | The navigation app that is configured as the default handler. Returns `null` if the default app is not part of the curated list of supported apps or if no default app is set. | 0.1.0 |
+
+
+#### NavigateOptions
+
+| Prop              | Type                                                    | Description                                                                                                                                                                                                                                                                               | Default                | Since |
+| ----------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----- |
+| **`app`**         | <code><a href="#navigationapp">NavigationApp</a></code> | The navigation app to launch. If not provided, the system default behavior is used (a chooser on Android, Apple Maps on iOS).                                                                                                                                                             |                        | 0.1.0 |
+| **`destination`** | <code><a href="#destination">Destination</a></code>     | The destination to navigate to.                                                                                                                                                                                                                                                           |                        | 0.1.0 |
+| **`start`**       | <code><a href="#destination">Destination</a></code>     | The start location of the route. If not provided, the current location of the device is used. **Note**: The support depends on the selected app. Apple Maps supports it fully, Google Maps opens the directions preview instead of starting turn-by-turn navigation, and Waze ignores it. |                        | 0.1.0 |
+| **`travelMode`**  | <code><a href="#travelmode">TravelMode</a></code>       | The travel mode to use for the directions. **Note**: The support depends on the selected app and is best-effort. Waze only supports driving and ignores this option.                                                                                                                      | <code>'driving'</code> | 0.1.0 |
+
+
+#### Destination
+
+A destination is either defined by its coordinates or by its address, but
+not both.
+
+| Prop            | Type                | Description                                                                                        | Since |
+| --------------- | ------------------- | -------------------------------------------------------------------------------------------------- | ----- |
+| **`address`**   | <code>string</code> | The address of the destination. Must be provided without `latitude` and `longitude`.               | 0.1.0 |
+| **`latitude`**  | <code>number</code> | The latitude of the destination. Must be provided together with `longitude` and without `address`. | 0.1.0 |
+| **`longitude`** | <code>number</code> | The longitude of the destination. Must be provided together with `latitude` and without `address`. | 0.1.0 |
+
+
+### Type Aliases
+
+
+#### TravelMode
+
+The travel mode to use for the directions.
+
+- `driving`: Driving directions.
+- `walking`: Walking directions.
+- `bicycling`: Bicycling directions.
+- `transit`: Public transit directions.
+
+<code>'driving' | 'walking' | 'bicycling' | 'transit'</code>
+
+
+### Enums
+
+
+#### NavigationApp
+
+| Members          | Value                     | Description                        | Since |
+| ---------------- | ------------------------- | ---------------------------------- | ----- |
+| **`AppleMaps`**  | <code>'appleMaps'</code>  | Apple Maps. Only available on iOS. | 0.1.0 |
+| **`GoogleMaps`** | <code>'googleMaps'</code> | Google Maps.                       | 0.1.0 |
+| **`Waze`**       | <code>'waze'</code>       | Waze.                              | 0.1.0 |
+
+</docgen-api>
+
+## Platform Support
+
+The behavior of the `navigate(...)` method depends on the selected app and platform. Keep the following in mind:
+
+### Start location
+
+| App         | `start` support                                                                                                    |
+| ----------- | ------------------------------------------------------------------------------------------------------------------ |
+| Apple Maps  | Full support.                                                                                                       |
+| Google Maps | Supported, but opens the directions preview instead of starting turn-by-turn navigation directly.                  |
+| Waze        | Not supported. The option is ignored.                                                                              |
+
+If `start` is not provided, the current location of the device is used.
+
+### Travel mode
+
+| App         | `driving` | `walking` | `bicycling` | `transit` |
+| ----------- | --------- | --------- | ----------- | --------- |
+| Apple Maps  | ✅        | ✅        | ❌          | ✅        |
+| Google Maps | ✅        | ✅        | ✅          | ✅        |
+| Waze        | ✅        | ❌        | ❌          | ❌        |
+
+Unsupported travel modes fall back to the default behavior of the respective app. Waze only supports driving and ignores the `travelMode` option.
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/maps-launcher/CHANGELOG.md).
+
+## License
+
+See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/maps-launcher/LICENSE).

package/android/build.gradle

@@ -0,0 +1,58 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace = "io.capawesome.capacitorjs.plugins.mapslauncher"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        abortOnError = false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,10 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <queries>
+        <package android:name="com.google.android.apps.maps" />
+        <package android:name="com.waze" />
+        <intent>
+            <action android:name="android.intent.action.VIEW" />
+            <data android:scheme="geo" />
+        </intent>
+    </queries>
+</manifest>

package/android/src/main/java/io/capawesome/capacitorjs/plugins/mapslauncher/MapsLauncher.java

@@ -0,0 +1,200 @@
+package io.capawesome.capacitorjs.plugins.mapslauncher;
+
+import android.content.ActivityNotFoundException;
+import android.content.Context;
+import android.content.Intent;
+import android.content.pm.PackageManager;
+import android.content.pm.ResolveInfo;
+import android.net.Uri;
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import io.capawesome.capacitorjs.plugins.mapslauncher.classes.CustomExceptions;
+import io.capawesome.capacitorjs.plugins.mapslauncher.classes.options.Destination;
+import io.capawesome.capacitorjs.plugins.mapslauncher.classes.options.NavigateOptions;
+import io.capawesome.capacitorjs.plugins.mapslauncher.classes.results.GetAvailableAppsResult;
+import io.capawesome.capacitorjs.plugins.mapslauncher.classes.results.GetDefaultAppResult;
+import io.capawesome.capacitorjs.plugins.mapslauncher.interfaces.EmptyCallback;
+import io.capawesome.capacitorjs.plugins.mapslauncher.interfaces.NonEmptyResultCallback;
+import java.util.ArrayList;
+import java.util.List;
+
+public class MapsLauncher {
+
+    public static final String APP_GOOGLE_MAPS = "googleMaps";
+    public static final String APP_WAZE = "waze";
+    public static final String PACKAGE_GOOGLE_MAPS = "com.google.android.apps.maps";
+    public static final String PACKAGE_WAZE = "com.waze";
+
+    @NonNull
+    private final MapsLauncherPlugin plugin;
+
+    public MapsLauncher(@NonNull MapsLauncherPlugin plugin) {
+        this.plugin = plugin;
+    }
+
+    public void getAvailableApps(@NonNull NonEmptyResultCallback<GetAvailableAppsResult> callback) {
+        List<String> apps = new ArrayList<>();
+        if (isPackageInstalled(PACKAGE_GOOGLE_MAPS)) {
+            apps.add(APP_GOOGLE_MAPS);
+        }
+        if (isPackageInstalled(PACKAGE_WAZE)) {
+            apps.add(APP_WAZE);
+        }
+        callback.success(new GetAvailableAppsResult(apps));
+    }
+
+    public void getDefaultApp(@NonNull NonEmptyResultCallback<GetDefaultAppResult> callback) {
+        Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse("geo:0,0?q=0,0"));
+        ResolveInfo resolveInfo = getContext().getPackageManager().resolveActivity(intent, PackageManager.MATCH_DEFAULT_ONLY);
+        String app = null;
+        if (resolveInfo != null && resolveInfo.activityInfo != null) {
+            app = mapPackageToApp(resolveInfo.activityInfo.packageName);
+        }
+        callback.success(new GetDefaultAppResult(app));
+    }
+
+    public void navigate(@NonNull NavigateOptions options, @NonNull EmptyCallback callback) throws Exception {
+        String app = options.getApp();
+        if (app != null) {
+            String packageName = getPackageForApp(app);
+            if (packageName == null || !isPackageInstalled(packageName)) {
+                throw CustomExceptions.APP_NOT_AVAILABLE;
+            }
+        }
+        Intent intent = createIntent(options);
+        try {
+            plugin.getActivity().startActivity(intent);
+        } catch (ActivityNotFoundException exception) {
+            throw CustomExceptions.LAUNCH_FAILED;
+        }
+        callback.success();
+    }
+
+    @NonNull
+    private Intent createDefaultIntent(@NonNull Destination destination) {
+        return new Intent(Intent.ACTION_VIEW, Uri.parse("geo:0,0?q=" + Uri.encode(formatDestination(destination))));
+    }
+
+    @NonNull
+    private Intent createGoogleMapsIntent(@NonNull Destination destination, @Nullable Destination start, @Nullable String travelMode) {
+        Uri uri;
+        if (start == null) {
+            String value =
+                "google.navigation:q=" + Uri.encode(formatDestination(destination)) + "&mode=" + mapTravelModeToGoogleMode(travelMode);
+            uri = Uri.parse(value);
+        } else {
+            String value =
+                "https://www.google.com/maps/dir/?api=1" +
+                "&origin=" +
+                Uri.encode(formatDestination(start)) +
+                "&destination=" +
+                Uri.encode(formatDestination(destination)) +
+                "&travelmode=" +
+                mapTravelModeToGoogleUrlMode(travelMode);
+            uri = Uri.parse(value);
+        }
+        Intent intent = new Intent(Intent.ACTION_VIEW, uri);
+        intent.setPackage(PACKAGE_GOOGLE_MAPS);
+        return intent;
+    }
+
+    @NonNull
+    private Intent createIntent(@NonNull NavigateOptions options) {
+        String app = options.getApp();
+        if (APP_GOOGLE_MAPS.equals(app)) {
+            return createGoogleMapsIntent(options.getDestination(), options.getStart(), options.getTravelMode());
+        } else if (APP_WAZE.equals(app)) {
+            return createWazeIntent(options.getDestination());
+        } else {
+            return createDefaultIntent(options.getDestination());
+        }
+    }
+
+    @NonNull
+    private Intent createWazeIntent(@NonNull Destination destination) {
+        String query = destination.hasCoordinates() ? "ll=" : "q=";
+        String value = "https://waze.com/ul?" + query + Uri.encode(formatDestination(destination)) + "&navigate=yes";
+        Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(value));
+        intent.setPackage(PACKAGE_WAZE);
+        return intent;
+    }
+
+    @NonNull
+    private String formatDestination(@NonNull Destination destination) {
+        if (destination.hasCoordinates()) {
+            return destination.getLatitude() + "," + destination.getLongitude();
+        }
+        String address = destination.getAddress();
+        return address == null ? "" : address;
+    }
+
+    @NonNull
+    private Context getContext() {
+        return plugin.getContext();
+    }
+
+    @Nullable
+    private String getPackageForApp(@NonNull String app) {
+        switch (app) {
+            case APP_GOOGLE_MAPS:
+                return PACKAGE_GOOGLE_MAPS;
+            case APP_WAZE:
+                return PACKAGE_WAZE;
+            default:
+                return null;
+        }
+    }
+
+    private boolean isPackageInstalled(@NonNull String packageName) {
+        try {
+            getContext().getPackageManager().getPackageInfo(packageName, 0);
+            return true;
+        } catch (PackageManager.NameNotFoundException exception) {
+            return false;
+        }
+    }
+
+    @Nullable
+    private String mapPackageToApp(@NonNull String packageName) {
+        switch (packageName) {
+            case PACKAGE_GOOGLE_MAPS:
+                return APP_GOOGLE_MAPS;
+            case PACKAGE_WAZE:
+                return APP_WAZE;
+            default:
+                return null;
+        }
+    }
+
+    @NonNull
+    private String mapTravelModeToGoogleMode(@Nullable String travelMode) {
+        if (travelMode == null) {
+            return "d";
+        }
+        switch (travelMode) {
+            case "walking":
+                return "w";
+            case "bicycling":
+                return "b";
+            case "transit":
+                return "l";
+            default:
+                return "d";
+        }
+    }
+
+    @NonNull
+    private String mapTravelModeToGoogleUrlMode(@Nullable String travelMode) {
+        if (travelMode == null) {
+            return "driving";
+        }
+        switch (travelMode) {
+            case "walking":
+            case "bicycling":
+            case "transit":
+                return travelMode;
+            default:
+                return "driving";
+        }
+    }
+}