Встраивание

Глобус работает внутри любой страницы как iframe. Одна строка показывает карту главы рядом с текстом, который открыт у читателя, а несколько сообщений согласуют карту с текстом.

Быстрый старт

<iframe
  src="https://historyglobe.app/embed/v1?ref=Acts.16&locale=ru"
  title="Карта: Деяния, глава 16"
  style="width: 100%; height: 480px; border: 0; border-radius: 12px"
  allow="fullscreen"
  loading="lazy"
></iframe>

Карта откроется на местах 16-й главы Деяний в год её событий и займёт всю рамку. Сверху — глава: по нажатию она показывает свои места в том порядке, в каком их называет текст, а нажатие на место открывает его карточку. Снизу — год: по нажатию открывается шкала времени. Ссылка открывает тот же вид на полном глобусе в новой вкладке. Источники данных подписаны на самой карте, как того требуют лицензии. Рамка годится и для экрана телефона; высоты в 480 px достаточно.

Глава или отрывок

ref принимает ссылку в формате OSIS: английские сокращения книг и нумерацию английских переводов (Пс. 22 по Синодальному — это Ps.23):

Значение	Показывает
`Acts.16`	главу
`Gen.12-Gen.13`	до трёх глав подряд
`Acts.16.11-Acts.16.15`	отрывок
`Ruth`	всю книгу

Карта переходит в год отрывка: в год, указанный для его глав (датированы главы 56 книг), а если его нет — в год экскурсии, в которую входит этот отрывок; для всей книги берётся год экскурсии, у которой больше всего остановок в этой книге. Если нет ни того ни другого, год не меняется.

Параметры

Параметр	Пример	Значение
`ref`	`Acts.16`	глава, отрывок или книга (см. выше)
`year`	`-999`	год в астрономическом счёте: 1 г. до н. э. — `0`, 1000 г. до н. э. — `-999`
`place`	`af2161c`	открыть место (Капернаум); идентификаторы — из OpenBible
`tour`	`paul-1`	начать экскурсию
`stop`	`3`	вместе с `tour`: открыть её на этой остановке
`lesson`	`a15257a~30.a112427~30`	свой урок, вместе с `tour=lesson`: идентификаторы мест по порядку, у каждого — год, на который его показывать (`~-585` — 586 г. до н. э.: как в `year`, 1 г. до н. э. — это 0); на каждой остановке — стих о месте, ближайший к этому году, расстояние, время пути пешком и рельеф. Такую ссылку собирает кнопка «В урок» в карточке места
`title`	`Павел%20в%20Галатии`	вместе с `lesson`: название урока, до 80 знаков, в заголовке его экскурсии и листа для печати
`locale`	`ru`	язык: `ru` или `en`
`camera`	`35.2,31.8,7,30,0`	долгота, широта, масштаб, наклон, поворот
`hide`	`relief,ancient`	выключить слои: `borders`, `places`, `relief`, `routes`, `roads`, `ancient`

Проще всего настроить вид на самом глобусе и скопировать адрес: те же параметры работают после /embed/v1.

Сообщения

Глобус и ваша страница обмениваются сообщениями через postMessage. Каждое сообщение — объект с type и v: 1. Глобус передаёт только вид карты и никаких сведений о читателе; сообщения он принимает только от страницы, в которую встроена рамка.

От глобуса

Тип	Данные	Когда
`hg:ready`	`{ view }`	карта нарисована
`hg:view-changed`	`{ view }`	вид карты изменился и устоялся: год, место, экскурсия или положение камеры
`hg:verse-clicked`	`{ osis }`	читатель нажал на стих, например `"Acts.16.12"`
`hg:error`	`{ code, message }`	карта или данные не загрузились

В view всегда есть year, locale и layers, а если заданы, то place, tour, stop, ref и camera.

Глобусу

Тип	Данные	Что делает
`hg:set-view`	`{ view }`	переходит к году, главе (`ref`), месту, слоям или положению камеры; с `tour` (и `stop`) начинается экскурсия, а остальные поля не учитываются; язык меняется только через `hg:set-locale`
`hg:set-locale`	`{ locale }`	меняет язык

Пример: карта следует за читателем

const globe = document.querySelector("iframe").contentWindow;

// Читатель открыл главу — показать её на карте.
function showChapter(osis) {
  globe.postMessage({ type: "hg:set-view", v: 1, view: { ref: osis } }, "*");
}

// На карте нажали стих — открыть его в вашем тексте Библии.
window.addEventListener("message", (e) => {
  if (e.source !== globe) return;
  if (e.data?.type === "hg:verse-clicked") openVerse(e.data.osis);
});

Места в любом тексте

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

Павел отплыл из Кесарии на Кипр, проповедовал в Ефесе и Коринфе и писал в Рим. Задолго до того Авраам пришёл к Сихему и в Хеврон; Иисус родился в Вифлееме и вырос в Назарете, а Иоанн видел свои видения на острове Патмос.

Живой пример: эти названия связал скрипт на этой странице.

<script src="https://historyglobe.app/hg-places.js" data-scope="article" charset="utf-8" defer></script>

Атрибут	Что делает
`data-scope`	где искать, CSS-селектор; по умолчанию вся страница
`data-locale`	`ru` или `en`: язык текста; по умолчанию `lang` страницы
`data-every`	связывать каждое упоминание, а не только первое у каждого места
`data-theme`	`light` или `dark` для карточки; по умолчанию как в системе читателя

Связываются только названия, которые указывают на одно место. Название, общее для двух мест (Антиохия — Сирийская и Писидийская), для места и человека (Иуда) или для места и обычного слова, остаётся простым текстом. Так же остаётся название, которое в самих стихах Библии чаще значит другое: «Иудеи» там почти всегда народ, а не родительный падеж от «Иудея». Название места, которое бывает и личным именем (Нил), рядом с другим словом с заглавной буквы не связывается: Нил Сорский — не река. Русские названия находятся во всех падежах: «в Египте», «из Антиохии Писидийской». Ссылки, код, поля форм, кнопки и заголовки скрипт не трогает.

У скрипта нет зависимостей, и он не ставит cookie. Он читает с глобуса один файл названий (по сети около 35 КБ для русского и 25 КБ для английского, плюс 7 КБ самого скрипта), не передавая адрес вашей страницы, и меняет только те названия, которые связывает. Он работает и при строгой политике безопасности (CSP), если адрес глобуса разрешён в script-src и connect-src. Для текста, который страница добавит позже, вызовите HistoryGlobePlaces.scan(element), когда текст уже отрисован: скрипт делит текстовые узлы, поэтому на странице React или Vue запускайте его на содержимом, которое фреймворк больше не перерисовывает.

Стабильность

/embed/v1 — это стабильный контракт: внутри v1 параметры и сообщения только добавляются, но не меняются и не удаляются. Изменение, которое сломало бы чужую страницу, выйдет как /embed/v2, а v1 продолжит работать.

Данные на 3 октября 2026 г.

Встраивание

#Быстрый старт

#Глава или отрывок

#Параметры

#Сообщения