Как вставить карту на сайт: пошаговая инструкция с API-ключом и защитой по домену

Карта на сайте нужна почти любому бизнесу с офлайн-точками: клиника, магазин, сервисный центр, пункт выдачи, юридическая или строительная компания. Технически задача сводится к четырём вещам: получить ключ доступа, привязать его к своему домену, подобрать внешний вид карты и вставить на страницу несколько строк кода. Ниже — полный путь с настоящими экранами личного кабинета Karty и разбором ошибок, на которых новички теряют больше всего времени.

Что понадобится

• Доступ к редактированию страницы сайта — достаточно блока «произвольный HTML-код». В Tilda это «Т123», в WordPress — блок «Произвольный HTML», в «1С-Битрикс» — HTML-блок или компонент с кодом. Для сайта на конструкторе, который не разрешает вставку кода, виджет не подойдёт.
• Адрес сайта (домен). Ключ мы привязываем именно к нему — об этом отдельный шаг ниже.
• Координаты центра карты, если нужен определённый вид: долгота и широта. Если их нет, достаточно названия города — центр можно подобрать прямо в конструкторе, перетащив карту.

Никаких серверов и собственных тайлов поднимать не нужно: карта рисуется нашим сервисом на открытых картографических данных, покрытие — вся Россия, включая Крым, ДНР и ЛНР.

Шаг 1. Регистрация и стартовая квота

Регистрация в личном кабинете занимает минуту. Сразу после неё начинается пробный период на 3 дня: доступны все продукты сервиса, лимиты те же, что у тарифа «Базовый» (299 ₽ за 30 дней). Когда пробный период закончится, доступ приостанавливается до оплаты тарифа — об этом кабинет предупреждает заранее, а ваши данные хранятся ещё 90 дней.

На странице «Обзор» видно, сколько квоты потрачено по каждому из семи продуктов, и есть короткий чек-лист «Первые шаги»: создан ли ключ, указан ли у него разрешённый домен и был ли первый реальный запрос.

Шаг 2. Создаём ключ API и выбираем его тип

Откройте раздел «Ключи». Один ключ с названием «По умолчанию» уже создан — его можно использовать сразу. Но привычка заводить отдельный ключ под каждый сайт и под тестовую среду окупается: так в статистике видно, какой сайт сколько потратил, а скомпрометированный ключ можно отозвать, не ломая остальные проекты.

При создании нужно выбрать тип. Здесь чаще всего и путаются, поэтому разберём подробно.

Тип	Префикс	Где использовать	Что с ним можно
Publishable	pk_live_…	В браузере, прямо в коде страницы	Карта, тайлы, поиск адреса, маршрут, зоны доступности, статичная картинка
Secret	sk_live_…	Только на вашем сервере	Всё то же плюс пакетный геокодинг, матрица расстояний и оптимизация маршрутов

Для карты на сайте вам нужен publishable-ключ. Он виден в исходном коде страницы, и это нормально: так устроены все встраиваемые карты. Защищает такой ключ не секретность, а привязка к домену и суточный лимит. Secret-ключ, наоборот, нельзя класть в код страницы и передавать в адресной строке (?key=): он попадёт в логи и историю браузера. Мы такие запросы отклоняем, ключ принимается только в заголовке Authorization: Bearer.

Шаг 3. Привязываем ключ к домену

Привязка к домену — главная защита publishable-ключа: без неё любой, кто скопирует ключ из исходного кода, мог бы рисовать карты на своём сайте за ваш счёт. Поэтому по умолчанию работает правило «всё, что не разрешено, запрещено»: пока в настройках ключа нет ни одного домена, он не принимается из браузера вообще, и карта на вашем сайте покажет ошибку доступа. Откройте настройки ключа (иконка карандаша) и впишите разрешённые домены — это обязательный шаг, а не формальность.

• Домен пишется без https:// и без слэша на конце: example.ru.
• Чтобы разрешить сразу основной домен и все его поддомены (www, shop, blog), впишите маску *.example.ru — она покрывает и сам example.ru. Точная запись example.ru разрешает только этот хост и не включает www.example.ru.
• Адреса localhost и 127.0.0.1 автоматически не добавляются. Если вы тестируете карту на локальной машине, впишите их вручную — и уберите перед выпуском.
• Изменение применяется сразу: встраивания с других доменов перестанут работать.

Шаг 4. Настраиваем карту в конструкторе встраивания

Раздел «Встраивание» — это живой предпросмотр с генератором кода. Всё, что вы меняете слева, сразу видно на карте и попадает в код под ней. Предпросмотр работает на внутреннем ключе и не тратит вашу квоту.

Тема оформления

Шесть готовых тем: тёплая (по умолчанию), светлая, белая, серая, тёмная и чёрная. Если нужен фирменный вид, кнопка «Настроить цвета» в блоке «Мои стили» открывает редактор: можно перекрасить воду, парки, дороги и подписи под палитру сайта. Количество собственных стилей зависит от тарифа: один на тарифах до «Старта» включительно, 5 на «Бизнесе», 20 на «Масштабе».

Поиск по адресу

Переключатель «Показать поиск» добавляет в левый верхний угол поле поиска. Поиск запускается по Enter. Если включить «Автодополнение», подсказки появятся по мере ввода — но помните, что каждая подсказка расходует квоту геокодинга (одинаковый запрос в течение 5 минут бесплатный). Для обычной карты проезда автодополнение не нужно, а вот для формы заказа с адресом доставки оно удобно.

Размер и масштаб

Размер блока задаёт пропорции: во всю ширину 16:9 подходит для страницы «Контакты», квадрат — для боковой колонки. «Пределы приближения» ограничивают минимальный и максимальный зум: если клиентам достаточно видеть район, не позволяйте уходить на карту мира. Начальный вид задаётся перетаскиванием и приближением карты прямо в предпросмотре.

Шаг 5. Вставляем код на сайт

Под предпросмотром три вкладки с кодом. Вкладка «JS» даёт примерно такой фрагмент (ключ и координаты подставятся ваши):

<script src="https://kartrout.ru/widget/karty.js"></script>
<div id="map" style="width:100%;aspect-ratio:16/9;min-height:240px"></div>
<script>
  var map = Karty.map('map', {
    key: 'pk_live_ВАШ_КЛЮЧ',
    style: 'warm',
    center: [83.7636, 53.3478],   // [долгота, широта]
    zoom: 12
  });
  map.attachSearch({});
</script>

Обратите внимание на порядок координат: сначала долгота, потом широта. Это стандарт для веб-карт, а не наоборот, как привыкли по картам-приложениям, — перепутанные местами числа выбрасывают карту в океан у берегов Африки.

Вкладка «Без кода (data-атрибуты)» — вариант для тех, кто не хочет писать JavaScript: достаточно одного <div> с атрибутами data-karty-map, data-karty-key, data-karty-lon, data-karty-lat и data-karty-zoom, плюс подключённый скрипт. Именно этот способ удобнее всего в конструкторах сайтов: вставили блок — и карта работает.

Куда вставлять в популярных системах

• Tilda: блок «Т123» (HTML) на нужной странице; можно добавить блок в «Контакты» и в подвал.
• WordPress: блок «Произвольный HTML» в редакторе Gutenberg или виджет «HTML» в боковой колонке.
• «1С-Битрикс» и самописные сайты: разметку блока вставьте в шаблон, а подключение скрипта оставьте в футере — так он не будет тормозить первый экран.
• React, Vue и другие SPA: создавайте карту после монтирования компонента и вызывайте map.remove() при размонтировании; для динамически добавленных блоков с data-атрибутами есть повторное сканирование страницы — вызов Karty.autoInit().

Шаг 6. Проверяем, что всё работает

1. Откройте страницу с боевого домена (не из редактора конструктора и не из локального файла: у такой страницы нет разрешённого домена) и убедитесь, что карта нарисовалась, а в углу виден значок атрибуции — он обязателен по лицензии картографических данных и не убирается.
2. Проверьте мобильную версию: блок с width:100% и заданной высотой или aspect-ratio сам подстроится под экран.
3. Вернитесь в «Обзор»: пункт «Зафиксирован первый реальный запрос» должен стать зелёным, а счётчик тайлов — вырасти.

Если карта не появилась, посмотрите на текст сообщения под значком — он подскажет причину:

Сообщение	Что делать
«неверный или отозванный ключ доступа»	Проверьте, что ключ скопирован целиком, без лишних пробелов, и не отозван в разделе «Ключи».
«этот домен не разрешён для данного ключа»	Добавьте домен сайта в настройки ключа (шаг 3) — лучше маской *.example.ru, чтобы покрыть www и поддомены. Тот же ответ вы получите, если у ключа вообще нет доменов.
«лимит тарифа исчерпан или тариф не оплачен»	Закончилась квота или не оплачен тариф. Квота обновляется каждые 30 дней с даты оплаты; в разделе «Тариф» можно докупить объём или сменить тариф.
«превышен лимит запросов»	Слишком частые запросы или публичный ключ достиг суточного лимита (не более 30% месячной квоты в сутки; сброс в 00:00 по Москве).

Сколько расходует карта и как не выйти за лимит

Карта потребляет квоту «тайлы»: это фрагменты изображения, которые браузер подгружает при показе и перемещении. Мы измерили реальную нагрузку: один неподвижный кадр — около 6 тайлов, а типичный визит «открыл, подвинул, приблизил» — в среднем 15–25. Поэтому ориентируйтесь на ≈20 тайлов на показ карты.

Тариф	Цена за 30 дней	Тайлов	≈ показов карты	Геокодингов
Базовый	299 ₽	5 000	≈250	1 500
Старт	1 490 ₽	15 000	≈750	8 000
Бизнес	4 990 ₽	70 000	≈3 500	40 000
Масштаб	14 900 ₽	300 000	≈15 000	150 000

Несколько приёмов, которые экономят квоту без потери качества:

• Статичная картинка вместо живой карты. Для страницы «Контакты», где карту редко двигают, часто хватает картинки: она расходует одну единицу из отдельной квоты статичных карт, а не десятки тайлов. Подробности — в документации.
• Ограничьте пределы зума. Чем меньше возможных уровней приближения, тем меньше тайлов запросит посетитель.
• Один ключ — один сайт. Тогда в «Использовании» сразу видно, где расход выше нормы.
• Следите за уведомлениями. На 80% и 100% квоты кабинет присылает сообщение с датой обновления и подсказкой о докупке.

Типичные ошибки при встраивании

• Скрипт подключён после кода инициализации. Тег <script src=…> должен идти раньше, чем вызов Karty.map(...).
• У контейнера нет высоты. Блок с width:100% без height или aspect-ratio схлопывается до нуля — карта «не видна», хотя ошибок нет.
• Один id на странице используется дважды. Для нескольких карт на одной странице нужны разные идентификаторы.
• Secret-ключ в коде страницы. Если вы случайно вставили sk_live_…, сразу отзовите его и создайте новый; в браузере для карты нужен только publishable-ключ.
• Домен не совпадает. Сайт работает на www.example.ru, а в ключе указан example.ru. Используйте маску *.example.ru или добавьте оба адреса.
• Домены у ключа не заданы. Новый ключ «По умолчанию» создаётся без доменов, поэтому код из конструктора, вставленный на сайт «как есть», сначала выдаст ошибку доступа. Добавьте домен — и карта заработает сразу, ждать не нужно.

Частые вопросы