Миграция между версиями HERE API

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

Ключевая особенность современных версий заключается в разделении логики:

  • базовая платформа (Platform)
  • визуализация карты (Map / MapView)
  • сервисные модули (routing, geocoding, search)
  • UI-компоненты (ui components)

В старых реализациях многие функции были доступны через глобальные объекты, тогда как в новых версиях применяется модульная загрузка через CDN или пакетные сборки.

Изменение способа подключения библиотек

Старый подход (legacy CDN)

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

<script src="https://js.api.here.com/v3/3.0/mapsjs-core.js"></script>
<script src="https://js.api.here.com/v3/3.0/mapsjs-service.js"></script>
<script src="https://js.api.here.com/v3/3.0/mapsjs-ui.js"></script>
<script src="https://js.api.here.com/v3/3.0/mapsjs-mapevents.js"></script>

Особенности:

  • глобальное пространство H
  • порядок подключения критичен
  • отсутствие гибкого tree-shaking
  • ограниченная поддержка современных сборщиков

Современный подход (v3.1+ и modular)

В новых версиях применяется более гибкая загрузка:

<script src="https://js.api.here.com/v3/3.1/mapsjs-core.js"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-service.js"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-ui.js"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-mapevents.js"></script>

Но ключевое отличие заключается не только в версии, а в возможности использования модульной архитектуры через bundler (Webpack, Vite):

import H from '@here/maps-api-for-javascript';

В таком режиме:

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

Переход от Platform v2 к Platform v3

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

Было

const platform = new H.service.Platform({
  app_id: 'APP_ID',
  app_code: 'APP_CODE'
});

Стало

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

Ключевые изменения:

  • отказ от app_id и app_code
  • переход на единый ключ apikey
  • упрощение модели аутентификации
  • усиление контроля доступа через HERE Developer Portal

Изменения в создании карты

Legacy инициализация

const defaultLayers = platform.createDefaultLayers();

const map = new H.Map(
  document.getElementById('mapContainer'),
  defaultLayers.normal.map,
  {
    center: { lat: 52.5, lng: 13.4 },
    zoom: 10
  }
);

Актуальная модель

Основной принцип остался, но изменились слои и рекомендации по рендерингу:

const layers = platform.createDefaultLayers();

const map = new H.Map(
  document.getElementById('map'),
  layers.vector.normal.map,
  {
    center: { lat: 52.5, lng: 13.4 },
    zoom: 10,
    pixelRatio: window.devicePixelRatio
  }
);

Важные изменения:

  • переход на vector tiles как основной стандарт
  • обязательный учёт pixelRatio для HiDPI
  • оптимизация рендеринга через WebGL в новых версиях

Изменение модели событий

В старых версиях обработка событий выполнялась через map.addEventListener, но в новых версиях предпочтение отдаётся унифицированной системе событий H.mapevents.

Было

map.addEventListener('tap', function (evt) {
  console.log(evt.currentPointer);
});

Стало

const beh * avior = new H.mapevents.Behavior(new H.mapevents.MapEvents(map));

map.addEventListener('tap', (evt) => {
  console.log(evt.type, evt.currentPointer);
});

Дополнительный слой абстракции

Появление Behavior изменило логику взаимодействия:

  • масштабирование
  • панорамирование
  • обработка жестов

Теперь управляются централизованно через MapEvents.

Изменения UI-компонентов

Старый UI

const ui = H.ui.UI.createDefault(map, defaultLayers);

Особенности старого UI:

  • фиксированный набор контролов
  • ограниченная кастомизация
  • зависимость от legacy CSS

Обновлённый UI слой

В новых версиях UI стал более модульным:

const ui = H.ui.UI.createDefault(map, layers);

Но ключевые изменения касаются не синтаксиса, а внутренней структуры:

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

Геокодирование и сервисные модули

Ранее

const geocoder = platform.getGeocodingService();

Сейчас

const service = platform.getSearchService();

Или:

const geocodingService = platform.getGeocodingService();

Основные изменения:

  • унификация Search API и Geocoding API
  • переход к REST-подобной архитектуре
  • изменение структуры ответов (JSON стал более вложенным)

Изменения в маршрутизации

Старый Routing API

const router = platform.getRoutingService();

Новый подход

const router = platform.getRoutingService(null, 8);

или использование нового Routing V8 API через REST:

  • явное указание версии сервиса
  • поддержка альтернативных профилей маршрутов
  • расширенные параметры транспорта

Пример запроса маршрута

const routingParameters = {
  routingMode: 'fast',
  transportMode: 'car',
  origin: '52.5,13.4',
  destination: '52.52,13.45'
};

router.calculateRoute(routingParameters, result => {
  console.log(result);
}, error => {
  console.error(error);
});

Изменения структуры ответов API

При миграции часто возникает необходимость адаптации под новую структуру JSON.

Пример различий:

Ранее

{
  "Response": {
    "View": [{
      "Result": []
    }]
  }
}

Сейчас

{
  "items": [
    {
      "position": {
        "lat": 52.5,
        "lng": 13.4
      }
    }
  ]
}

Практическое влияние:

  • требуется переписать парсинг данных
  • убирается зависимость от вложенных legacy-структур
  • упрощается работа с результатами поиска

Изменение модели слоёв (Layers)

Legacy модель

const layers = platform.createDefaultLayers();
map.setBaseLayer(layers.normal.map);

Новая модель

const layers = platform.createDefaultLayers({
  lg: 'eng'
});

И использование vector слоёв:

layers.vector.normal.map

Важные изменения:

  • разделение raster/vector
  • улучшенная кастомизация стилей
  • поддержка динамических тем

Изменения производительности и рендеринга

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

  • WebGL рендеринг вместо Canvas2D
  • уменьшение количества DOM-операций
  • оптимизацию тайловой загрузки

Практический эффект:

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

Типичные проблемы при миграции

1. Несовместимость ключей доступа

Использование старых app_id/app_code приводит к отказу авторизации.

Решение: переход на apikey.

2. Поломка событий

Если не инициализирован MapEvents, события жестов могут не работать.

Решение:

const mapEvents = new H.mapevents.MapEvents(map);
const beh * avior = new H.mapevents.Behavior(mapEvents);

3. Изменение структуры ответа сервисов

Парсинг старых JSON-структур приводит к undefined.

Решение: адаптация под новый REST формат.

4. Проблемы с UI

Старые кастомные CSS могут конфликтовать с новым UI-слоем.

Решение: отказ от legacy тем и переход на UI Theme API.

Стратегия миграции между версиями

Последовательная миграция строится по слоям:

  1. Обновление ключей доступа
  2. Замена подключения SDK
  3. Переподключение платформы
  4. Адаптация картографических слоёв
  5. Переработка сервисных вызовов
  6. Обновление UI и событий
  7. Переписывание парсинга ответов

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

Оглавление