Kartenfunktionen in der WoltLab Suite: Einrichtung und Betrieb

Zweck

Einige unserer Anwendungen nutzen interaktive Karten. Damit diese Funktionen laufen, müssen Sie die Google-Maps-Dienste korrekt einrichten und in der WoltLab Suite konfigurieren.

Voraussetzungen

• Google-Konto und Projekt in der Google Maps Platform
• Ein API-Schlüssel
• Abrechnung aktiviert, da Google Maps grundsätzlich kostenpflichtig ist. Google stellt in der Regel ein monatliches Startguthaben bereit. Die aktuellen Konditionen entnehmen Sie Ihrem Google-Dashboard.

Schritt 1: API-Schlüssel anlegen

1. In der Google Cloud Console ein Projekt anlegen oder wählen.
2. APIs & Dienste → Anmeldedaten → Anmeldedaten erstellen → API-Schlüssel.
3. Schlüssel sofort einschränken:
   • Für Browser-Aufrufe: HTTP-Referrer (z. B. https://ihre-domain.tld/*)
   • Für serverseitige Funktionen: IP-Adresse des Servers
4. Nur die benötigten APIs freigeben (siehe unten).

Zitat

Gute Praxis: Einen Schlüssel für Browser-Zugriffe und einen separaten Schlüssel für serverseitige Aufgaben verwenden.

Schritt 2: Benötigte Google-APIs aktivieren

Minimal erforderlich:

• Maps JavaScript API
• Geocoding API

Optional, falls Routen angezeigt oder berechnet werden:

• Directions API

Aktivieren Sie diese im Bereich APIs & Dienste → Bibliothek für Ihr Projekt.

Schritt 3: WoltLab konfigurieren

• ACP → Konfiguration → Allgemein → System → Browser-API-Schlüssel
  API-Schlüssel eintragen.
• ACP → Konfiguration → Allgemein → System → Google Maps
  Grundwerte prüfen/anpassen:
  • Start-Zoom
  • Standard-Position der Karte (Breiten-/Längengrad)
  • ggf. Sprache und Region

Eingaben in Formularen

Ortsfelder unterstützen in der Regel Vorschläge während der Eingabe. Diese kommen aus der Google-Suche. Geben Sie den Ort aus, warten Sie kurz auf Vorschläge und wählen Sie dann den passenden Eintrag. Bei Karten mit Marker-Eingabe kann der Ort alternativ direkt auf der Karte gewählt oder verschoben werden.

Tests und Fehlersuche

1. Seite mit Karte öffnen.
2. Browser-Konsole prüfen (F12 → „Konsole“). Häufige Hinweise:
   • „API key invalid“ oder „RefererNotAllowedMapError“ → Schlüsselbeschränkungen prüfen
   • „Quota exceeded“ → Kontingente angepasst oder aufgebraucht
   • „API not activated“ → erforderliche API in der Bibliothek aktivieren
3. Falls serverseitige Funktionen beteiligt sind: Server-Log prüfen und IP-basierte Beschränkung des Server-Schlüssels verifizieren.

Kosten im Blick behalten

• Google berechnet kleine Beträge pro Karten-, Geocoding- und Routing-Aufruf.
• Es gibt üblicherweise ein monatliches Guthaben. Erst darüber hinaus entstehen Kosten.
• Prüfen Sie regelmäßig Nutzung und Kontingente in der Google-Konsole.

Schlüssel einschränken und Kontingente setzen

• Key-Restrictions sind Pflicht:
  • Browser-Key nur für Ihre Domains freigeben, z. B. https://example.com/* und https://www.example.com/*
  • Server-Key auf die öffentliche Server-IP begrenzen
• Quotas setzen, um Kosten zu kontrollieren, z. B. tägliche Limits für Kartenaufrufe oder Geocoding. Erhöhen Sie diese nur, wenn es fachlich nötig ist.

Zusätzlicher Browser-Schlüssel (optional)

Für Lastverteilung oder differenzierte Limits können Sie einen zweiten Browser-Key nutzen, der nur für Geocoding freigegeben ist. Beschränken Sie diesen Key ausschließlich auf die benötigten APIs und die richtigen Referrer.

Häufige Stolpersteine

• Falsche Restriction-Art: Browser-Key fälschlich auf IP statt auf HTTP-Referrer begrenzt. Ergebnis: Karte lädt nicht.
• Zu enge Referrer-Maske: Statt einzelner Seiten die Domain mit Wildcard eintragen, z. B. https://example.com/*.
• API vergessen zu aktivieren: Maps JavaScript API aktiv, Geocoding API jedoch nicht.
• Gemischte Inhalte: Seite per HTTPS, Karten-Asset per HTTP eingebunden. Immer HTTPS verwenden.
• Abrechnung nicht aktiv: Ohne Billing bleiben Aufrufe blockiert.

Checkliste zum Abschluss

• Projekt und Abrechnung eingerichtet
• Browser-Key mit Referrer-Beschränkung
• Server-Key mit IP-Beschränkung (falls benötigt)
• Maps JavaScript, Geocoding und ggf. Directions API aktiviert
• Schlüssel im ACP hinterlegt
• Start-Zoom und Standard-Position gesetzt
• Quotas definiert und überwacht
• Funktion per Browser-Konsole getestet