01 — Dla twórców aplikacji
Osadź mapę wydarzenia w swojej aplikacji
Jeśli tworzysz aplikację wydarzenia, nie musisz budować mapy. Osadź mapę STUMaps w WebView, komunikuj się z nią przez niewielki most JavaScript i otwieraj ją linkami głębokimi.
02 — WebView
Osadzenie w WebView w czterech krokach
-
Otwórz adres mapy
Załaduj adres mapy wydarzenia w WKWebView (iOS), WebView (Android) lub react-native-webview. Dodaj ?lang=, aby język mapy zgadzał się z językiem aplikacji.
-
Zarejestruj obsługę wiadomości
Dodaj message handler o nazwie z konfiguracji mapy (iOS) albo interfejs JavaScript (Android); React Native dostaje onMessage.
-
Poczekaj na „ready”
Mapa wysyła ready z wersją mostu, gdy jest gotowa na polecenia.
-
Wywołuj i nasłuchuj
Otwieraj miejsca i wyznaczaj trasy z natywnych ekranów; reaguj na zdarzenia z mapy.
03 — JavaScript
Most JavaScript
Mapa udostępnia w window obiekt z trzema poleceniami. Każde zwraca false, gdy miejsce lub język są nieznane.
const map = window.NoctaraRunMap; // name from the map config
map.open('water-5'); // true | false
map.route('tram-wawel-01', 'start');
map.setLang('pl');
// iOS: webkit.messageHandlers[...] Android: JavaScript interface
// React Native: ReactNativeWebView.postMessage
{ source: 'noctara-run-map', type: 'route_built', payload: { from, to, meters, seconds, floors } }Zdarzenia do aplikacji: ready, poi_opened, route_built (z metrami, sekundami i piętrami), share_image i share_link — aplikacja może użyć własnego okna udostępniania.
04 — URL
Linki głębokie
Każdy stan, którym warto się podzielić, ma swój adres — może go otworzyć kod QR, powiadomienie push albo przycisk.
?poi=<id> | otwiera kartę miejsca |
?from=<id>&to=<id> | pokazuje trasę pieszą |
?lang=en|pl|ru | język interfejsu |
?stepfree=1 | trasy bez schodów od początku |
?kiosk=1 | tryb kiosku na ekran informacyjny |
?runner=<bib> | karta biegacza (mapy biegów) |
05 — WKWebView · Android WebView
Ograniczenia, o których mówimy wprost
Trzy rzeczy, których WebView nie zrobi sam — i jak je rozwiązujemy.
-
Web push nie działa w WebView
Powiadomienia push wysyła Twoja aplikacja. Mapa udostępnia API lub webhook, przez które Twój serwis push może wysłać komunikaty; konfigurujemy to w każdym projekcie.
-
Offline w iOS WKWebView wymaga App-Bound Domains
Service worker, dzięki któremu mapa działa offline, uruchamia się w WKWebView tylko dla domen wpisanych w aplikacji jako App-Bound Domains. Bez nich mapa działa online.
-
Lokalizację i aparat przyznaje aplikacja
WebView może użyć lokalizacji lub aparatu (do kodów QR) tylko wtedy, gdy aplikacja ma uprawnienie i przekazuje je do WebView.
06 — FAQ
Pytania
Czy mapa wymaga SDK?
Nie. To strona internetowa; most to zwykłe wiadomości JavaScript między stroną a aplikacją.
Czy mapa może pasować do wyglądu naszej aplikacji?
Kolory jasnego i ciemnego motywu, czcionki, logo i słownictwo ustawia się w konfiguracji mapy.
A jeśli aplikacja jest w React Native?
Użyj react-native-webview: mapa wysyła zdarzenia do ReactNativeWebView, a most wywołujesz przez injectJavaScript.
Masz teren, któremu przyda się mapa?
Prześlij plan i daty, a odpowiemy, czego wymagałaby mapa dla Twojego terenu.