iFrame API · Довідка Measure Map Online

Показуйте один зі своїх проєктів як живу карту на власному вебсайті в одиницях, стилі карти й темі, що пасують вашому сайту.

iFrame API розміщує карту проєкту на вашій власній вебсторінці. Відвідувачі бачать супутникову карту з вашими вимірюваннями і можуть переміщатися нею без облікового запису та не залишаючи ваш сайт. Ви вибираєте проєкт, одиниці, стиль карти й колірну тему.

Перш ніж почати#

Робочий ключ API із доступом Вбудовані карти. Див. ключі API.
Проєкт, який можуть бачити відвідувачі: ваш або з іншого облікового запису, у спільному доступі з рівнем Тільки перегляд або Публічний. Приватний проєкт показується лише якщо він належить іншому обліковому запису і його власник авторизував вас (див. приватні проєкти клієнтів); ваші власні приватні проєкти не показуються ніколи. Див. які проєкти можна вбудовувати.
За бажання, обмеження вебсайтів для ключа, щоб вбудована карта працювала лише на ваших сайтах. Див. ключі API.

Створіть код для вбудовування#

Розробник > Вбудувати карту створює код за вас із вашим робочим ключем: виберіть проєкт, тему, одиниці, тип і розмір карти, перевірте Попередній перегляд наживо і скопіюйте Код для вбудовування. Якщо проєкт приватний, розділ повідомляє про це і пропонує Зробити лише для перегляду. Усі кроки див. у розділі отримайте код для вбудовування.

Вбудовування карти з вибраним проєктом і живим попереднім переглядом

Код містить ваш ключ, тому працює, доки ви не заміните ключ. Розділ попереджає, коли ключ може більше, ніж Вбудовані карти, адже кожен може прочитати його у вихідному коді вашої сторінки, і коли ключ не має обмежень вебсайтів. Лише Попередній перегляд наживо використовує короткочасний токен. Див. ключ чи токен.

Адреса вбудованої карти#

Вбудована карта — це <iframe>, адреса якого починається з https://app.measuremaponline.com/iframe_api, а далі йдуть такі параметри:

Параметр	Потрібен	Значення
`pid`	обов’язковий	Ідентифікатор проєкту: частина після `/p/` в адресі проєкту в застосунку. Його власник може скопіювати його внизу огляду проєкту, а клацання назви проєкту у вбудованій карті також його копіює.
`key`	`key` або `token`	Ваш ключ API.
`token`	`key` або `token`	Токен з вашого сервера (див. нижче).
`ms`	необов’язковий	Одиниці: `metric` або `imperial`. Без нього відвідувачі зі Сполучених Штатів бачать імперські одиниці, а решта — метричні.
`maptype`	необов’язковий	`satellite` (типове), `map`, `hybrid` або `terrain`.
`theme`	необов’язковий	`auto` (типове: відповідає власному системному налаштуванню відвідувача), `light` або `dark`.

Мінімальний приклад#

<iframe src="https://app.measuremaponline.com/iframe_api?pid=YOUR_PROJECT_ID&key=YOUR_API_KEY&maptype=satellite&theme=auto"
  title="YOUR_PROJECT_NAME" width="500" height="500" style="border:0" allow="fullscreen"></iframe>

Замініть YOUR_PROJECT_ID, YOUR_API_KEY і YOUR_PROJECT_NAME (екранні читачі озвучують title) та задайте ширину й висоту, що пасують вашій сторінці.

Код для вбудовування з кнопкою копіювання

Ключ чи токен#

З key, як у коді, який дає розділ Вбудувати карту, вбудована карта працює доти, доки працює ключ, на вебсайтах, які дозволяють його обмеження. Тоді ваш ключ видно у вихідному коді сторінки, тому:

використовуйте ключ лише з доступом Вбудовані карти;
обмежте його вашими власними вебсайтами;
коли замінюєте ключ, оновіть свої сторінки протягом 24 годин, поки старий ключ ще працює (ключ, створений до появи налаштувань доступу, працює до вказаної вам дати).

З token ключ залишається на вашому сервері. Це пасує вбудованим картам, які ваш сервер записує на сторінку для кожного візиту: перш ніж показати сторінку, він запитує в REST API токен і вставляє його в адресу iframe:

POST https://api.measuremaponline.com/api/v2/auth/iframe/token із вашим ключем у заголовку Authorization повертає token, що діє 60 хвилин;
POST https://api.measuremaponline.com/api/v2/auth/token робить те саме й приймає duration у секундах, до 24 годин. У його відповіді сказано, коли токен спливає.

Ваш обліковий запис може отримувати до 600 токенів на годину. Використовуйте робочий ключ: вбудовані карти показують лише робочі проєкти, тож токен, створений ключем sandbox, карту не відкриє. Див. довідник API.

Що можуть робити відвідувачі#

Відвідувачі можуть переміщати й масштабувати карту, читати вимірювання ваших фігур і коментарі до проєкту. Вони можуть додавати коментарі, якщо проєкт дозволяє коментувати всім, а клацання назви проєкту копіює його ідентифікатор. Нічого іншого вони змінити не можуть: редагування у вбудованій карті вимкнено незалежно від рівня доступу до проєкту. Єдиний виняток — проєкт Open Guest у плані Open Guest, де відвідувачі вимірюють самі.

Коли карта не з’являється#

У більшості випадків карта показує повідомлення з причиною: див. коли карта показує повідомлення. Перевірте по черзі:

В адресі є token, що спливув. Токени діють 60 хвилин, якщо ваш сервер не запитав довше. Скопіюйте код ще раз із Вбудувати карту, який використовує ваш ключ, або нехай ваш сервер отримує свіжий токен для кожного візиту (див. вище).
Проєкт приватний. Якщо це ваш проєкт, установіть для нього Тільки перегляд або Публічний, або натисніть Зробити лише для перегляду у Вбудувати карту. Якщо це проєкт клієнта, він може авторизувати вас просто з карти, або ви можете попросити його в розділі Приватні проєкти.
План проєкту завершився: план його власника, а для проєкту організації — план організації. Проєкт знову показується після поновлення плану.
Вебсайт не дозволено. Якщо ключ має обмеження вебсайтів, сторінка з вбудованою картою має бути на одному з них. Деякі браузери й сайти приховують, на якій сторінці розміщено вбудовану карту; за наявності обмежень таку карту буде відхилено.
Ключ замінено. Старий ключ перестає працювати через 24 години після створення нового або одразу, якщо його відкликано.
Ключ — це ключ sandbox. Вбудовані карти працюють лише з робочими ключами та робочими проєктами.
Підписка не активна, або доступ до API призупинено: розділ Ключі API про це повідомляє.