Яндекс.Карты

Что это за документ

Этот документ нужен компании, которая хочет подключить Яндекс.Карты к своей клиентской витрине, Telegram Mini App или Max мини-приложению и начать использовать карты в рабочих клиентских сценариях.

Если говорить совсем просто, Яндекс.Карты в Omnis нужны не ради самой карты, а ради понятных для клиента действий:

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

В Omnis карты обычно используются в двух основных сценариях:

• в CMS-компоненте Карта с метками
• в оформлении заказа, когда клиент выбирает пункт выдачи на карте

Что важно понять сразу

Для подключения карт в Omnis компании обычно нужен один рабочий API ключ Яндекс.Карт.

Практически это выглядит так:

1. Вы создаете ключ в кабинете разработчика Яндекса.
2. Копируете этот ключ.
3. Вставляете его в Omnis.
4. Сохраняете приложение.
5. Проверяете карту в клиентской витрине, Telegram Mini App или Max мини-приложении.

Важно понимать и еще одну вещь:

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

Релевантные разделы

• Карта с метками - если карта нужна как отдельный блок страницы.
• Блок страницы оформления заказа - если карта нужна для самовывоза.
• Пункты выдачи - если нужно сначала подготовить сами точки.
• Конструктор приложений - если ключ вносится при создании нового приложения.

Что дает подключение Яндекс.Карт компании

После подключения карт компания может:

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

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

• пункты выдачи
• магазины
• офисы
• шоурумы
• склады
• партнерские точки

Что нужно подготовить заранее

До подключения полезно подготовить:

• доступ к нужному приложению в Управление -> CMS
• аккаунт Яндекса, на котором будет создан ключ
• адрес клиентской витрины, Telegram Mini App или Max мини-приложения

Если вы уже знаете, что карта нужна именно для Telegram Mini App или Max мини-приложения, удобнее сразу держать под рукой адрес запуска приложения или хотя бы домен, на котором оно открывается.

Что именно брать, копировать и куда вставлять

Во всем процессе чаще всего используются два значения.

1. Где карты реально используются в Omnis

Для пользователя особенно важно понимать не общую теорию, а реальные места использования карт.

Сценарий 1. Компонент Карта с метками

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

Например:

• Где нас найти
• Наши магазины
• Пункты самовывоза
• Филиалы компании

Карта может содержать:

• несколько точек
• название точки
• краткое описание
• подробный текст
• свою иконку у метки

Подробнее работа этого блока разобрана здесь:

• Карта с метками

Сценарий 2. Выбор пункта выдачи в оформлении заказа

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

На карте клиент может:

• увидеть пункты выдачи
• переключаться между режимами На карте и Списком
• открыть подробности точки
• выбрать подходящий пункт прямо в процессе оформления

Подробнее сценарий описан здесь:

• Блок страницы оформления заказа

2. Какой ключ нужен для работы карт

В интерфейсе Omnis и в текущей логике приложения используется ключ для сервиса:

• JavaScript API и HTTP Геокодер

Именно этот вариант нужен для работы карт в клиентской витрине.

Если говорить проще:

• берите ключ для JavaScript-карт
• именно его Omnis использует для показа карты в приложении

В Конструкторе приложений система прямо подсказывает этот вариант при заполнении поля карты.

3. Как создать ключ Яндекс.Карт

Обычно порядок такой:

1. Откройте кабинет разработчика Яндекса.
2. Перейдите к созданию ключа для карт.
3. Выберите пакет JavaScript API и HTTP Геокодер.
4. Создайте ключ.
5. Скопируйте его.

Что важно знать про активацию ключа

По официальной документации Яндекс.Карт новый ключ может начать работать не мгновенно. Обычно на активацию может потребоваться до 15 минут.

Практически это означает:

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

это не всегда ошибка. Иногда нужно немного подождать, пока ключ активируется.

4. Какие ограничения ключа важно проверить

Это один из самых важных моментов во всем подключении.

По официальной документации Яндекс.Карт для JavaScript API ключ работает с учетом ограничений по HTTP Referer.

Для пользователя это значит следующее:

• при создании ключа важно указать домен вашей витрины, Telegram Mini App или Max мини-приложения
• если ограничения настроены слишком узко или неверно, карта может не загрузиться

Практический ориентир такой:

• берите домен из реального адреса витрины, Telegram Mini App или Max мини-приложения
• если приложение открывается по адресу вида https://xxx.tg.omnis-commerce.ru, то проверяйте именно домен этой ссылки

Если карта работает в обычном браузере, но не открывается в Telegram Mini App или Max мини-приложении, чаще всего стоит в первую очередь перепроверить ограничения ключа и адрес, к которому он привязан.

5. Где вставить ключ в Omnis

В Omnis есть два основных варианта подключения карты.

Вариант 1. Во время создания нового приложения

Откройте:

Управление -> CMS -> Конструктор приложений

На шаге Аналитика, карты и подсказки адреса заполните поле:

• API ключ яндекс-карт

В этом сценарии Omnis может сразу проверить ключ.

Если ключ введен неверно, система покажет сообщение о проблеме.

Вариант 2. В уже существующем приложении

Если приложение уже создано, откройте:

Управление -> CMS -> Приложения

И заполните поле:

• API ключ карт

Это удобно, если:

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

6. Что Omnis делает сам после сохранения ключа

После того как ключ сохранен в приложении:

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

Для пользователя это означает:

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

7. Когда может понадобиться отдельный ключ внутри самой карты

В обычной работе чаще всего достаточно общего ключа приложения.

Но у компонента Карта с метками есть и собственное настраиваемое свойство:

• apikey

Оно полезно, если:

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

Если общий ключ уже настроен и карта работает, это свойство обычно трогать не нужно.

8. Как начать использовать карты после подключения

После сохранения ключа есть два базовых варианта запуска.

Вариант 1. Добавить на страницу компонент Карта с метками

Обычно сценарий такой:

1. Создайте или откройте компонент Карта с метками.
2. Добавьте метки с координатами.
3. Заполните названия и описания точек.
4. Разместите компонент на нужной странице.
5. Откройте страницу в клиентской витрине.
6. Проверьте, что карта загружается и точки отображаются.

Вариант 2. Использовать карту в сценарии самовывоза

Обычно сценарий такой:

1. Проверьте, что в системе настроены пункты выдачи.
2. Убедитесь, что у точек есть координаты и адресные данные.
3. Откройте оформление заказа в клиентской витрине.
4. Переключитесь в сценарий самовывоза.
5. Проверьте, что карта пунктов выдачи открывается и позволяет выбрать точку.

9. Как быстро проверить, что карты работают

После сохранения ключа проведите короткую проверку.

Проверка отдельной карты на странице

1. Откройте страницу с компонентом Карта с метками.
2. Убедитесь, что карта загрузилась.
3. Проверьте, что точки стоят в правильных местах.
4. Нажмите на метки и убедитесь, что открываются подробности.

Проверка карты в оформлении заказа

1. Откройте клиентскую витрину, Telegram Mini App или Max мини-приложение.
2. Перейдите в корзину и оформление заказа.
3. Выберите сценарий самовывоза.
4. Откройте карту пунктов выдачи.
5. Проверьте режимы На карте и Списком.
6. Выберите одну из точек.

10. Что чаще всего делают неправильно

Ошибка 1. Берут не тот тип ключа

Для Omnis нужен ключ карт для сценария JavaScript API и HTTP Геокодер.

Ошибка 2. Неправильно настраивают ограничения ключа

Если домен витрины, Telegram Mini App или Max мини-приложения не учтен в ограничениях, карта может не загрузиться даже при внешне правильном ключе.

Ошибка 3. Проверяют карту сразу после выпуска ключа и считают, что все сломано

Новый ключ может активироваться не мгновенно.

Ошибка 4. Путают ключ карт с адресными подсказками

Ключ Яндекс.Карт и подсказки адреса это разные интеграции.

Ошибка 5. Подключают ключ, но забывают проверить сами точки

Даже при правильном ключе карта не поможет, если:

• координаты указаны неверно
• точки не заполнены
• у пунктов выдачи нет нужных данных

Ошибка 6. Ждут, что карта заработает без ключа

Если ключ не задан, карта не сможет загрузиться.

В отдельном компоненте клиент может увидеть сообщение о том, что ключ карты не задан.

11. Когда карты особенно полезны бизнесу

Карты особенно полезны, если:

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

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

12. Короткий чек-лист подключения

• создан ключ JavaScript API и HTTP Геокодер
• ключ активен
• проверены ограничения по домену или HTTP Referer
• скопирован правильный API ключ Яндекс.Карт
• ключ вставлен в Omnis
• приложение сохранено
• при необходимости создан компонент Карта с метками
• у точек или пунктов выдачи есть координаты
• карта открывается в витрине, Telegram Mini App или Max мини-приложении
• точки можно выбрать или открыть без ошибок