Deep Links, Map Events & Analytics (F47, F49, F62)

---

Deep Links (F47)

The SDK encodes map state — floor ordinal, camera position, and optional destination — into URL search parameters so users can bookmark or share a precise view.

URL schema

Parameter	Description
bs_floor	Floor ordinal integer
bs_lat	Camera centre latitude
bs_lng	Camera centre longitude
bs_zoom	Camera zoom level
bs_dest	(optional) Destination unit ID for auto-route

Building deep links

import { buildDeepLink, type DeepLinkState } from '@diginestai/core';

const url = buildDeepLink({
  floor: 2,
  lat: 43.6452,
  lng: -79.3806,
  zoom: 18,
  destinationId: 'unit-b3',
});
// https://your-app.com/map?bs_floor=2&bs_lat=43.6452&bs_lng=-79.3806&bs_zoom=18&bs_dest=unit-b3

Parsing deep links

import { parseDeepLink } from '@diginestai/core';

const state = parseDeepLink(window.location.search);
// DeepLinkState | null

parseDeepLink returns null if required parameters are absent or malformed.

React hook

useDeepLink reads the current URL on mount, applies the state to the map, and keeps the URL in sync as the user navigates:

import { useDeepLink } from '@diginestai/core';

function MapPage() {
  const { state, setDeepLink } = useDeepLink();

  return (
    <SpatialProvider>
      <SpatialMap buildings={[building]}>
        {/* Camera and floor are automatically restored from the URL */}
      </SpatialMap>
    </SpatialProvider>
  );
}

---

Map View Events (F49)

useMapViewEvent is a unified hook that subscribes to typed map interaction events without wiring MapLibre listeners directly.

import { useMapViewEvent, type MapClickEvent } from '@diginestai/core';

function ClickHandler() {
  useMapViewEvent('click', (event: MapClickEvent) => {
    console.log('Clicked unit', event.unitId, 'on floor', event.floorOrdinal);
  });

  useMapViewEvent('floor-change', (event) => {
    console.log('Floor changed to', event.floorOrdinal);
  });

  useMapViewEvent('camera-change', (event) => {
    console.log('Zoom:', event.zoom, 'Centre:', event.center);
  });

  return null;
}

Available event types

Event	Payload type	Description
'click'	MapClickEvent	User tapped a map feature
'hover'	MapHoverEvent	Pointer moved over a feature
'floor-change'	FloorChangeEvent	Active floor ordinal changed
'camera-change'	CameraChangeEvent	Camera moved/zoomed/panned
'space-select'	SpaceSelectEvent	Space selection state changed

All event subscriptions are automatically cleaned up on component unmount.

---

Analytics Hooks (F62)

useAnalytics receives a structured AnalyticsHandler callback and fires it on every meaningful user interaction. Wire it once at the app root and forward events to your analytics platform.

import { useAnalytics, type AnalyticsEvent } from '@diginestai/core';

function AnalyticsLayer() {
  useAnalytics((event: AnalyticsEvent) => {
    switch (event.type) {
      case 'space-viewed':
        analytics.track('Space Viewed', { unitId: event.unitId });
        break;
      case 'space-selected':
        analytics.track('Space Selected', { unitId: event.unitId });
        break;
      case 'route-computed':
        analytics.track('Route Computed', {
          from: event.originId,
          to: event.destinationId,
          floors: event.floorCount,
        });
        break;
      case 'share-triggered':
        analytics.track('Map Shared', { url: event.url });
        break;
    }
  });

  return null;
}

Event types

event.type	Payload type	Fired when
'space-viewed'	SpaceViewedEvent	Space detail visible for ≥ 500 ms
'space-selected'	SpaceSelectedEvent	User selects a space
'route-computed'	RouteComputedEvent	Wayfinding route returned
'floor-changed'	FloorChangedEvent	Active floor changes
'search-performed'	SearchPerformedEvent	Search query executed
'share-triggered'	ShareTriggeredEvent	ShareControl clicked