Wenn du eine Alternative zu Capacitor Google Maps brauchst, hast du drei realistische Wege: beim offiziellen @capacitor/google-maps Plugin bleiben und seine Limits umgehen, die Karte mit einer JavaScript-Bibliothek wie MapLibre GL JS oder Leaflet im WebView rendern, oder ein natives Map-Plugin auf Basis eines anderen SDK nutzen. Capgo bietet kein eigenes Map-Rendering-Plugin an, daher vergleicht dieser Guide die Optionen neutral und zeigt die Capgo Plugins, die sich gut mit jeder Karte kombinieren lassen: Navigation Handoff, Geocoding und Background Location.
Warum Entwickler über @capacitor/google-maps hinausschauen
Das offizielle Plugin (Version 8 für Capacitor 8) bettet das native Google Maps SDK auf iOS und Android sowie die Google Maps JavaScript API im Web ein. Es funktioniert, aber diese Punkte tauchen immer wieder auf.
Ein Google-Cloud-Konto mit aktiviertem Billing auf jeder Plattform
Das Plugin benötigt API-Keys, die mit einem Google-Cloud-Konto mit aktiviertem Billing verknüpft sind – auf Android, iOS und im Web. Googles Preisgestaltung für native Map-Loads auf Mobilgeräten ist großzügig, aber du musst Billing einrichten, Keys pro Plattform einschränken und Quotas im Auge behalten. Web-Map-Loads und Services wie Places und Directions werden nach Ausschöpfung der kostenlosen Kontingente nutzungsbasiert abgerechnet. Prüfe die aktuelle Preisseite der Google Maps Platform, bevor du dich festlegst, da sich das Modell 2025 geändert hat.
Auf Android wird die Map hinter der WebView gezeichnet
Auf iOS wird die Map-View in die ScrollView der WebView eingebettet. Auf Android wird sie unter der gesamten WebView gerendert, und das Plugin verschiebt sie, um dem <capacitor-google-map> Element zu folgen. Jede Ebene darüber muss transparent sein:
/* Required on Android with @capacitor/google-maps */
html,
body,
ion-content,
ion-content::part(background) {
background: transparent !important;
--background: transparent;
}Das ist das Hauptproblem bei „meine Map ist leer“. Zudem erschwert es Custom Overlays, Modals und Page Transitions, da dein HTML über einer nativen View liegt.
Markers can be added and removed, not updated
Die API hat addMarker, addMarkers, removeMarker und removeMarkers, aber kein updateMarker. Eine Live-Fahrzeugposition bedeutet bei jeder Aktualisierung Entfernen plus Hinzufügen, was zu Flackern führen kann und Bridge-Calls kostet.
Eingeschränktes Styling und eingeschränkte Features nativ
Einige Optionen sind nur für Web verfügbar, zum Beispiel mapId für cloud-basiertes Styling, und region und language. Du erhältst Marker, Clustering, Polylines, Polygone, Kreise, Tile-Overlays, Kamera-Steuerung und Click-Listener. Wenn du datengetriebenes Styling, Heatmaps oder 3D-Gebäude auf allen Plattformen auf dieselbe Weise benötigst, stößt du an Grenzen.
Die Optionen im Überblick
| Option | Rendering | API-Key erforderlich | Tile-Quelle | Ideal für |
|---|---|---|---|---|
@capacitor/google-maps |
Native SDK (Android, iOS), JS im Web | Ja, Abrechnung aktiviert | Apps, die Google-Daten und native Performance wollen | |
| MapLibre GL JS | WebGL in der WebView | Abhängig vom Tile-Provider | Beliebige Vector-Tile-Quellen, Self-Hosting möglich | Individuelle Map-Styles, quasi offline, kein Vendor-Lock-in |
| Leaflet | DOM und Canvas in der WebView | Abhängig vom Tile-Provider | Raster-Kacheln (OSM-basiert oder andere) | Einfache Karten, kleines Bundle, viele Plugins |
| Google Maps JS API im WebView | Googles JS-Renderer | Ja | Gleicher Google-Look auf allen Plattformen, volles JS-Feature-Set | |
| Native MapLibre- oder Mapbox-Plugins | Native SDK | Abhängig | Beliebig / Mapbox | Schwere Daten, lange Sessions, native Gesten |
Es gibt keinen eindeutigen Sieger. Die richtige Wahl hängt vom Datenvolumen, den Styling-Anforderungen und davon ab, wie stark du dich an einen Anbieter binden willst.
Option 1: MapLibre GL JS in der WebView
MapLibre GL JS ist der Open-Source-Fork von Mapbox GL JS v1. Es rendert Vector Tiles mit WebGL und läuft gut in WKWebView und der Android System WebView. Die flexibelste Wahl, wenn du Googles Daten nicht brauchst.
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]);
}GeoJSON-Layer, Data-driven Styling und Routenlinien sind erstklassig unterstützt:
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 },
});
});Was du wissen solltest:
- Du brauchst eine Tile-Quelle. Zur Auswahl stehen kommerzielle Vector-Tile-Hosts oder Self-Hosting von Tiles, die aus OpenStreetMap-Daten erzeugt werden. Die öffentlichen OpenStreetMap-Tile-Server haben eine Usage Policy, die starken App-Traffic nicht erlaubt.
- Zeige immer die Attribution an, die dein Tile-Provider verlangt.
- Da es reines Web code ist, funktioniert dieselbe Karte auch in der Browser-Vorschau, was die Entwicklung beschleunigt.
Option 2: Leaflet
Leaflet ist klein und ausgereift. Es passt gut für Karten mit ein paar hundert Markern, Raster-Tiles und einfachen Interaktionen.
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');In Bundled Apps funktionieren die Standard-Pfade der Leaflet-Marker-Icons oft nicht. Importiere die Icon-Bilder und setze die L.Icon.Default Optionen oder nutze eigene Icons L.divIcon.
Option 3: Google Maps JavaScript API im WebView
Wenn du Googles Daten und Look brauchst, aber die Karte wie jedes andere HTML-Element verhalten soll, lade die Maps JavaScript API in der WebView statt des nativen SDK. Du verlierst etwas native Smoothness, und jeder Karten-Ladevorgang ist eine abrechenbare Web-Load, aber du bekommst die volle JS API: Cloud-Styling mit Map-IDs, erweiterte Marker, Data-Layers.
Schränke den Web-Key per HTTP-Referrer ein. Auf iOS wird die App von Capacitor aus ausgeliefert capacitor://localhost standardmäßig, und auf Android von https://localhost, füge also diese Origins zu den Key-Einschränkungen hinzu und teste beide.
Option 4: Native Plugins auf Basis anderer SDKs
Native Wrapper um MapLibre Native oder die Mapbox-SDKs existieren in der Community. Sie bieten native Gesten und Performance mit jeder Tile-Quelle. Bevor du dich für einen entscheidest, prüfe, ob er Capacitor 8 unterstützt, eine aktuelle Version hat, Swift Package Manager auf iOS unterstützt (Standard für neue Capacitor 8 iOS-Projekte) und die Overlay-Typen abdeckt, die du brauchst. Native Map-Plugins teilen denselben Layering-Trade-off wie das offizielle Plugin: Die Karte ist eine native View, und dein HTML muss darum herum layoutet werden.
Nutze @capacitor/google-maps, wenn
- Du brauchst Googles Basiskarte, Places- und Street-View-Daten.
- Deine Karte ist eine Vollbildansicht, keine kleine Karte innerhalb scrollender Inhalte.
- Du kannst damit leben, Marker zu entfernen und neu hinzuzufügen, oder Positionen nur selten zu aktualisieren.
Wenn du es behältst, setze die oben genannte Transparenz-CSS und gib der <capacitor-google-map> dem Element eine explizite Größe geben, rufen Sie destroy() beim Verlassen der Seite, und setzen Sie skipLibCheck: true in einem tsconfig.json wie im README des Plugins gefordert.
Plugins, die gut mit jeder Karte harmonieren
Egal, was die Karte rendert, decken diese Capgo Plugins die nativen Teile ab, die eine WebView-Karte nicht allein leisten kann.
Turn-by-Turn-Navigation auslagern
Die Entwicklung einer Navigation ist ein eigenes Projekt. Die meisten Apps öffnen stattdessen die bevorzugte Navigations-App des Nutzers. @capgo/capacitor-launch-navigator unterstützt Apple Maps, Google Maps, Waze und viele weitere:
import { LaunchNavigator, TransportMode } from '@capgo/capacitor-launch-navigator';
await LaunchNavigator.navigate({
destination: [48.8584, 2.2945], // [lat, lng]
options: { transportMode: TransportMode.DRIVING },
});Geocoding ohne Web-Service
@capgo/capacitor-nativegeocoder nutzt die Plattform-Geocoder auf iOS und Android, die auf dem Gerät keinen Google-Key benötigen:
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);Im Web nutzt das Plugin Googles API und benötigt den apiKey Option.
Den Standort des Nutzers auch im Hintergrund anzeigen
Für einen blauen Punkt im Vordergrund, @capacitor/geolocation reicht das aus. Um die Ortung fortzusetzen, während die App im Hintergrund ist, oder Ereignisse auszulösen, wenn Nutzer Orte betreten, verwenden Sie @capgo/background-geolocation, und übergeben Sie die Punkte an die von Ihnen gewählte Karte.
Fehlersuche bei Kartenproblemen in Capacitor
Leere Karte auf Android mit dem offiziellen Plugin. Transparenz fehlt an einem Parent-Element. Prüfe mit Chrome DevTools via chrome://inspect und suche nach jeder Hintergrundfarbe zwischen <html> und dem Map-Element.
Map-Element hat Höhe 0. Map-Container haben keine intrinsische Größe. Setze eine explizite Höhe oder verwende ein Flex-Layout mit einer festen Höhe des Parent-Elements.
WebGL-Map ist auf Android unscharf oder langsam. Prüfe, ob das System WebView aktuell ist, reduziere die Layer-Anzahl und vermeide das Neuerstellen der Map bei jedem Route-Change. Erstelle sie einmal und verwende sie wieder.
Tiles laden nicht in Release-Builds. Prüfe deine Content Security Policy und die Network Security Config; stelle sicher, dass der Tile-Host HTTPS verwendet.
Map funktioniert nach dem Ändern der Tile-Style-URL nicht mehr. Style- und Tile-URLs sind reine JavaScript-Configs. Du kannst den Provider für bestehende Nutzer wechseln mit Capgo Live Updates, ohne einen App Store Release, solange keine nativen code Änderungen vorgenommen werden.
So entscheidest du
- Du brauchst Google-Daten und native Performance auf einer Full-Screen-Map: bleib bei
@capacitor/google-maps. - Du brauchst Custom Styling, kein Google-Billing und eine Map, die sich wie HTML verhält: MapLibre GL JS.
- Du brauchst eine einfache Map mit ein paar Markern: Leaflet.
- Du brauchst den Google-Look in einem Scrolling-Layout: Google Maps JS API im WebView.
Egal wofür du dich entscheidest, teste frühzeitig auf einem Low-End-Android-Gerät. Für weitere native Bausteine schau in die Capgo Plugin-Verzeichnis.
