Se cerchi un'alternativa a Capacitor Google Maps, hai tre strade percorribili: mantenere l'ufficiale @capacitor/google-maps plugin e gestirne i limiti, renderizzare la mappa nella WebView con una libreria JavaScript come MapLibre GL JS o Leaflet, oppure usare un plugin nativo basato su un altro SDK. Capgo non include un proprio plugin di rendering mappe, quindi questa guida confronta le opzioni in modo neutrale e mostra i plugin Capgo che funzionano bene con qualsiasi mappa: navigation handoff, geocoding e background location.
Perché gli sviluppatori cercano oltre @capacitor/google-maps
Il plugin ufficiale (versione 8 per Capacitor 8) integra il SDK nativo di Google Maps su iOS e Android e il API JavaScript di Google Maps sul web. Funziona, ma questi problemi emergono continuamente.
Un account Google Cloud con fatturazione attiva su ogni piattaforma
Il plugin richiede chiavi API collegate a un account Google Cloud con fatturazione attiva su Android, iOS e web. Il pricing di Google per il caricamento di mappe mobile native è generoso, ma devi comunque configurare il billing, limitare le chiavi per piattaforma e monitorare le quote. I caricamenti web e i servizi come Places e Directions vengono fatturati in base all'uso dopo i limiti gratuiti. Controlla la pagina dei prezzi di Google Maps Platform prima di procedere, dato che il modello è cambiato nel 2025.
Su Android la mappa viene disegnata dietro la WebView
Su iOS la vista della mappa è inserita nella scroll view della WebView. Su Android viene renderizzata sotto l'intera WebView e il plugin la sposta per seguire l' <capacitor-google-map> elemento. Ogni layer sopra di essa deve essere trasparente:
/* Required on Android with @capacitor/google-maps */
html,
body,
ion-content,
ion-content::part(background) {
background: transparent !important;
--background: transparent;
}Questo è il problema principale del tipo "la mia mappa è vuota". Rende anche più difficili gli overlay custom, i modal e le transizioni di pagina, perché l'HTML si trova sopra una view nativa.
I marker possono essere aggiunti o rimossi, ma non aggiornati
Il API ha addMarker, addMarkers, removeMarker e removeMarkers, ma nessun updateMarker. La posizione live di un veicolo richiede di rimuovere e aggiungere elementi a ogni aggiornamento, causando flickering e un eccesso di chiamate al bridge.
Styling e funzionalità limitate su native
Alcune opzioni sono solo web, ad esempio mapId per lo styling basato su cloud, e region e language. Avrai marker, clustering, polylines, poligoni, cerchi, tile overlay, controllo della camera e click listener. Se cerchi styling basato su dati, heatmap o edifici 3D uniformi su tutte le piattaforme, incontrerai dei limiti.
Panoramica delle opzioni
| Opzione | Rendering | Chiave API necessaria | Sorgente tile | Ideale per |
|---|---|---|---|---|
@capacitor/google-maps |
SDK Native (Android, iOS), JS su web | Sì, fatturazione attiva | App che richiedono dati Google e performance native | |
| MapLibre GL JS | WebGL nella WebView | Dipende dal provider di tile | Qualsiasi fonte di vector tile, possibile self-hosting | Mappe con stile custom, quasi offline, no vendor lock-in |
| Leaflet | DOM e canvas nella WebView | Dipende dal provider di tile | Tile raster (OSM o altre fonti) | Mappe semplici, bundle ridotto, molti plugin |
| Google Maps JS API in WebView | Renderer JS di Google | Sì | Stesso look Google su ogni piattaforma, feature set JS completo | |
| Plugin nativi MapLibre o Mapbox | SDK nativo | Dipende | Qualsiasi / Mapbox | Dati pesanti, sessioni lunghe, gesti nativi |
Non esiste un vincitore assoluto. La scelta dipende dal volume di dati, dalle esigenze di styling e da quanto vuoi dipendere da un singolo vendor.
Opzione 1: MapLibre GL JS nella WebView
MapLibre GL JS è il fork open source di Mapbox GL JS v1. Renderizza vector tiles con WebGL e funziona bene in WKWebView e Android System WebView. È l'opzione più flessibile se non ti servono i dati di Google.
bun add maplibre-glimport maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
const map = new maplibregl.Map({
container: 'map',
style: 'https://your-tile-provider.example.com/styles/streets/style.json',
center: [2.3522, 48.8566], // [lng, lat]
zoom: 12,
});
map.addControl(new maplibregl.NavigationControl(), 'top-right');
// A marker you can move without remove/add
const courier = new maplibregl.Marker({ color: '#1d4ed8' })
.setLngLat([2.35, 48.85])
.addTo(map);
export function moveCourier(lng: number, lat: number) {
courier.setLngLat([lng, lat]);
}Layer GeoJSON, data-driven styling e linee di percorso sono supportati nativamente:
map.on('load', () => {
map.addSource('route', {
type: 'geojson',
data: {
type: 'Feature',
properties: {},
geometry: {
type: 'LineString',
coordinates: [
[2.3522, 48.8566],
[2.3376, 48.8606],
[2.2945, 48.8584],
],
},
},
});
map.addLayer({
id: 'route-line',
type: 'line',
source: 'route',
paint: { 'line-color': '#2563eb', 'line-width': 5 },
});
});Cose da sapere:
- Serve una fonte di tile. Le opzioni includono host commerciali di vector tile o l'auto-hosting di tile generati da OpenStreetMap. I server pubblici di OpenStreetMap hanno una policy che non permette traffico intenso da app.
- Mostra sempre l'attribuzione richiesta dal tuo provider di tile.
- Essendo semplice code web, la stessa mappa funziona in una preview nel browser, velocizzando lo sviluppo.
Opzione 2: Leaflet
Leaflet è leggero e maturo. È l'ideale per mappe con poche centinaia di marker, raster tiles e interazioni semplici.
bun add leafletimport L from 'leaflet';
import 'leaflet/dist/leaflet.css';
const map = L.map('map').setView([48.8566, 2.3522], 13);
L.tileLayer('https://tiles.example.com/{z}/{x}/{y}.png', {
maxZoom: 19,
attribution: '© OpenStreetMap contributors',
}).addTo(map);
L.marker([48.8584, 2.2945]).addTo(map).bindPopup('Eiffel Tower');Nelle app bundle, i percorsi predefiniti delle icone dei marker di Leaflet spesso si rompono. Importa le immagini delle icone e imposta L.Icon.Default le opzioni, oppure usa le tue L.divIcon.
Opzione 3: API di Google Maps JavaScript nella WebView
Se ti servono i dati e l'estetica di Google, ma vuoi che la mappa si comporti come un normale elemento HTML, carica la API JavaScript di Maps nella WebView invece della SDK nativa. Perderai un po' di fluidità nativa e ogni caricamento della mappa sarà un caricamento web fatturabile, ma avrai il pieno API JS: cloud styling con map ID, marker avanzati e data layer.
Limita la web key tramite HTTP referrer. Su iOS, Capacitor serve l'app da capacitor://localhost di default, e su Android da https://localhost, quindi aggiungi questi origin alle restrizioni della chiave e testa entrambi.
Opzione 4: Plugin nativi basati su altri SDK
Esistono wrapper nativi attorno a MapLibre Native o agli SDK di Mapbox nella community. Offrono gesti e performance native con qualsiasi tile source. Prima di sceglierne uno, verifica che supporti Capacitor 8, che abbia un rilascio recente, che supporti Swift Package Manager su iOS (il default per i nuovi progetti Capacitor 8 iOS) e che copra i tipi di overlay necessari. I plugin mappa nativi condividono lo stesso compromesso di layering del plugin ufficiale: la mappa è una view nativa e il tuo HTML deve essere disposto attorno ad essa.
Mantieni @capacitor/google-maps se
- Ti servono la mappa base di Google, i dati di Places e Street View.
- La tua mappa è una visualizzazione a tutto schermo, non una piccola card in un contenuto scrollabile.
- Puoi gestire il movimento dei marker con remove e add, o aggiorni le posizioni raramente.
Se decidi di tenerlo, imposta la trasparenza CSS sopra, fornisci il <capacitor-google-map> un elemento con dimensioni esplicite, chiama destroy() uscendo dalla pagina, e imposta skipLibCheck: true in tsconfig.json come richiesto dal README del plugin.
Plugin che si integrano bene con qualsiasi mappa
Indipendentemente da cosa renderizzi la mappa, questi plugin Capgo coprono le funzionalità native che una mappa in WebView non può gestire da sola.
Gestisci la navigazione turn-by-turn
Sviluppare un sistema di navigazione è un progetto complesso. La maggior parte delle app preferisce aprire l'app di navigazione predefinita dell'utente. @capgo/capacitor-launch-navigator supporta Apple Maps, Google Maps, Waze e molti altri:
import { LaunchNavigator, TransportMode } from '@capgo/capacitor-launch-navigator';
await LaunchNavigator.navigate({
destination: [48.8584, 2.2945], // [lat, lng]
options: { transportMode: TransportMode.DRIVING },
});Geocoding senza un web service
@capgo/capacitor-nativegeocoder utilizza i geocoder della piattaforma su iOS e Android, che non richiedono una chiave Google sul dispositivo:
import { NativeGeocoder } from '@capgo/capacitor-nativegeocoder';
const { addresses } = await NativeGeocoder.reverseGeocode({
latitude: 48.8584,
longitude: 2.2945,
maxResults: 1,
});
console.log(addresses[0]?.thoroughfare, addresses[0]?.locality);
const result = await NativeGeocoder.forwardGeocode({
addressString: '5 Avenue Anatole France, Paris',
maxResults: 1,
});
console.log(result.addresses[0]?.latitude, result.addresses[0]?.longitude);Sul web, il plugin utilizza API di Google e richiede il apiKey opzione.
Mostra la posizione dell'utente, anche in background
Per un "pallino blu" in foreground, @capacitor/geolocation è sufficiente. Per continuare il tracciamento mentre l'app è in background, o per attivare eventi quando gli utenti entrano in determinati luoghi, usa @capgo/background-geolocation, e passa i punti alla mappa scelta.
Risoluzione problemi mappe in Capacitor
Mappa vuota su Android con il plugin ufficiale. Manca la trasparenza su un elemento padre. Ispeziona con Chrome DevTools tramite chrome://inspect e cerca eventuali colori di sfondo tra <html> e l'elemento della mappa.
L'elemento mappa ha altezza zero. I container della mappa non hanno una dimensione intrinseca. Imposta un'altezza esplicita o usa un layout flex con un'altezza fissa del padre.
La mappa WebGL è sfocata o lenta su Android. Verifica che il System WebView sia aggiornato sul dispositivo, riduci il numero di layer ed evita di ricreare la mappa a ogni cambio di rotta. Creala una volta e riutilizzala.
I tile non si caricano nelle build di release. Controlla la Content Security Policy e la configurazione di rete, assicurandoti che l'host dei tile sia HTTPS.
La mappa si rompe dopo aver cambiato l'URL dello stile dei tile. Style e URL dei tile sono solo configurazioni JavaScript. Puoi cambiare provider per gli utenti esistenti con Capgo live updates, senza un rilascio sugli store, purché non ci siano modifiche native a code.
Come decidere
- Ti servono i dati di Google e performance native su una mappa full screen: resta su
@capacitor/google-maps. - Ti serve uno stile custom, zero costi Google e una mappa che si comporti come HTML: MapLibre GL JS.
- Ti serve una mappa semplice con pochi marker: Leaflet.
- Ti serve l'aspetto di Google in un layout a scorrimento: Google Maps JS API nella WebView.
Qualunque soluzione tu scelga, testala subito su un dispositivo Android economico. Per altri componenti nativi, consulta la directory dei plugin Capgo.
