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

Модель геолокации и источники ошибок

Геолокация в веб-картах опирается на браузерный API navigator.geolocation, который возвращает координаты устройства при наличии разрешения пользователя и технической возможности определения местоположения. В контексте картографических библиотек этот процесс оборачивается дополнительным слоем абстракции, где ошибки могут возникать на нескольких уровнях:

  • уровень браузера (Geolocation API)
  • уровень сетевого/аппаратного определения координат
  • уровень обработки в библиотеке карт
  • уровень пользовательского кода

Основные причины сбоев:

  • отказ в доступе к геоданным
  • невозможность определить координаты
  • превышение времени ожидания
  • отсутствие поддержки API в окружении
  • блокировка HTTPS или политики безопасности

Типы ошибок Geolocation API

Браузерный API стандартизирует ошибки через объект PositionError, который содержит код и сообщение.

Коды ошибок

  • 1 — PERMISSION_DENIED Геолокация запрещена пользователем или политиками браузера

  • 2 — POSITION_UNAVAILABLE Координаты недоступны (например, нет сигнала GPS или сетевого определения)

  • 3 — TIMEOUT Превышено время ожидания запроса

Эти коды напрямую используются при обработке событий в картографических библиотеках.

Геолокация в Leaflet и механизм событий

В Leaflet геолокация реализуется через метод:

map.locate({ setView: true, maxZoom: 16 });

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

  • locationfound
  • locationerror

Событие успешного определения

map.on('locationfound', function (e) {
    const radius = e.accuracy;

    L.marker(e.latlng).addTo(map);
    L.circle(e.latlng, radius).addTo(map);
});

Событие ошибки

map.on('locationerror', function (e) {
    console.log(e.message);
});

Объект ошибки e содержит:

  • code — числовой идентификатор ошибки
  • message — текстовое описание
  • дополнительные внутренние поля Leaflet

Интерпретация ошибок в Leaflet

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

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

map.on('locationerror', function (e) {
    if (e.code === 1) {
        console.log('Доступ к геолокации запрещён');
    }
});

Сценарии возникновения:

  • пользователь отклонил запрос
  • политика браузера блокирует геолокацию на HTTP
  • настройки приватности запрещают доступ

Недоступность координат

map.on('locationerror', function (e) {
    if (e.code === 2) {
        console.log('Координаты недоступны');
    }
});

Причины:

  • отсутствие GPS сигнала
  • отключённые службы определения местоположения
  • проблемы сети при IP-геолокации

Таймаут определения

map.on('locationerror', function (e) {
    if (e.code === 3) {
        console.log('Превышено время ожидания');
    }
});

Факторы:

  • медленный отклик GPS
  • ограничение timeout в параметрах map.locate
  • высокая нагрузка на устройство

Параметры, влияющие на вероятность ошибок

Метод map.locate принимает конфигурацию, которая напрямую влияет на поведение геолокации:

map.locate({
    enableHighAccuracy: true,
    timeout: 10000,
    maximumAge: 0,
    setView: true
});

enableHighAccuracy

  • true — использование GPS и высокоточных источников
  • увеличивает время получения координат
  • повышает вероятность таймаута

timeout

Определяет максимальное время ожидания результата. Слишком малое значение приводит к частым ошибкам TIMEOUT.

maximumAge

Определяет допустимость использования кешированных координат:

  • 0 — всегда свежие данные
  • большие значения уменьшают нагрузку, но могут давать устаревшие координаты

Централизованная обработка ошибок

При построении картографических интерфейсов используется единая точка обработки ошибок:

function handleLocationError(e) {
    switch (e.code) {
        case 1:
            console.log('Нет разрешения');
            break;
        case 2:
            console.log('Нет данных о местоположении');
            break;
        case 3:
            console.log('Таймаут запроса');
            break;
        default:
            console.log('Неизвестная ошибка');
    }
}

map.on('locationerror', handleLocationError);

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

Повторные попытки определения координат

Ошибки геолокации часто носят временный характер, поэтому используется механизм повторных запросов:

function locateWithRetry(attempt = 0) {
    if (attempt > 2) return;

    map.locate({
        setView: true,
        timeout: 8000
    });
}

map.on('locationerror', function () {
    locateWithRetry(1);
});

При этом важно учитывать:

  • повторный запрос может снова вызвать отказ пользователя
  • частые вызовы геолокации ограничиваются браузером
  • батарея устройства и ресурсы GPS ограничены

Обработка отсутствия поддержки геолокации

Некоторые окружения не предоставляют navigator.geolocation. В этом случае Leaflet не инициирует успешное определение координат.

if (!navigator.geolocation) {
    console.log('Геолокация не поддерживается');
}

Дополнительно может применяться fallback:

  • статическая координата центра карты
  • IP-геолокация через серверный API
  • выбор региона вручную

Сочетание ошибок Leaflet и браузера

Leaflet передаёт ошибки без изменения структуры, но добавляет контекст карты. Это приводит к необходимости учитывать:

  • расхождение между PositionError и Leaflet event
  • отсутствие дополнительных автоматических преобразований
  • необходимость ручной нормализации ошибок

Пример унифицированного объекта:

function normalizeError(e) {
    return {
        code: e.code,
        message: e.message,
        source: 'geolocation'
    };
}

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

При разработке картографических систем геолокация требует детального логирования:

  • код ошибки
  • время запроса
  • параметры locate
  • состояние сети устройства
map.on('locationerror', function (e) {
    console.error({
        code: e.code,
        message: e.message,
        timestamp: Date.now()
    });
});

Такая информация используется для анализа причин нестабильного определения координат.

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

Мобильные устройства добавляют дополнительные источники нестабильности:

  • переключение между Wi-Fi и мобильной сетью
  • энергосберегающие ограничения GPS
  • фоновая приостановка скриптов

Это увеличивает вероятность:

  • TIMEOUT
  • POSITION_UNAVAILABLE

Связь ошибок с безопасным контекстом

Геолокация доступна только в защищённом контексте HTTPS. При отсутствии HTTPS:

  • запросы блокируются
  • событие locationerror может не инициироваться
  • браузер подавляет доступ к API

Архитектурные подходы к обработке ошибок

В сложных приложениях используется разделение уровней:

  • слой инициализации карты
  • слой геолокации
  • слой обработки ошибок
  • слой UI-индикации состояния

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

Особенности отладки

При диагностике ошибок геолокации важны следующие параметры:

  • точность (accuracy)
  • задержка получения координат
  • повторяемость ошибки
  • различие поведения между браузерами

Leaflet предоставляет только событийную модель, поэтому основная аналитика выполняется через внешние механизмы и консольные инструменты разработчика.

Оглавление