--- metadata: - name: generator content: Diplodoc Platform v5.39.1 alternate: - https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/dg/concepts/load.md - https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/dg/concepts/load.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/llms.txt # Подключение API [Параметры загрузки API](#param) [Подключение нужной версии API](#section_b2b_1q1_v2b) [Загрузка API по требованию](#condition) [Готовность API](#api-ready) [Подключение API при использовании CSP](#using-csp) Для использования API Яндекс Карт необходимо, чтобы компоненты API были загружены вместе с кодом страницы как обычный внешний JavaScript-файл. Наиболее распространенным способом подключения внешних скриптов является использование элемента `script` в заголовке HTML-документа. Например: ```xml ``` {% note info %} Вы также можете использовать подпись для загрузки API: ```html ``` Более подробно о механизме подписи запросов можно узнать в [документации](https://yandex.ru/maps-api/docs/common/security/signature_usage.html). {% endnote %} Обратите внимание, что в стандартном браузере мобильной операционной системы Android и Apple iOS версии ниже 3.2 жест масштабирования над картой приводит к увеличению масштаба всей страницы средствами браузера. Для того чтобы отключить обработку жеста масштабирования, необходимо добавить в тег head страницы следующий код: ```xml ``` Подробнее см. описание метатега viewport в [Safari HTML Reference](https://developer.apple.com/library/safari/documentation/appleapplications/reference/safarihtmlref/articles/metatags.html). ## Параметры загрузки API {#param} Для бесплатной версии API ссылка для загрузки имеет вид: ```http https://api-maps.yandex.ru/2.1?apikey=ваш API-ключ&lang=<идентификатор языка>&<дополнительные параметры> ``` Для платной версии API ссылка имеет вид: ```http https://enterprise.api-maps.yandex.ru/2.1?apikey=ваш API-ключ&lang=<идентификатор языка>&<дополнительные параметры> ``` В таблице ниже описаны параметры, которые можно указать при загрузке API. #| || **Параметр** | **Описание** || || `apikey`[*](*star) | **Обязательный параметр.** API-ключ. Получить ключ можно в [Кабинете разработчика](https://developer.tech.yandex.ru/). || || `lang`[*](*star) | **Обязательный параметр.** Локаль. Задается в виде: {% include [localization-lang_2](../../../_includes/2.1/dg/concepts/localization/id-localization/lang_2-37881b63d0a7.md) %} {% include [localization-lang_3](../../../_includes/2.1/dg/concepts/localization/id-localization/lang_3-a0b0f3bdf6f3.md) %} {% include [localization-lang_4](../../../_includes/2.1/dg/concepts/localization/id-localization/lang_4-b54c0bb61e3b.md) %} || || `suggest_apikey` | Ключ [API Геосаджеста](https://yandex.ru/dev/geosuggest/doc/ru/). Получить ключ можно в [Кабинете разработчика](https://developer.tech.yandex.ru/). {% include [include](../../../_includes/2.1/terms/index-47b676c75e05.md) %} || || `coordorder` | Порядок задания географических координат при работе API. Возможные значения: - `latlong` — [широта, долгота] — используется по умолчанию; - `longlat` — [долгота, широта]. || || `load` | Список загружаемых модулей. Имена модулей перечисляются через запятую. Например, `load=Map,Placemark,map.addon.balloon`. Компоненты также можно загружать «по требованию», используя функцию [require](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/modules.require.md). Значение по умолчанию: `package.full`. || || `mode` | Режим загрузки API. Код API может быть загружен в упакованном виде для минимизации трафика и скорости исполнения в браузере (`mode=release`), а также в виде исходного кода (`mode=debug`). Загрузка в виде исходного кода удобна для отладки JavaScript-компонентов — код всех загруженных компонентов доступен для просмотра. Кроме того, в этом режиме в консоль выводятся сообщения об ошибках и исключениях. При загрузке в упакованном виде эти сообщения не выводятся. Значение по умолчанию: `release`. || || `csp` | Включает режим использования CSP. Может принимать значение true. Подробнее см. [Подключение API при использовании CSP](#using-csp). || || `ns` | Пространство имен, в котором локализованы программные компоненты API. По умолчанию все объекты принадлежат пространству имен `ymaps` (например, ymaps.[Map](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Map.md)). Если при загрузке API указать `ns=myNameSpace`, то объекты будут доступны уже как `myNameSpace`.[Map](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Map.md). Использование пространства имен позволяет избежать пересечения названий функций и прочих программных компонентов, используемых в API и пользовательском/стороннем коде. Вы можете задать пустое значение ns. В этом случае API не будет создавать объектов в глобальной области видимости, и доступ к функциональности API получит только функция, указанная в параметре `onload`. Значение по умолчанию: `ymaps`. || || `onload` | Имя функции, которую необходимо вызвать после того, как компоненты API будут загружены и готовы к использованию (callback). В эту функцию в качестве аргумента будет передан объект-неймспейс с функциональностью API. Допускается использование вложенных пространств имен: `onload=myfunction` `onload=myapp.dosmth` Пример использования приведен в [таблице](#example) ниже. || || `onerror` | Имя callback-функции, которая будет вызвана в случае ошибки загрузки API. В эту функцию в качестве аргумента будет передан объект, содержащий информацию об ошибке. || || `signature` | Подпись запроса. Более подробно о механизме подписи запросов можно узнать в [документации](https://yandex.ru/maps-api/docs/common/security/signature_usage.html). || |# \* Обязательный параметр. ## Подключение нужной версии API {#section_b2b_1q1_v2b} В ссылке подключения API Яндекс Карт всегда необходимо указывать номер версии. - Подключить текущую версию API (то есть последнюю стабильную версию): ```http https://api-maps.yandex.ru/2.1?apikey=ваш API-ключ&lang=ru_RU ``` - Подключить релиз-кандидат можно по ссылке: ```http https://api-maps.yandex.ru/2.1-dev?apikey=ваш API-ключ&lang=ru_RU ``` Релиз-кандидат — это новая версия API, которая доступна для открытого использования, но находится на стадии утверждения. Используя релиз-кандидат в своих проектах, вы поможете нам своевременно выявить возможные ошибки. Кроме того, вы сможете заранее протестировать работу приложения с новой версией API. - Подключить фиксированную версию API: ```http https://api-maps.yandex.ru/2.1.68?apikey=ваш API-ключ&lang=ru_RU ``` {% include [loading-variants-update-version](../../../_includes/2.1/versions/index/id-loading-variants/update-version-2948aeaae16c.md) %} Подробнее про версионирование в API см. в разделе [Версии JavaScript API](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/versions/index.md). ## Загрузка API по требованию {#condition} С помощью функции [modules.require](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/modules.require.md) можно загружать отдельные компоненты API. Это бывает полезно, когда нужно загрузить какие-нибудь компоненты API по требованию. ```xml ``` ## Готовность API {#api-ready} Компоненты API Яндекс Карт всегда загружаются асинхронно. Это происходит даже в том случае, если для подключения API используется тег ` // Формирование div-контейнер карты.
``` || || **Использование параметра загрузки onload** || || ```javascript // Формирование div-контейнер карты.
``` || |# Возникновение событий загрузки DOM-дерева или документа не сигнализирует об окончании загрузки API. То есть использование обработчиков событий типа `document.ready`, `window.onload`, `jQuery.ready` и пр. не позволяет определить, готовы ли компоненты для использования. Для инициализации карты необходимо, чтобы в DOM-дереве находился элемент, в котором она размещается. Функция `ready` исполняет включенный в нее код после того, как будут загружены компоненты API _и_ DOM-дерево документа. Функция, переданная в параметр onload вызывается после загрузки API, но не отслеживает готовность DOM-дерева. В этом случае отслеживать доступность HTML-элемента, в который помещается карта, необходимо самостоятельно. Например, при помощи обработчиков событий, перечисленных выше. Использование параметра onload дает возможность инициализировать карту, не дожидаясь, пока DOM будет сформирован полностью. Поэтому данный способ является самым быстрым способом загрузки API. ## Подключение API при использовании CSP {#using-csp} Если приложение использует [политику защиты контента](https://developer.mozilla.org/en-US/docs/Web/Security/CSP) (CSP), то для корректной работы с API в политику необходимо добавить [правила](#white-list), разрешающие загрузку ресурсов с доменов Яндекса. {% note alert %} По умолчанию в API отключена поддержка CSP. Для ее активации при подключении API нужно передать параметр csp=true и указать используемую [минорную версию API](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/versions/index.md#fixed-version): {% list tabs %} - Бесплатная версия ```http https://api-maps.yandex.ru/2.1.77/?apikey=&lang=ru_RU&csp=true ``` - Платная версия ```http https://enterprise.api-maps.yandex.ru/2.1.77/?apikey=&lang=ru_RU&csp=true ``` {% endlist %} Рекомендуется обновлять используемую версию API не реже чем раз в квартал. При обновлении версии API может измениться список необходимых доменов, поэтому необходимо обновить список разрешенных доменов согласно таблице ниже. {% endnote %} В таблице ниже приведены правила, которые необходимо добавить в политику приложения для работы c API. Правила перечисляются отдельно для каждой директивы. Обратите внимание на многоточия в примерах — это означает, что правила, необходимые для работы с API, приведены без учета других правил, которые разработчик может задать для своего приложения. Если для какой-либо директивы в политике будет разрешена загрузка из любых источников (например, 'img-src *;'), то для этой директивы соответствующие правила API можно не задавать. #| || **Директива** | **Правила, которые требуется добавить в директиву** || || `img-src` | Для директивы `img-src` в список разрешенных источников необходимо добавить домены: - `https://*.maps.yandex.net` (для загрузки тайлов); - `api-maps.yandex.ru` (для загрузки курсоров и т. п.); - `*.api-maps.yandex.ru` (для загрузки курсоров и т. п.); - `enterprise.api-maps.yandex.ru` (для загрузки курсоров в платной версии API); - `https://yandex.ru`. С этих доменов будут загружаться изображения API. Кроме того, некоторые изображения API вставляются через data:URL, поэтому в директиве `img-src` также необходимо указать протокол **data:**. ```http img-src data: https://*.maps.yandex.net api-maps.yandex.ru ...; ``` || || `frame-src` | В директиве `frame-src` должены быть разрешены домены - `https://api-maps.yandex.ru` - `https://enterprise.api-maps.yandex.ru` (для платной версии API) С этих доменов будут загружаться компоненты API, которые размещаются во фреймах (например, блок «Открыть в Яндекс Картах»): ```http frame-src https://api-maps.yandex.ru ...; frame-src https://enterprise.api-maps.yandex.ru ...; ``` {% note info %} Директива `frame-src` используется в CSP версии 1.0; в версии 2.0 эта директива заменена на `child-src`. Однако некоторые браузеры еще не поддерживают CSP 2.0, поэтому для обеспечения кроссбраузерной совместимости в политике рекомендуется указывать обе эти директивы: ```http frame-src https://api-maps.yandex.ru ...; child-src https://api-maps.yandex.ru ...; frame-src https://enterprise.api-maps.yandex.ru ...; child-src https://enterprise.api-maps.yandex.ru ...; ``` {% endnote %} || || `script-src` | В директиве `script-src` нужно добавить следующие домены: - `https://api-maps.yandex.ru` - `https://*.api-maps.yandex.ru` - `https://enterprise.api-maps.yandex.ru` (для платной версии API) - `https://suggest-maps.yandex.ru` - `https://*.maps.yandex.net` - `https://yandex.ru` - `https://yastatic.net` С этих доменов будут загружаться модули API. Кроме того, для работы с шаблонами в директиве `script-src` рекомендуется включить поддержку 'unsafe-eval’ (это необходимо для работы условных операторов). ```http script-src 'unsafe-eval' https://api-maps.yandex.ru https://suggest-maps.yandex.ru https://*.maps.yandex.net https://yandex.ru ...; ``` || || `connect-src` | Для директивы `connect-src` следует разрешить домены: - `https://api-maps.yandex.ru` - `https://*.api-maps.yandex.ru` - `https://enterprise.api-maps.yandex.ru` (для платной версии API) - `https://suggest-maps.yandex.ru` - `https://*.maps.yandex.net` - `https://yandex.ru` - `https://*.taxi.yandex.net` ```http connect-src https://api-maps.yandex.ru https://suggest-maps.yandex.ru https://*.maps.yandex.net https://yandex.ru ...; ``` || || `style-src` | Для загрузки стилей API в директиве `style-src` необходимо указать протокол **blob:**. ```http style-src: blob: ...; ``` API будет подключать стили на страницу через элемент <\link\>, содержащий blob URL нужного стиля. Если в приложении использование blob невозможно, то для корректной работы с API в директиве `style-src` можно указать nonce-значение, сгенерированное на стороне клиента. В этом случае API будет подключать стили через inline-элемент <\style nonce="..."\>. ```http style-src 'nonce-<токен>' ...; ``` Это же значение следует передать в параметре `csp` при подключении API: Для бесплатной версии API: ```http https://api-maps.yandex.ru/2.1/?apikey=&lang=ru_RU&csp[style_nonce]=<токен> ``` Для платной версии API: ```http https://enterprise.api-maps.yandex.ru/2.1/?apikey=&lang=ru_RU&csp[style_nonce]=<токен> ``` Следует иметь в виду, что атрибут `nonce` реализован в CSP 2.0 и не поддерживается в версии 1.0. Однако в некоторых браузерах еще не включена поддержка CSP 2.0, поэтому для обеспечения кроссбраузерной совместимости в `style-src` рекомендуется использовать протокол blob:. || |# Если для какого-либо ресурса API политика определена неправильно, то карта (либо ее объекты) будут отображаться некорректно. При этом API не отслеживает, для каких ресурсов политика задана неверно. Чтобы получить информацию о том, какие ресурсы карты не могут быть загружены, можно воспользоваться директивой [report-uri](https://developer.mozilla.org/en-US/docs/Web/Security/CSP/CSP_policy_directives#report-uri). Ниже приведен пример политики, в которой определены правила для работы с API, а также другие правила приложения: {% list tabs %} - Бесплатная версия ```httpget Content-Security-Policy: img-src data: https://*.maps.yandex.net https://*.api-maps.yandex.ru https://api-maps.yandex.ru https://yandex.ru 'self'; child-src https://api-maps.yandex.ru; frame-src https://api-maps.yandex.ru; script-src https://api-maps.yandex.ru https://*.api-maps.yandex.ru https://suggest-maps.yandex.ru http://*.maps.yandex.net https://yandex.ru https://yastatic.net 'self'; connect-src https://api-maps.yandex.ru https://*.api-maps.yandex.ru https://suggest-maps.yandex.ru https://*.maps.yandex.net https://yandex.ru https://*.taxi.yandex.net; style-src blob:; ``` - Платная версия ```httpget Content-Security-Policy: img-src data: https://*.maps.yandex.net https://enterprise.api-maps.yandex.ru https://*.api-maps.yandex.ru https://yandex.ru 'self'; child-src https://enterprise.api-maps.yandex.ru; frame-src https://enterprise.api-maps.yandex.ru; script-src https://enterprise.api-maps.yandex.ru https://*.api-maps.yandex.ru https://suggest-maps.yandex.ru http://*.maps.yandex.net https://yandex.ru https://yastatic.net 'self'; connect-src https://enterprise.api-maps.yandex.ru https://*.api-maps.yandex.ru https://suggest-maps.yandex.ru https://*.maps.yandex.net https://yandex.ru https://*.taxi.yandex.net; style-src blob:; ``` {% endlist %} **Задание inline-стилей в шаблонах при включенном CSP** Иногда при работе с [шаблонами](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/dg/concepts/layouts.md) для DOM-элементов необходимо задавать inline-стили (например, при настройке автопозиционирования балуна). Если в API отключен режим CSP, inline-стили задаются стандартным образом, как обычный HTML-текст. Например: ```javascript