Интеграция

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

1. Подготовить хранение статьи

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

Для публикации нужно хранить:

• vms_html - готовый HTML для публичной страницы;
• vms_json - состояние редактора для повторного открытия;
• is_verstka - флаг, что материал выводится как публикация Verstka.

Для vms_html и vms_json используйте поля, которые могут вместить большой объем данных: например, TEXT/JSONB в PostgreSQL или LONGTEXT/JSON в MySQL.

2. Добавить кнопку в админку

В админке сайта нужна отдельная кнопка, например «Редактировать в Verstka».

Лучше сделать кнопку обычной ссылкой, которая открывается в новой вкладке и ведет на route вашего backend:

<a
  href="/admin/verstka/edit?post=123"
  target="_blank"
>
  Редактировать в Verstka
</a>

Этот backend route проверяет права пользователя, запрашивает у Verstka URL редактора и сразу делает redirect на него. Так новая вкладка открывается непосредственно по клику пользователя, и браузер не блокирует ее как всплывающее окно.

Кнопка-ссылка в CMS
   |
   v
Backend сайта получает editor_url
   |
   v
Redirect на editor_url
   |
   v
Verstka Editor открывается в новой вкладке

Если статья уже редактировалась в Verstka, при открытии нужно передать сохраненный vms_json. Тогда редактор откроет последнюю сохраненную версию публикации.

3. Принять callback после сохранения

Когда пользователь нажимает Save в Verstka, редактор не публикует статью сам. Вместо этого Verstka отправляет callback на ваш сайт.

Callback route на стороне сайта должен:

• принять событие сохранения;
• проверить подпись запроса;
• скачать ZIP с публикацией;
• обработать файлы, HTML и JSON;
• вернуть Verstka ответ об успешном сохранении.

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

4. Скачать и разобрать ZIP

После сохранения сайт получает ссылку на ZIP-архив с публикацией.

Внутри архива находятся основные данные:

• vms_html.html - HTML, который сайт будет выводить на публичной странице;
• vms_json.json - состояние редактора для следующего открытия;
• vms_media/* - медиафайлы публикации;
• metadata_json.json - служебные данные сохранения.

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

5. Сохранить медиа у себя

Медиафайлы из vms_media/* нужно положить в публичное хранилище сайта: CDN, uploads-директорию, S3 bucket или другое место, откуда файлы доступны читателям.

После сохранения каждого файла сайт получает его публичный URL. Эти URL нужно подставить обратно в HTML и JSON публикации.

SDK делает эту замену автоматически, если вы реализовали storage adapter: метод, который сохраняет файл и возвращает публичный URL.

6. Сохранить HTML и JSON

После обработки медиа сайт сохраняет:

• vms_html - HTML для публичной страницы;
• vms_json - обновленное состояние редактора с публичными URL файлов.

Именно обновленный vms_json нужно использовать при следующем открытии статьи в Verstka.

7. Вывести публикацию на сайте

На публичной странице сайт выводит сохраненный vms_html.

Для интерактивности, анимаций и эффектов нужно подключить JS библиотеку.

Если сайт использует npm-сборку, можно подключить пакет verstka-viewer.

Или можно подключить JS файл напрямую из облака.

<script type="module">
  import('https://go.r2.verstka.org/viewer-latest.js').then(({ Verstka }) => {
    Verstka.initArticles(document)
  })
</script>

8. Использование своего набора шрифтов

Шрифты сайта обрабатываются отдельно от конкретной статьи. Если в Verstka обновился набор шрифтов, сайт получит отдельный callback.

В этом случае нужно сохранить:

• vms_fonts/* - файлы шрифтов;
• vms_fonts.css - CSS с @font-face;
• vms_fonts.json - описание дерева шрифтов.

CSS шрифтов нужно подключать на страницах, где выводятся публикации Verstka. SDK так же помогает с этим.

Где помогает SDK

SDK нужен, чтобы не писать низкоуровневый протокол вручную. Он помогает:

• запрашивать API и получать editor_url;
• подписывать и проверять запросы;
• обрабатывать callback;
• скачивать ZIP;
• сохранять медиа через ваш storage adapter;
• сохранять обновленный набор шрифтов;
• заменять временные URL файлов на публичные;
• формировать правильный ответ для Verstka.

Дальше можно перейти к SDK для вашего backend:

• Python SDK
• PHP SDK

Если SDK не подходит, используйте Интеграцию API.