Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
README.md Update README.md Jul 16, 2019
js-sdk.md
php-sdk.md

README.md

Quick links

PHP SDK
JavaScript SDK
🇬🇧English language

Verstka API

Верстка предлагает разработчикам удобный способ интеграции редактора на сайт посредством API

Формат возвращаемых данных (кроме скачивания файлов) – JSON, и будет иметь следующие поля:

  • rc - код результата выполнения (1 - для успешных запросов)
  • rm - сообщение в текстовом виде
  • data - массив возвращаемых данных

Редактирование статьи

Для редактирования статьи достаточно отправить POST-запрос на URL https://verstka.io/api/open c параметрами:

  • material_id - идентификатор материала (обязательный уникальный не нулевой, при верстке отдельной мобильной версии используйте префикс 'M' в этом поле)
  • user_id - идентификатор текущего пользователя
  • html_body - html статьи (пустой в случае новой статьи)
  • api-key - API-key, выдаваемый при подключении к Verstka SaaS API
  • callback_url - URL-адрес, на который придет запрос при сохранении статьи в редакторе
  • host_name - с этого хоста редактор попытается скачать изображения статьи (если html_body содержит изображения и они имеют относительные адреса)
  • user_ip - IP-адрес текущего пользователя (дополнительный уровень безопасности при открытии редактора)
  • callback_sign - md5 от сконкатенированных параметров в следующем порядке: secret, api-key, material_id, user_id, callback_url
  • custom_fields - массив дополнительных параметров в формате JSON для включения дополнительных функций редактора

Возможные ключи массива custom_fields:

  • auth_user и auth_pw - если host_name закрыт с помощью http-авторизации
  • fonts.css - относительный путь до CSS-файла со шрифтами для подключения к редактору (описан ниже)
  • любые дополнительные данные (будут возвращены при сохранении статьи в неизменном виде)

В ответ Verstka API вернет в виде JSON следующие поля данных:

  • session_id - уникальный идентификатор сессии редактирования
  • edit_url - URL страницы редактора для этой сессии

Также в ответе будут дополнительные поля:

  • last_save - время последнего сохранения статьи (в случае если статья недавно редактировалась)
  • contents - URL для получения содержимого сессии редактирования (необходим только для интеграции без callback_url)
  • client_folder - вычисленный относительный URL до статического контента статьи на host_name (для debug)

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

  • lacking_pictures - список недостающих изображений
  • upload_url - URL для загрузки посредством POST multipart/form-data

Сохранение статьи

Сохранение статьи доступно в течение 48 часов с последнего взаимодействия (открытия или предыдущего сохранения) этой статьи

При нажатии пользователем кнопки "сохранить" в редакторе будет запрошен callback_url и с помощью POST переданы следующие параметры:

  • material_id - идентификатор сохраняемого материала
  • user_id - идентификатор текущего пользователя
  • session_id - уникальный идентификатор сессии редактирования
  • html_body - html сохраняемой статьи
  • download_url - URL для скачивания статического контента
  • custom_fields - JSON с дополнительными полями, переданными при открытии редактора
  • callback_sign - цифорвая подпись запроса, генерируемая по следующему алгоритму:

md5 от сконкатенированных параметров в следующем порядке: secret, session_id, user_id, material_id, download_url, где secret - ключ, выдаваемый при подключении к Verstka SaaS API

Изображения статьи доступны по адресу download_url (возвращает список) и download_url/name (возвращает файл), где name - имя файла для скачивания.

Использование собственных шрифтов

Нужно собрать CSS-файл с определенными комментариями и зашитыми в base64 шрифтами, и тогда они автоматически появятся в Верстке.

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

/* default_font_family: 'formular'; */
/* default_font_weight: 400; */
/* default_font_size: 16px; */
/* default_line_height: 24px; */

Далее, для каждого @font-face нужно прописать комментарии с названием шрифта и его начертанием

  /* font_name: 'Formular'; */
  /* font_style_name: 'Light'; */

Итоговый CSS-файл:

/* default_font_family: 'formular'; */
/* default_font_weight: 400; */
/* default_font_size: 16px; */
/* default_line_height: 24px; */

@font-face {
  /* font_name: 'Formular'; */
  /* font_style_name: 'Light'; */
   font-family: 'formular';
   src: url(data:application/font-woff2;charset=utf-8;base64,KJHGKJHGJHG) format('woff2'),
        url(data:application/font-woff;charset=utf-8;base64,KJHGKJHGJHG) format('woff');
   font-weight: 300;
   font-style: normal;
}

@font-face {
  /* font_name: 'Formular'; */
  /* font_style_name: 'Regular; */
   font-family: 'formular';
   src: url(data:application/font-woff2;charset=utf-8;base64,KJHGKJHGJHG) format('woff2'),
        url(data:application/font-woff;charset=utf-8;base64,KJHGKJHGJHG) format('woff');
   font-weight: 400;
   font-style: normal;
}

Отображение статей

Вывод HTML-кода статьи должен сопровождаться подключением скрипта:

<script type="text/javascript">
    window.onVMSAPIReady = function(api) {
        api.Article.enable({
            <options>
        });
    };
</script>
<script src="//go.verstka.io/api.js" async type="text/javascript"></script>

Параметры options

Все параметры являются необязательными

  • observe_selector – селекторы DOM-элементов, которые потенциально могут изменить положение статьи. Например, здесь указывается селектор баннера, расхлапывающегося над статьей.

Далее параметры если верстать отдельную мобильную версию невозможно:

  • display_mode – переключает между режимами отображения статьи (desktop или mobile). Default: desktop;
  • auto_mobile_detect – автоматическое определение мобильных устройств по User Agent. Default: true;
  • mobile_max_width – ширина окна браузера, при которой происходит переключение между мобильной и десктопной версией статьи;
You can’t perform that action at this time.