Skip to main content

Get started with positioning

|

The Positioning module enables your web application to obtain and utilize location data, serving as the foundation for features like navigation, tracking, and location-based services. This data can be sourced either from the browser's Geolocation API or from a custom data source, offering flexibility to suit diverse application needs.

Using the Positioning module, you can:

  • Leverage browser geolocation: Obtain accurate, real-time location updates directly from the browser's built-in Geolocation API.
  • Integrate custom location data: Configure the module to use location data provided by external sources, such as mock services or specialized hardware.

In the following sections, you will learn how to request the necessary location permissions in the browser, set up live data sources, and manage location updates effectively. This comprehensive guide will help you integrate robust and flexible positioning capabilities into your web application.

Requesting Location Permissions​

Browser Geolocation API​

Modern web browsers require explicit user consent to access location data. The SDK provides a convenient method to request location permissions.

import { PositionService } from '@magiclane/maps-sdk';

async function requestLocationPermission(): Promise<boolean> {
  const permission = await PositionService.requestLocationPermission();
  if (!permission) {
    console.log('Location permission denied.');
    return false;
  }
  console.log('Location permission granted');
  return true;
}

HTTPS Requirement​

important

The Geolocation API requires a secure context (HTTPS) in production. It will only work on http://localhost during development. Ensure your production application is served over HTTPS.

Checking Permission Status​

The permission status can be checked using the browser's Permissions API if needed:

async function checkLocationPermission(): Promise<PermissionState> {
  try {
    const result = await navigator.permissions.query({ name: 'geolocation' });
    console.log('Location permission status:', result.state);
    // result.state can be 'granted', 'denied', or 'prompt'
    return result.state;
  } catch (error) {
    console.error('Error checking permission:', error);
    return 'prompt';
  }
}

Enabling Live Location Tracking​

Once permission is granted, you can enable live location tracking:

import { PositionService } from '@magiclane/maps-sdk';

async function enableLiveTracking() {
  // Request permission first
  const hasPermission = await PositionService.requestLocationPermission();
  if (!hasPermission) {
    console.error('Location permission not granted');
    return;
  }
  
  // Set live data source
  PositionService.instance.setLiveDataSource();
  
  console.log('Live tracking enabled');
}

Listening to Position Updates​

You can subscribe to position updates to track user location changes:

import { PositionService, GemPosition, GemPositionListener } from '@magiclane/maps-sdk';

function subscribeToPositionUpdates(): GemPositionListener {
  const listener = PositionService.instance.addPositionListener((position: GemPosition) => {
    console.log('Position updated:', {
      latitude: position.coordinates.latitude,
      longitude: position.coordinates.longitude,
      altitude: position.altitude,
      speed: position.speed,
      accuracy: position.accuracyH
    });
    
    // Update your UI or perform other actions with the new position
  });
  
  return listener;
}

Removing Position Listeners​

When you no longer need position updates, you should remove the listener to prevent memory leaks:

import { PositionService, GemPositionListener } from '@magiclane/maps-sdk';

function cleanupListener(listener: GemPositionListener) {
  PositionService.instance.removeListener(listener);
}

User Interface Considerations​

When requesting location permissions, it's good practice to:

  1. Explain why you need location access before requesting permission
  2. Provide a fallback if the user denies permission
  3. Handle errors gracefully and provide clear feedback to users
import { PositionService } from '@magiclane/maps-sdk';

function showLocationPermissionDialog() {
  const dialog = document.createElement('div');
  dialog.innerHTML = `
    <div class="permission-dialog">
      <h2>Location Access Required</h2>
      <p>This app needs access to your location to provide navigation and map features.</p>
      <button id="grant-permission">Allow</button>
      <button id="deny-permission">Deny</button>
    </div>
  `;
  
  document.body.appendChild(dialog);
  
  document.getElementById('grant-permission')?.addEventListener('click', async () => {
    const granted = await PositionService.requestLocationPermission();
    if (granted) {
      PositionService.instance.setLiveDataSource();
    }
    dialog.remove();
  });
  
  document.getElementById('deny-permission')?.addEventListener('click', () => {
    console.log('User denied location access');
    dialog.remove();
  });
}

Next Steps​

Now that you have positioning set up, you can:

  • Display the user's location on the map
  • Implement navigation features
  • Track user movement
  • Create location-based services
Last updated on