API-Konfiguration

Im dritten Schritt des Karten-Setups werden die API-Keys für Google Maps und/oder MapTiler konfiguriert. Dieser Schritt erscheint nur, wenn du diese Anbieter aktiviert hast.

Übersicht

Die API-Konfiguration umfasst:

Cloud Functions

Sichere Key-Verwaltung in Firebase.

Verschlüsselung

Keys werden verschlüsselt gespeichert.

Validierung

Automatische Prüfung der API-Keys.

Admin-Zugriff

Nur Admins können Keys verwalten.

---

Was du im Setup siehst

Der API-Konfiguration Schritt zeigt dir:

1. Titel: „API-Konfiguration”

2. Beschreibung: „Richten Sie die API-Keys für Google Maps und MapTiler ein.”

3. Info-Box: „Für Google Maps und MapTiler werden API-Keys benötigt. Diese werden sicher in Cloud Functions gespeichert.”

4. Was eingerichtet wird:

   • Cloud Functions für sichere Key-Verwaltung
   • Sichere Speicherung der API-Keys
   • Zugriffsbeschränkungen auf Admin-Rolle
   • Validierung der API-Keys

5. Buttons:

   • „Wizard starten” - Geführtes Setup
   • „Überspringen (nur OpenStreetMap)” - API-Keys später einrichten

---

Optionen

Wizard starten

Empfohlen

Geführtes API-Setup

Eigenschaft	Wert
Dauer	ca. 5-10 Minuten
Voraussetzung	Service Account konfiguriert
Schritte	5 Schritte

Der Wizard führt dich durch:

1. Cloud Functions Deployment
2. Anbieter-Auswahl bestätigen
3. API-Keys eingeben
4. Keys validieren
5. Speichern und abschließen

Empfehlung

Nutze den Wizard für eine sichere und geführte Einrichtung.

Überspringen

Nur OpenStreetMap verwenden

Eigenschaft	Wert
Dauer	Sofort
Voraussetzung	Keine
Verfügbare Anbieter	Nur OpenStreetMap

Wenn du überspringst:

• Nur OpenStreetMap ist verfügbar
• Du kannst API-Keys später in den Einstellungen hinzufügen

Hinweis: „Sie können API-Keys später in den Einstellungen hinzufügen.”

Später einrichten

Du kannst die API-Konfiguration jederzeit im Karten-Editor nachholen.

---

Der API-Konfiguration Wizard

Wizard-Flow

Der Wizard durchläuft 5 Phasen:

Deployment → Intro → Provider → Keys → Abschluss

Phase	Beschreibung
Deployment	Cloud Functions bereitstellen
Intro	Übersicht der Features
Provider	Anbieter auswählen
Keys	API-Keys eingeben und validieren
Abschluss	Zusammenfassung und Speichern

---

Phase 1: Cloud Functions Deployment

1. Wizard starten

   Tippe auf „Wizard starten”. Der Wizard öffnet sich mit dem Titel „Karten einrichten”.

2. Service Account prüfen

   Der Wizard prüft, ob ein Service Account konfiguriert ist.

   Status	Anzeige
   ✅ Konfiguriert	Deployment kann starten
   ❌ Nicht konfiguriert	Fehlermeldung mit Hinweis

3. Deployment starten

   Die Cloud Functions werden automatisch deployed:

   • „Cloud Functions werden eingerichtet…”
   • „Die Maps Cloud Functions werden in Ihrem Firebase-Projekt deployed.”

4. Status prüfen

   Ergebnis	Meldung
   ✅ Erfolgreich	„Einrichtung erfolgreich!”
   ✅ Demo-Modus	„Einrichtung erfolgreich (Demo-Modus)”
   ❌ Fehler	„Einrichtung fehlgeschlagen”

5. Weiter zum Intro

   Bei Erfolg tippe auf „Weiter”, um fortzufahren.

Demo-Modus

Im AppBuilder-Modus wird das Deployment simuliert. Die eigentlichen Cloud Functions werden beim Kunden-App-Export deployed.

---

Phase 2: Intro

Nach erfolgreichem Deployment siehst du eine Übersicht:

Titel: „Interaktive Karten”

Untertitel: „Integrieren Sie Karten in Ihre App - einfach und datenschutzkonform.”

Features:

• OpenStreetMap - kostenlos & ohne API-Key
• Google Maps - hochwertige Karten
• MapTiler - stilvolle Designs
• Intelligentes Marker-Clustering
• DSGVO-konformes Consent-Management

Tippe auf „Karten einrichten”, um fortzufahren.

---

Phase 3: Anbieter auswählen

Bestätige oder ändere die Anbieter-Auswahl:

Titel: „Anbieter wählen”

Beschreibung: „Aktivieren Sie einen oder mehrere Kartenanbieter für Ihre App.”

Verfügbare Anbieter

Anbieter	Beschreibung	API-Key
OpenStreetMap	Kostenlos, Open Source, keine API-Keys nötig. Ideal für den Start.	Nicht nötig
Google Maps	Hochwertige Karten mit Street View, erfordert Google Cloud Account.	Erforderlich
MapTiler	Moderne Kartenstile, EU-Server, erfordert MapTiler Account.	Erforderlich

Aktiviere die gewünschten Anbieter durch Antippen der Checkboxen.

Mehrere Anbieter

Du kannst mehrere Anbieter gleichzeitig aktivieren. OpenStreetMap ist als Fallback empfohlen.

---

Phase 4: API-Keys eingeben

Wenn du Google Maps oder MapTiler aktiviert hast, gibst du hier die API-Keys ein:

Titel: „API-Keys eingeben”

Beschreibung: „Geben Sie die API-Keys für die gewählten Anbieter ein.”

Sicherheitshinweis: „Die Keys werden sicher in Cloud Functions gespeichert und sind nicht im App-Code sichtbar.”

Google Maps API-Key

Key eingeben

Eingabefeld für Google Maps

Eigenschaft	Wert
Format	Beginnt mit AIza...
Länge	ca. 39 Zeichen
Beispiel	AIzaSyC1234567890abcdefghijklmnop

Gib deinen Google Maps API-Key in das Eingabefeld ein.

Validierung

Key validieren

Tippe auf „Key validieren”, um den Key zu prüfen.

Status	Meldung
⏳ Prüfung	„Validiere…”
✅ Gültig	„API-Key erfolgreich gesetzt”
❌ Leer	„Bitte geben Sie einen API-Key ein”
❌ Format	„Google Maps API-Keys beginnen mit ‚AIza’”
❌ Fehler	„Validierung fehlgeschlagen”

Format-Check

Google Maps API-Keys beginnen immer mit AIza. Wenn dein Key anders beginnt, ist er möglicherweise falsch kopiert.

Key erstellen

Google Maps API-Key erstellen

1. Öffne die Google Cloud Console

2. Erstelle ein neues Projekt oder wähle ein bestehendes

3. Aktiviere die mobilen Maps-SDKs (BLOCQ ist eine native iOS-/Android-App – die „Maps JavaScript API” für Web wird nicht benötigt):

   • Gehe zu APIs & Services > Library
   • Suche nach „Maps SDK for Android” und klicke auf Enable
   • Suche nach „Maps SDK for iOS” und klicke auf Enable

4. Erstelle den API-Key:

   • Gehe zu APIs & Services > Credentials
   • Klicke auf Create Credentials > API key

5. Kopiere den generierten Key

6. Empfohlen: Beschränke den Key auf deine App

   • Klicke auf den Key
   • Unter API restrictions wähle die beiden aktivierten Maps-SDKs aus
   • Unter Application restrictions kannst du den Key zusätzlich per Android apps (Package-Name + SHA-1) bzw. iOS apps (Bundle-ID) einschränken

Key schützen

Beschränke deinen API-Key auf deine App (Package-Name/Bundle-ID), um Missbrauch zu verhindern.

Web-API nur für Vorschauen

Falls du Karten zusätzlich in einer Web-Vorschau (z.B. Astro-Plattformseite) anzeigst, aktiviere dafür separat die Maps JavaScript API und beschränke den Key dort über Application restrictions → Websites (früher „HTTP referrers”). Für die mobile App selbst sind ausschließlich die beiden Maps-SDKs nötig. Der AIza…-Key ist das universelle Google-API-Key-Format (kein spezielles „SDK-Key”).

MapTiler API-Key

Key eingeben

Eingabefeld für MapTiler

Eigenschaft	Wert
Format	Alphanumerischer String
Länge	ca. 32 Zeichen
Beispiel	abc123def456ghi789jkl012mno345

Gib deinen MapTiler API-Key in das Eingabefeld ein.

Validierung

Key validieren

Tippe auf „Key validieren”, um den Key zu prüfen.

Status	Meldung
⏳ Prüfung	„Validiere…”
✅ Gültig	„API-Key erfolgreich gesetzt”
❌ Leer	„Bitte geben Sie einen API-Key ein”
❌ Kurz	„Der MapTiler API-Key scheint zu kurz”
❌ Fehler	„Validierung fehlgeschlagen”

Key erstellen

MapTiler API-Key erstellen

1. Öffne maptiler.com

2. Erstelle einen kostenlosen Account oder melde dich an

3. Gehe zum Dashboard

4. Klicke auf Create a new key oder API Keys

5. Gib einen Namen ein (z.B. „Meine App”)

6. Kopiere den generierten Key

Kostenloses Kontingent

MapTiler bietet ca. 100.000 kostenlose Kartenaufrufe pro Monat.

Keys speichern

Wenn alle erforderlichen Keys eingegeben sind:

1. Tippe auf „Keys speichern”
2. Die Keys werden an Cloud Functions gesendet
3. Status wird angezeigt:
   • „Speichere…”
   • „API-Keys erfolgreich gespeichert” (bei Erfolg)
   • „Fehler beim Speichern der API-Keys” (bei Fehler)

---

Phase 5: Abschluss

Nach erfolgreichem Speichern siehst du eine Zusammenfassung:

Titel: „Einrichtung abgeschlossen!”

Untertitel: „Das Karten-Modul ist jetzt einsatzbereit.”

Zusammenfassung:

Eigenschaft	Wert
Standard-Anbieter	Der primär verwendete Anbieter
Aktivierte Anbieter	Liste aller aktivierten Anbieter
Datenschutz	DSGVO-konform

Tippe auf „Einrichtung abschließen”, um den Wizard zu beenden.

---

Sicherheit

Die API-Keys werden sicher gespeichert:

Speicherort

Aspekt	Beschreibung
Wo	Firebase Cloud Functions
Wie	Verschlüsselt in Secret Manager
Zugriff	Nur Server-seitig

Vorteile

• ✅ Keys sind nicht im App-Code sichtbar
• ✅ Kein Reverse Engineering möglich
• ✅ Server-seitige Validierung
• ✅ Nur Admins können Keys ändern

Best Practice

Die Speicherung in Cloud Functions ist die sicherste Methode, um API-Keys vor Missbrauch zu schützen.

---

Fehlerbehandlung

Service Account nicht konfiguriert

Status	Lösung
Meldung	„Service Account erforderlich”
Aktion	Service Account einrichten

👉 Service Account einrichten

Deployment fehlgeschlagen

Ursache	Lösung
Keine Berechtigung	Service Account Rechte prüfen
Netzwerkfehler	Internetverbindung prüfen
Firebase-Fehler	Firebase-Konfiguration prüfen

Key-Validierung fehlgeschlagen

Ursache	Lösung
Falsches Format	Key erneut aus Konsole kopieren
Key deaktiviert	Key in der Konsole aktivieren
Quota überschritten	Kostenlimits prüfen

---

Tipps

Keys sorgfältig kopieren

Kopiere die API-Keys direkt aus der jeweiligen Konsole. Stelle sicher, dass keine Leerzeichen am Anfang oder Ende sind.

Keys beschränken

Beschränke deine API-Keys auf deine App-Domain, um Missbrauch zu verhindern.

Später ändern

Du kannst die API-Keys jederzeit im Karten-Editor ändern oder neue hinzufügen.

Kosten im Blick

Überwache deine API-Nutzung in den jeweiligen Konsolen, um unerwartete Kosten zu vermeiden.

---

Nächste Schritte

Karten-Editor Karteneinstellungen anpassen

Service Account Für automatisches Deployment

Zurück zur Übersicht Karten-Setup Übersicht