@mappedin/blue-dot

An extension for Mappedin JS to track the device position on the map.

Usage

Installation

With NPM:

npm install @mappedin/blue-dot

With Yarn:

yarn add @mappedin/blue-dot

Getting Started

import { show3dMap } from '@mappedin/mappedin-js';
import { BlueDot } from '@mappedin/blue-dot';

const mapView = await show3dMap(...);

// Create a new BlueDot
const blueDot = new BlueDot(mapView);
blueDot.enable();

// Listening to device position updates from the browser
blueDot.watchDevicePosition();

// Send custom position updates from a different source
blueDot.update({
    // Latitude of the update
	latitude,
    // Longitude of the update
	longitude,
    // Optional accuracy in meters
	accuracy,
    // Optional heading in degrees from north
	heading,
    // Optional floor or floor ID
	floorOrFloorId,
})

// Attach the camera to the BlueDot
blueDot.follow('position-only');

Options

export type BlueDotOptions = {
	/**
	 * The radius of the BlueDot in pixels. The BlueDot will maintain this size clamped to a minimum of 0.35 metres.
	 * @default 10
	 */
	radius?: number;
	/**
	 * The color of the BlueDot core element.
	 * @default #2266ff
	 */
	color?: string;
	/**
	 * The color of the BlueDot when it has timed out and gone inactive.
	 * @default #808080
	 */
	inactiveColor?: string;
	/**
	 * Options for the accuracy ring around the BlueDot.
	 */
	accuracyRing?: {
		/**
		 * The color of the accuracy ring.
		 * @default #2266ff
		 */
		color?: string;
		/**
		 * The opacity of the accuracy ring.
		 * @default 0.3
		 */
		opacity?: number;
	};
	/**
	 * Options for the heading directional indicator.
	 */
	heading?: {
		/**
		 * The color of the heading cone.
		 * @default #2266ff
		 */
		color?: string;
		/**
		 * The opacity of the heading cone.
		 * @default 0.7
		 */
		opacity?: number;
	};
	/**
	 * The duration of the timeout in milliseconds.
	 * If the BlueDot does not receive a position update within this time, it will grey out until a position is received.
	 * @default 30000
	 */
	timeout?: number;
	/**
	 * Whether to watch the device's position.
	 * @default true
	 */
	watchDevicePosition?: boolean;
	/**
	 * Whether to log debug messages.
	 * @default false
	 */
	debug?: boolean;
};

React Native

import React, { useEffect, useCallback } from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { MapView, useMapData } from '@mappedin/react-native-sdk';
import { useBlueDot, useBlueDotEvent } from '@mappedin/blue-dot/rn';

function MyComponent() {
	const { mapData } = useMapData({
		key: 'your-api-key',
		secret: 'your-api-secret',
		mapId: 'your-map-id',
	});

	return (
		<MapView mapData={mapData}>
			<BlueDotDisplay />
		</MapView>
	);
}

function BlueDotDisplay() {
	// All methods are async and return Promises
	const {
		isReady,
		isEnabled,
		state,
		position,
		floor,
		isFollowing,
		accuracy,
		heading,
		enable,
		disable,
		update,
		follow,
	} = useBlueDot();

	// Listen for position updates
	useBlueDotEvent(
		'position-update',
		useCallback(event => {
			console.log('Position updated:', event.coordinate, event.floor);
		}, []),
	);

	// Listen for state changes
	useBlueDotEvent(
		'state-change',
		useCallback(event => {
			console.log('State changed:', event.state);
		}, []),
	);

	// Listen for follow mode changes
	useBlueDotEvent(
		'follow-change',
		useCallback(event => {
			console.log('Follow mode:', event.following);
		}, []),
	);

	useEffect(() => {
		if (isReady && !isEnabled) {
			// All methods are async - use await or .then()
			enable({
				radius: 15,
				color: '#ff0000',
				watchDevicePosition: false,
			});
		}
	}, [isReady, isEnabled, enable]);

	const handleUpdatePosition = useCallback(async () => {
		try {
			// Update position manually
			await update({
				latitude: 43.6532,
				longitude: -79.3832,
				accuracy: 5,
				heading: 90,
				floorOrFloorId: floor,
			});

			// Enable follow mode
			await follow('position-and-heading', {
				zoomLevel: 19,
			});
		} catch (error) {
			console.error('Failed to update position:', error);
		}
	}, [update, follow, floor]);

	return (
		<View>
			<Text>Is Ready: {isReady ? 'Yes' : 'No'}</Text>
			<Text>Is Enabled: {isEnabled ? 'Yes' : 'No'}</Text>
			<Text>State: {state}</Text>
			<Text>Following: {following ? 'Yes' : 'No'}</Text>
			{position && (
				<Text>
					Position: {position.latitude.toFixed(4)}, {position.longitude.toFixed(4)}
				</Text>
			)}
			{accuracy && <Text>Accuracy: {accuracy.toFixed(1)}m</Text>}
			{heading && <Text>Heading: {heading.toFixed(0)}°</Text>}
			<TouchableOpacity onPress={handleUpdatePosition}>
				<Text>Update Position & Follow</Text>
			</TouchableOpacity>
		</View>
	);
}

Key Differences from Vanilla JS:

• All methods are async: enable(), disable(), update(), and follow() return Promises
• Rich state: Hook returns isReady, state, position, floor, following, accuracy, heading for real-time updates
• Separate event hook: Use useBlueDotEvent for listening to position-update, state-change, and follow-change events