Anwendungen mit Kartenfunktion

Mittlerweile sind einige Anwendungen mit Kartenfunktion für die WoltLab Suite verfügbar. Hier auf zaydowicz.de sind dies die Benutzerkarte, Points of Interest und das Schaufenster.

Voraussetzungen

Bei allen Anwendungen werden diverse APIs von Google Maps genutzt. Diese müssen unabhängig von den Anwendungen zunächst im System verfügbar gemacht werden. Hierzu muss bei Google ein Konto eröffnet, ein Projekt angelegt und ein sogenannter API-Schlüssel für Google Maps erzeugt werden. Dieser API-Schlüssel muss im ACP unter Konfiguration - Allgemein - System - Browser-API-Schlüssel hinterlegt werden.

Da es sich bei Google Maps grundsätzlich um einen kostenpflichtigen Dienst handelt, müssen zur Nutzung der APIs ein Abrechnungskonto erstellt und Zahlungsinformationen hinterlegt werden. In der Regel muss dabei eine Kreditkarte angegeben werden, damit Google entstehende Kosten direkt einziehen kann. Mehr zu den Kosten unten.

Erstellung des API-Schlüssels

Hierauf wird nicht im Detail eingegangen, da es bereits einige Anleitung im Netz gibt.


Eine nach meiner Bewertung gute deutschsprachige Anleitung ist unter Google Maps Api Key erstellen verfügbar. Im ACP wird zu diesem Zweck auf die englischsprachige Google-Seite Get an API Key verwiesen. Nach Aufruf dieser Seite lässt sich durch Klick auf GET STARTED eine dialogbasierte Erstellung in der gewünschten Sprache starten.

Benötigte APIs

Alle Karten-Anwendungen benötigen mindestens die folgenden Google Maps APIs:

  • Maps JavaScript API
  • Geocoding API

Anwendungen, wie die Benutzerkarte, die eine Routenplanung ermöglichen, benötigen zudem die folgende Google Maps API:

  • Directions API

Konfiguration im ACP

Nach Eingabe des API-Schlüssels sollte die grundlegende Karten-Konfiguration im ACP überprüft bzw. angepasst werden. Dies erfolgt unter Konfiguration - Allgemein - System - Google Maps. Hier sind insbesondere der Karten-Zoom und die Standard-Kartenposition (Breiten-/Längengrad) interessant, weil sie den Inhalt der Karte direkt nach dem Öffnen festlegen.


Bei der Benutzerkarte kann dies optional auch der Anwendung überlassen werden; sie kann die dargestellte Karte automatisch an die bisherigen Eingaben anpassen.

Bedienung

Die Bedienung der Karte ist bei allen Anwendungen identisch, weil sie identische Schnittstellen zu Google Maps nutzen.


Ortseingaben können entweder über Bewegen eines Markers auf der Karte (wenn angeboten) oder über Eingabe von Text in einem Feld gemacht werden. Bei Letzteren ist zu beachten, dass beim Eingeben des Textes im Hintergrund eine Google Maps-Suche nach passenden Orten gestartet wird. Sobald passende Orte gefunden werden, werden unterhalb des Feldes Vorschläge angezeigt, die gewählt werden können bzw. sollten. Dem entsprechend sollte die Texteingabe eher langsam und mit etwas Geduld erfolgen.



Zeigt Google keine Ergebnisse an, so wurde der Ort nicht gefunden oder es liegt ein Fehler vor. Dann sollte die Funktion der Karte geprüft werden.

Prüfung der Funktion

Wenn die Karte nicht so funktioniert wie gewünscht, sollte immer zunächst über die JavaScript-Konsole im Browser geprüft werden, ob Fehler vorliegen. Die Konsole kann über die Funktionstaste F12 geöffnet werden. Erfahrungsgemäß liegt bei Fehlern eine Fehlkonfiguration des API-Schlüssels im Google-Konto vor.


Ein typischer Fehler ist im Bild dargestellt; hier wurde das Limit für die Nutzung der Geocoding-API überschritten und Google Maps verweigert deswegen die weitere Nutzung der API.


Nutzern der Benutzerkarte wird empfohlen, regelmäßig das Protokoll der Benutzerkarte im ACP zu kontrollieren. Dort werden auch Hinweise auf Probleme gespeichert.

Kosten und Einschränkungen

Wie schon erwähnt, ist der Google Kartendienst nicht kostenlos. Für jeden Kartenaufruf und für jeden Aufruf der Geocoding- oder Routing-API berechnet Google einen kleinen Betrag. Dieser liegt je nach API, Funktion und Kostenmodell zwischen 0,004 und 0,014 USD. So muss ein normaler Anwender zum Beispiel für 1.000 Kartenaufrufe immerhin 7,00 USD bezahlen.

Allerdings gewährt Google einen Freibetrag in Höhe von 200,00 USD. Erst, wenn dieser überschritten wird, fallen reale Kosten an. Im u.a. Beispiel fallen also Kosten erst ab dem 28571. Kartenaufruf an - wenn nicht schon Kosten für Geocoding und/oder Routing berechnet wurden.


Um insbesondere bei größeren Communities nicht in eine Kostenfalle zu geraten, empfiehlt es sich die Nutzung des API-Schlüssels sowie der APIs einzuschränken.


Dies erfolgt zum einen über Schlüssel-Einschränkungen, die eine nicht autorisierte Verwendung des Schlüssels und einen Kontingentdiebstahl verhindern sollen; siehe dazu die Seite API-Schlüssel einschränken und umbenennen im Google-Konto. Und zum anderen lassen sich die Kontingente für die erlaubten APIs einschränken. So kann man z.B. festlegen, dass nur 500 Kartenaufrufe pro Tag erlaubt sind. Bei 0,007 USD je Aufruf werden dann im Monat nur maximal ca. 105,00 USD an Kosten für Kartenaufrufe berechnet.