Обработка ошибок геолокации

Геолокация в браузере опирается на Web Geolocation API, который возвращает координаты через асинхронный запрос к системным сервисам устройства (GPS, Wi-Fi, IP-геолокация). При интеграции с картографическими решениями HERE Technologies такие данные используются как начальная точка для отображения карты, построения маршрутов и поиска объектов.

Ошибки на этом уровне возникают не внутри карты, а на этапе получения координат. Основные категории:

  • отказ пользователя в предоставлении доступа;
  • отсутствие доступных источников позиционирования;
  • истечение времени ожидания;
  • внутренняя ошибка браузера или устройства;
  • снижение точности до уровня, непригодного для отображения.

Каждая ошибка сопровождается кодом и сообщением, которые необходимо интерпретировать до передачи данных в HERE Maps API.

Модель ошибок Geolocation API

В браузерной реализации ошибки передаются через объект PositionError, содержащий три ключевых параметра:

  • code — числовой идентификатор причины;
  • message — текстовое описание;
  • дополнительные метаданные зависят от реализации браузера.

Основные коды:

  • 1 (PERMISSION_DENIED) — доступ к геолокации запрещён;
  • 2 (POSITION_UNAVAILABLE) — координаты недоступны;
  • 3 (TIMEOUT) — превышено время ожидания.

Обработка этих кодов формирует базовый слой устойчивости геолокационного функционала.

Базовая обработка ошибок navigator.geolocation

Стандартный вызов получения позиции включает два callback-а: успех и ошибка.

navigator.geolocation.getCurrentPosition(
  (position) => {
    const lat = position.coords.latitude;
    const lng = position.coords.longitude;
    console.log(lat, lng);
  },
  (error) => {
    console.error("Geolocation error:", error.code, error.message);
  },
  {
    enableHighAccuracy: true,
    timeout: 8000,
    maximumAge: 0
  }
);

В этом фрагменте обработчик ошибок выступает единственной точкой контроля, через которую данные могут быть переданы в слой отображения карты HERE Maps API.

Причины отказов и их интерпретация

Отказ в доступе

Наиболее частая ситуация — блокировка геолокации пользователем или политикой браузера. В этом случае координаты недоступны независимо от настроек точности.

Типичная стратегия обработки:

  • переход на дефолтные координаты (например, центр города или страны);
  • отображение интерфейсного уведомления внутри карты;
  • отключение функций автопозиционирования.

Недоступность позиции

Состояние POSITION_UNAVAILABLE возникает при отсутствии GPS-сигнала или сетевых данных. Особенно характерно для:

  • закрытых помещений;
  • виртуальных сред;
  • устройств без модулей геолокации.

В таких случаях данные могут быть частично восстановлены через IP-геолокацию, однако точность резко снижается.

Таймаут

Ошибка TIMEOUT указывает на то, что устройство не успело получить стабильные координаты. Это критично при использовании enableHighAccuracy: true, так как GPS-определение может занимать несколько секунд.

Рекомендуемые подходы:

  • увеличение таймаута;
  • повторный запрос с пониженной точностью;
  • переключение на кэшированные координаты (maximumAge).

Интеграция ошибок с HERE Maps JavaScript API

В архитектуре приложений на базе HERE Maps JS API геолокация часто используется для инициализации карты:

const platform = new H.service.Platform({
  apikey: "API_KEY"
});

const defaultLayers = platform.createDefaultLayers();
const map = new H.Map(
  document.getElementById("map"),
  defaultLayers.vector.normal.map,
  {
    zoom: 10,
    center: { lat: 0, lng: 0 }
  }
);

После получения координат карта центрируется динамически:

function setMapCenter(lat, lng) {
  map.setCenter({ lat, lng });
}

При ошибке геолокации применяется fallback-логика:

function handleGeoError(error) {
  switch (error.code) {
    case error.PERMISSION_DENIED:
      setMapCenter(51.5074, -0.1278);
      break;

    case error.POSITION_UNAVAILABLE:
      setMapCenter(48.8566, 2.3522);
      break;

    case error.TIMEOUT:
      retryGeolocation();
      break;

    default:
      setMapCenter(0, 0);
  }
}

Такой подход позволяет сохранить функциональность карты даже при деградации источника данных.

Стратегии устойчивой геолокации

Многоуровневая деградация точности

Система обработки ошибок строится по уровням:

  1. GPS-координаты устройства;
  2. Wi-Fi и сетевые данные;
  3. IP-геолокация;
  4. статический fallback.

Каждый следующий уровень имеет меньшую точность, но большую доступность.

Повторные попытки запроса

При временных сбоях применяется повторный вызов:

let attempts = 0;

function retryGeolocation() {
  if (attempts > 3) return;

  attempts++;

  navigator.geolocation.getCurrentPosition(
    successCallback,
    handleGeoError,
    { timeout: 10000 }
  );
}

Ограничение числа попыток предотвращает блокировку интерфейса.

Использование кэшированных данных

Параметр maximumAge позволяет использовать ранее полученные координаты:

{
  maximumAge: 60000
}

Это снижает зависимость от нестабильного сигнала и уменьшает количество ошибок TIMEOUT.

Логирование и диагностика

В производственных системах ошибки геолокации фиксируются для анализа качества данных. Логирование включает:

  • код ошибки;
  • время возникновения;
  • состояние сети;
  • контекст запроса карты.

Пример структуры логов:

{
  "errorCode": 1,
  "message": "Permission denied",
  "timestamp": 1710000000,
  "mapState": "initialization"
}

Такая информация позволяет выявлять системные проблемы, связанные не только с браузером, но и с поведением пользователей.

Согласование геолокации с состоянием карты

Ошибки геолокации напрямую влияют на начальное состояние карты HERE Maps API. При отсутствии координат требуется определить стратегию:

  • фиксированный центр карты;
  • отключение автоприближения;
  • загрузка пользовательских слоёв без привязки к позиции.

Важно разделять состояние карты и состояние геолокации, чтобы ошибка одного компонента не блокировала другой.

Асинхронные сценарии и гонки состояния

Геолокация является асинхронным процессом, тогда как инициализация карты может завершаться быстрее. Это приводит к состояниям гонки:

  • карта загружена, координаты ещё не получены;
  • координаты получены, но карта не инициализирована;
  • повторный запрос перезаписывает центрирование.

Для синхронизации используется промежуточное состояние:

let mapReady = false;
let pendingCoords = null;

function onMapReady() {
  mapReady = true;

  if (pendingCoords) {
    setMapCenter(pendingCoords.lat, pendingCoords.lng);
  }
}

Обработка ошибок в SPA-архитектуре

В одностраничных приложениях геолокация может вызываться многократно при переходах между маршрутами. Это требует:

  • отмены устаревших запросов;
  • защиты от повторного центрирования карты;
  • разделения глобального и локального состояния координат.

Особое значение имеет предотвращение утечки старых ошибок в новые состояния интерфейса.

Безопасность и ограничения

Браузеры накладывают строгие ограничения на доступ к геолокации:

  • обязательное HTTPS-соединение;
  • явное разрешение пользователя;
  • невозможность фонового трекинга без взаимодействия.

Ошибки, возникающие на уровне политики безопасности, не могут быть обойдены программно и должны обрабатываться как окончательные состояния.

Поведение в мобильных средах

На мобильных устройствах поведение геолокации отличается:

  • более высокая точность GPS;
  • частые переходы между сетями;
  • энергосберегающие ограничения ОС.

Это увеличивает вероятность временных ошибок POSITION_UNAVAILABLE, особенно при переключении между приложениями.

Ошибки геолокации формируют критический слой устойчивости приложений, использующих картографические сервисы HERE Technologies, и требуют многоуровневой стратегии обработки, охватывающей как браузерный API, так и логику инициализации карты, управление состоянием и деградацию точности координат.

Оглавление