ПроКартыПроКарты
ГлавнаяВойти

SDK-карты

Что нужно сделать клиенту

SDK-карты нужны для приложения клиента. Клиент не получает от ProMaps готовый файл всей карты. Он подключает SDK, получает отдельный ключ и запускает карту через сервер ProMaps.

Коротко в 5 шагах

  1. Клиент получает у ProMaps отдельный SDK-ключ.
  2. Разработчик клиента подключает SDK в своё приложение.
  3. В настройки SDK он вставляет ключ и адрес сервера ProMaps.
  4. Он передаёт стабильный идентификатор пользователя или установки приложения.
  5. После этого карта начинает открываться через runtime ProMaps.

Что делает ProMaps

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

Что делает клиент-разработчик

  • подключает SDK в своё приложение;
  • вставляет SDK-ключ;
  • передаёт в SDK стабильный userId или installationId;
  • запускает карту на своей стороне.

Путь пользователя по SDK-картам

SDK-карты для приложений работают через runtime ProMaps. Пользователь не скачивает набор тайлов или отдельный файл карты: приложение обращается к защищённым endpoint-ам ProMaps и получает только те ресурсы, которые нужны для текущего экрана.

  1. Команда подключает SDK ProMaps в мобильное или embedded-приложение.
  2. Приложению выдаётся отдельный SDK-ключ.
  3. SDK запускает карту через /api/mobile-map/styles/*, /api/mobile-map/vector-tiles/*, /api/mobile-map/fonts/* и /api/mobile-map/sprites/*.
  4. Во время работы SDK передаёт стабильный идентификатор пользователя или установки, чтобы runtime корректно управлял доступом и считал уникальных пользователей за месяц.
  5. Если связь нестабильна, приложение продолжает использовать уже полученные ресурсы и повторяет запросы по мере необходимости, без отдельного bulk-download сценария.

Что важно для продукта

  • отдельные .pmtiles или raw tile-файлы клиенту не выдаются;
  • интеграция идёт через один SDK runtime, а не через ручную работу с архивами;
  • доступ контролируется на стороне ProMaps, поэтому сценарий ближе к обычному Maps API, чем к файловой поставке.

Что такое userId и installationId

userId и installationId нужны для того, чтобы ProMaps понимал: карту открыл тот же самый пользователь или та же самая установка приложения, а не кто-то новый. Это нужно для честного учёта лимита 1 000 уникальных пользователей в месяц на один SDK-ключ.

Если у клиента есть авторизация

Лучший вариант: клиент передаёт свой внутренний userId. Это может быть номер или строка пользователя в его собственной системе. Главное, чтобы для одного и того же пользователя этот идентификатор не менялся каждый день.

Если у клиента нет авторизации

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

Обычно приложение клиента создаёт его автоматически один раз и потом хранит у себя. ProMaps не собирает клиенту отдельный инсталлятор для этого.

Какой вариант правильный

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

Как работает SDK runtime

Технически это тот же серверный runtime карт, только через мобильный namespace /api/mobile-map/*. SDK запрашивает style JSON, шрифты, спрайты и vector tiles по мере открытия карты и движения по ней.

  • SDK не скачивает заранее весь город, регион или набор тайлов одним архивом;
  • приложение получает только те tiles и ресурсы, которые реально нужны в текущем viewport;
  • уже загруженные области могут продолжать показываться при потере связи, но новый cold start без сети и новые области заранее не гарантируются;
  • серверу в первую очередь нужен dataset на диске, а не большой дополнительный объём RAM под каждого клиента;
  • по характеру нагрузки это близко к обычному Maps API: style + fonts + sprites + vector tiles, только с отдельной моделью авторизации и контроля доступа для SDK.

Что это значит для инфраструктуры

Хранилище карт нужно в том же контуре, что и для обычного Maps API. Основной объём занимает dataset на диске, а не память под «раздачу файлов пользователям». Поэтому offline SDK runtime масштабируется примерно как обычная картографическая выдача, а не как файловый CDN с ручными пакетами.

Практический пользовательский сценарий

  1. Пользователь открывает экран карты в приложении.
  2. SDK получает style и служебные ресурсы.
  3. SDK запрашивает нужные vector tiles для текущей области карты.
  4. При смене масштаба, перемещении или повторном открытии экрана приложение берёт уже загруженные ресурсы из обычного HTTP/browser/native cache и при необходимости дозапрашивает недостающие.
  5. Если нужная область раньше не открывалась и сети нет, карта не сможет догрузить новые данные.