You are here: For app developers

Request a demo

01 — For app developers

Embed an event map in your app

If you build the event app, you do not need to build a map. Embed the STUMaps event map in a WebView, talk to it through a small JavaScript bridge and open it from deep links.

02 — WebView

WebView embedding in four steps

  1. Open the map URL

    Load the event’s map URL in WKWebView (iOS), WebView (Android) or react-native-webview. Pass ?lang= to match the app language.

  2. Register the handler

    Add the message handler named in the map config (iOS) or a JavaScript interface (Android); React Native receives onMessage.

  3. Wait for “ready”

    The map sends ready with the bridge version once it can take commands.

  4. Call and listen

    Open places and build routes from native screens; react to the events the map sends back.

03 — JavaScript

The JavaScript bridge

The map exposes an object on window with three commands. Each returns false when the place or language is unknown.

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 } }

Events back to the app: ready, poi_opened, route_built (with metres, seconds and floors), share_image and share_link — so the app can use its own share sheet.

05 — WKWebView · Android WebView

Honest limitations

Three things a WebView cannot do on its own — and how they are handled.

  • Web push does not work in a WebView

    Push notifications are sent by your app. The map provides an API or a webhook so your push service can send its alerts; this is set up per project.

  • Offline in iOS WKWebView needs App-Bound Domains

    The service worker that keeps the map offline only runs in WKWebView for domains listed as App-Bound Domains in the app. Without them the map still works online.

  • Location and camera are granted by the app

    The WebView can only use location or the camera (for QR codes) when the app has the permission and passes it on to the WebView.

Embedding an event map in your app: a WebView checklist

06 — FAQ

Questions

Does the map need an SDK?

No. It is a web page; the bridge is plain JavaScript messages between the page and your app.

Can the map match our app’s design?

Colours for light and dark themes, fonts, logo and wording come from the map configuration.

What if our app is built with React Native?

Use react-native-webview: the map posts its events to ReactNativeWebView, and you call the bridge with injectJavaScript.

Finish

Have a venue in mind?

Send the plan and the dates, and we will reply with what a map for your venue would take.

Request a demo Get a quote