@capgo/capacitor-launch-navigator

Panoramica

Il plugin Capacitor Launch Navigator consente di avviare app di navigazione native su dispositivi iOS e Android con navigazione basata su coordinate. Questo plugin fornisce integrazione senza soluzione di continuità con applicazioni di mappatura popolari e supporta molteplici modalità di trasporto per soluzioni di navigazione complete.

Supporto multi-app

Google Maps, Apple Maps, Waze, Citymapper e altro 🗺️

Modalità di trasporto

Indicazioni in auto, a piedi, con trasporto pubblico e in bici 🧭

Rilevamento app

Controlla disponibilità ed elenca app di navigazione installate 🔍

Basato su coordinate

Naviga usando coordinate latitudine/longitudine 📍

Installazione

npm install @capgo/capacitor-launch-navigator
npx cap sync

Configurazione iOS

Aggiungi schemi URL al tuo Info.plist per rilevare le app di navigazione installate:

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>googlemaps</string>
    <string>waze</string>
    <string>citymapper</string>
    <!-- Aggiungi altri schemi di app di navigazione -->
</array>

Metodi API Principali

Navigazione

• navigate(options) - Avvia navigazione verso coordinate specificate
• isAppAvailable(options) - Controlla se un’app di navigazione specifica è installata
• getAvailableApps() - Elenca tutte le app di navigazione disponibili sul dispositivo
• getSupportedApps() - Ottieni tutte le app supportate per la piattaforma corrente

Esempio di Utilizzo

import { LaunchNavigator, TransportMode } from '@capgo/capacitor-launch-navigator';

// Navigazione di base verso coordinate
await LaunchNavigator.navigate({
  destination: [37.7749, -122.4194], // Coordinate San Francisco
});

// Navigazione avanzata con opzioni
await LaunchNavigator.navigate({
  destination: [37.7749, -122.4194],
  options: {
    start: [37.7849, -122.4094], // Punto di partenza opzionale
    transportMode: TransportMode.DRIVING,
    app: 'google_maps', // App di navigazione preferita
    appDisplayName: 'Google Maps'
  }
});

// Controlla se un'app specifica è disponibile
const result = await LaunchNavigator.isAppAvailable({
  app: 'google_maps'
});

if (result.available) {
  console.log('Google Maps è installato');
} else {
  console.log('Google Maps non è disponibile');
}

// Ottieni tutte le app di navigazione disponibili
const availableApps = await LaunchNavigator.getAvailableApps();
console.log('App di navigazione disponibili:', availableApps);

// Ottieni tutte le app supportate per la piattaforma
const supportedApps = await LaunchNavigator.getSupportedApps();
console.log('App supportate:', supportedApps);

Opzioni di Navigazione

interface NavigationOptions {
  start?: [number, number];      // Coordinate di partenza [lat, lng]
  transportMode?: TransportMode; // Metodo di trasporto
  app?: string;                  // App di navigazione preferita
  appDisplayName?: string;       // Nome visualizzato per l'app
  launchMode?: LaunchMode;       // Come avviare l'app
}

Modalità di Trasporto

enum TransportMode {
  DRIVING = 'driving',
  WALKING = 'walking',
  TRANSIT = 'transit',
  CYCLING = 'cycling'
}

App di Navigazione Supportate

iOS

• Apple Maps (integrata)
• Google Maps
• Waze
• Citymapper
• Transit
• Moovit
• Uber
• Lyft
• E molte altre…

Android

• Google Maps (integrata)
• Waze
• Citymapper
• HERE WeGo
• Sygic
• MapQuest
• Moovit
• E molte altre…

Requisiti Coordinate

⚠️ Importante: Questo plugin accetta solo coordinate latitudine/longitudine per la navigazione. Usa @capgo/capacitor-nativegeocoder per convertire indirizzi in coordinate.

// Esempio con geocodifica
import { NativeGeocoder } from '@capgo/capacitor-nativegeocoder';

// Converti indirizzo in coordinate
const geocodeResult = await NativeGeocoder.forwardGeocode({
  address: '1600 Amphitheatre Parkway, Mountain View, CA'
});

if (geocodeResult.results.length > 0) {
  const coords = geocodeResult.results[0];

  // Avvia navigazione con coordinate geocodificate
  await LaunchNavigator.navigate({
    destination: [coords.latitude, coords.longitude]
  });
}

Rilevamento e Selezione App

// Controlla più app e usa la prima disponibile
const appsToCheck = ['google_maps', 'waze', 'apple_maps'];
let selectedApp = null;

for (const app of appsToCheck) {
  const result = await LaunchNavigator.isAppAvailable({ app });
  if (result.available) {
    selectedApp = app;
    break;
  }
}

if (selectedApp) {
  await LaunchNavigator.navigate({
    destination: [37.7749, -122.4194],
    options: { app: selectedApp }
  });
} else {
  console.log('Nessuna app di navigazione supportata trovata');
}

Gestione degli Errori

try {
  await LaunchNavigator.navigate({
    destination: [37.7749, -122.4194],
    options: {
      app: 'google_maps',
      transportMode: TransportMode.DRIVING
    }
  });
} catch (error) {
  console.error('Navigazione fallita:', error);
  // Gestisci errore - app non disponibile, coordinate non valide, ecc.
}

Casi d’Uso

• Servizi basati sulla posizione: Naviga gli utenti verso punti di interesse
• App di consegna: Guida i conducenti alle posizioni di consegna
• App per eventi: Dirigi i partecipanti alle sedi degli eventi
• App immobiliari: Naviga verso le posizioni delle proprietà
• App di viaggio: Guida i turisti alle attrazioni

Migliori Pratiche

• Controlla sempre la disponibilità dell’app prima di tentare la navigazione
• Fornisci opzioni di fallback quando le app preferite non sono disponibili
• Usa nomi visualizzati significativi per la selezione dell’utente
• Gestisci gli errori con grazia con messaggi user-friendly
• Considera le preferenze dell’utente per le app di navigazione predefinite

Documentazione

Consulta la documentazione completa per guide di implementazione dettagliate e pattern di navigazione avanzati.