Работа с токенами Mapbox

Kepler.gl использует инфраструктуру Mapbox для рендеринга карт, тайлов и базовых слоёв. В основе взаимодействия лежит access token — строка, которая идентифицирует приложение и определяет уровень доступа к API Mapbox.

Структура Mapbox access token

Access token представляет собой строку вида:

pk.eyJ1IjoidXNlciIsImEiOiJja3...

Ключевые характеристики:

  • начинается с префикса pk (public token) или sk (secret token)
  • кодирует идентификатор пользователя и приложения
  • привязан к настройкам аккаунта Mapbox
  • управляет доступом к стилям, тайлам и API

Public token используется в клиентских приложениях (в том числе Kepler.gl), secret token — только на серверной стороне.

Роль токена в архитектуре Kepler.gl

Kepler.gl (kepler.gl) построен на deck.gl и Mapbox GL JS. Access token выполняет несколько функций:

  • авторизация запросов к Mapbox Tile API
  • загрузка базовых карт (styles)
  • доступ к кастомным стилям пользователя
  • получение географических тайлов (vector/raster tiles)
  • работа с геокодингом (при подключении дополнительных сервисов Mapbox)

Без корректного токена карта не загружается, остаются только слои данных без подложки.

Добавление токена в Kepler.gl

Через конфигурацию приложения

В большинстве React-приложений Kepler.gl токен передаётся глобально:

import KeplerGl from 'kepler.gl';

const MAPBOX_TOKEN = 'pk.your_public_token_here';

const App = () => (
  <KeplerGl
    id="map"
    width={width}
    height={height}
    mapboxApiAccessToken={MAPBOX_TOKEN}
  />
);

Через Redux state

Kepler.gl часто используется вместе с Redux:

const initialState = {
  keplerGl: {
    map: {
      mapboxApiAccessToken: 'pk.your_public_token_here'
    }
  }
};

Переменные окружения и безопасное хранение

В production-сборках токен обычно хранится через переменные окружения:

REACT_APP_MAPBOX_TOKEN=pk.your_public_token_here

Использование в коде:

const token = process.env.REACT_APP_MAPBOX_TOKEN;

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

  • токен доступен в клиентском JS, поэтому не считается секретным
  • нельзя хранить sk.* токены в frontend-коде
  • рекомендуется ограничивать токен через dashboard Mapbox

Ограничения и безопасность токенов

Mapbox token может быть ограничен следующими параметрами:

Ограничение по доменам

Позволяет использовать токен только с определённых сайтов:

  • localhost
  • example.com
  • staging-домены

Ограничение по API

Можно включать или отключать доступ к:

  • Styles API
  • Tiles API
  • Geocoding API
  • Directions API

Ограничение по использованию

  • лимит запросов в месяц
  • лимит тайлов
  • контроль биллинга

Такая модель предотвращает злоупотребления даже при утечке public token.

Использование кастомных стилей Mapbox

Kepler.gl поддерживает кастомные Mapbox Styles:

const mapConfig = {
  mapStyle: {
    styleType: 'dark',
    topLayerGroups: {},
    visibleLayerGroups: {}
  }
};

или через URL:

const MAP_STYLE = 'mapbox://styles/user/customstyle';

Токен обязателен для загрузки кастомного стиля, так как стиль хранится в инфраструктуре Mapbox.

Ошибки, связанные с токеном

Invalid token

Причины:

  • опечатка в строке
  • использование sk вместо pk
  • удалённый токен в dashboard

Unauthorized

  • домен не добавлен в whitelist
  • отключён доступ к API

Map not loading

  • отсутствует mapboxApiAccessToken
  • превышен лимит запросов
  • блокировка корпоративным firewall

Динамическая смена токена

Kepler.gl позволяет менять токен в runtime:

dispatch(
  updateMap({ mapboxApiAccessToken: newToken })
);

Сценарии использования:

  • переключение между staging/prod аккаунтами
  • работа с несколькими Mapbox проектами
  • миграция пользователей

Использование токенов в server-side рендеринге

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

  • токен не должен быть удалён из initial state
  • карта должна инициализироваться только на клиенте
  • pre-render требует mock состояния карты без API вызовов

Интеграция с deck.gl и Mapbox GL JS

Kepler.gl использует Mapbox GL JS как рендер-движок:

  • токен передаётся в mapboxgl.accessToken
  • deck.gl использует Mapbox canvas context
  • слои данных накладываются поверх tile-based map

Пример низкоуровневой установки:

import mapboxgl from 'mapbox-gl';

mapboxgl.accessToken = MAPBOX_TOKEN;

Различие public и secret токенов

Тип токена Назначение Использование
pk.* Public access Frontend, Kepler.gl
sk.* Admin API Backend, управление токенами

Secret токен позволяет:

  • создавать/удалять токены
  • управлять стилями
  • доступ к административным API

Использование sk в Kepler.gl недопустимо.

Оптимизация работы с токеном

Кэширование стилей

Mapbox автоматически кэширует:

  • tile requests
  • style JSON
  • glyphs (шрифты)

Снижение количества запросов

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

Работа с несколькими токенами

В сложных системах применяются разные токены:

  • отдельный токен для staging
  • отдельный для production
  • ограниченные токены для аналитических дашбордов

Переключение происходит через конфигурацию Kepler.gl state без пересборки приложения.

Поведение при отсутствии интернета или API

Если Mapbox API недоступен:

  • базовая карта не отображается
  • данные Kepler.gl (GeoJSON, CSV) остаются доступными
  • взаимодействие со слоями сохраняется частично

Это важно при офлайн-аналитике, где карта служит только визуальной подложкой.

Взаимодействие токена с тайловой системой Mapbox

Mapbox использует систему vector tiles:

  • токен авторизует запрос к tile endpoint
  • каждый zoom level требует отдельные тайлы
  • Kepler.gl агрегирует тайлы для рендеринга слоёв

Схема запроса:

Client → Mapbox GL JS → Tile API → Vector Tiles → Render

Токен участвует в каждом запросе как параметр авторизации.

Практика работы с ограниченными токенами

В продакшн-средах часто применяются:

  • token rotation (регулярная смена)
  • scoped tokens (ограниченные права)
  • environment-based tokens (dev/stage/prod)

Это снижает риск компрометации и упрощает управление доступом к картографической инфраструктуре.

Оглавление