Перед началом интеграции
Прежде, чем начать интеграцию, убедитесь, что в вашем аккаунте в Управление дизайн системой, во вкладке CMS Integration заполнено поле Editor config URL. В поле указывается эндпоинт, для работы с Setka Editor на вашем домене:
По указанной ссылке вы будете получать актуальную версию редактора и обновления стилей из Управления дизайн системой. Также, при первой синхронизации, вы получите `public_token`, необходимый для работы ряда функций редактора. Например, комментариев и вставки эмбедов по ссылке.
Запросы к editor.setka.io осуществляются с вашим лицензионным ключом (в этом документе в примерах запросов, он обозначен как your-license-key). Лицензионный ключ можно получить на странице CMS Integration в вашем аккаунте:
Шаг 1. Начальная синхронизация. Получение файлов Setka Editor для подключения к вашей CMS
Важно: если вы производите интеграцию с нуля, настоятельно рекомендуем пользоваться новой версией API.
Для получения файлов редактора и стилей, сконфигурированных в вашем аккаунте на editor.setka.io, необходимо выполнить следующий запрос c вашим лицензионным ключом:
GET https://editor.setka.io/api/v1/custom/builds/current?token=your-license-key
Пример ответа на запрос:
{
"public_token": "123456789123456789123456789",
"plugins": [
{
"url": "https://ceditor.setka.io/public.v.1.2.3.js",
"filetype": "js",
"md5": "asdfasdfasdf"
}
],
"theme_files": [
{
"id": 1,
"url": "https://ceditor.setka.io/company.v.1.2.3.min.css",
"filetype": "css",
"md5": "asdfasdfasdf"
},
{
"id": 1,
"url": "https://ceditor.setka.io/company.v.1.2.3.json",
"filetype": "json",
"md5": "asdfasdfasdf"
}
],
"content_editor_files": [
{
"id": 1,
"url": "https://ceditor.setka.io/editor.v.1.2.3.min.css",
"filetype": "css",
"md5": "asdfasdfasdf"
},
{
"id": 1,
"url": "https://ceditor.setka.io/editor.v.1.2.3.min.js",
"filetype": "js",
"md5": "asdfasdfasdf"
}
]
}
Описание полученного набора файлов:
- JS файл редактора (файл из примера ответа на GET запрос выше:
https://ceditor.setka.io/editor.v.1.2.3.min.js
) — JavaScript WYSIWYG-редактор Setka Editor. - CSS файл редактора (файл из примера ответа на GET запрос выше:
https://ceditor.setka.io/editor.v.1.2.3.min.css
) — файл стилей интерфейса редактора. - Конфигурационный JSON файл (файл из примера ответа на GET запрос выше:
https://ceditor.setka.io/company.v.1.2.3.json
) — необходим для корректного запуска инструмента редактора Setka Editor, содержит в себе всю информацию о стилях, которые вы настраиваете в вашем личном кабинете Управления дизайн системой на editor.setka.io. - CSS файл ваших стилей (файл из примера ответа на GET запрос выше:
https://ceditor.setka.io/company.v.1.2.3.min.css
) — CSS-правила для всех стилей и сеток компании, созданных в Управлении дизайн системой. - public.js файл (файл из примера ответа на GET запрос выше:
https://ceditor.setka.io/public.v.1.2.3.js
) — файл со скриптами для запуска интерактивных элементов поста (анимации и галереи). - Публичный ключ (public_token) — публичный идентификатор компании, используется для отправки вспомогательных запросов из редактора в Управлении дизайн системой. Вы можете получить его в ответе на запрос при первичной синхронизации или же найти на странице CMS Integration. Публичный ключ необходимо передать в инициализацию редактора.
Шаг 2. Хранение и обработка файлов Setka Editor
Существует 2 варианта хранения и обработки ресурсов, получаемых от Setka Editor.
Вариант 1. Полученные ссылки на ресурсы хранить в базе и динамически подключать на страницы редактирования и просмотра поста. После запроса на обновление менять ссылки на новые.
ВАЖНО - Запросы к Управлениию дизайн системой API за файлами не следует отправлять каждый раз при открытии страницы поста, так как файлы меняются только при изменении стилей в Управлении дизайн системой или при появлении новой версии инструмента редактора. Мы рекомендуем сохранять ссылки в базе данных и обновлять их только при необходимости. При получении нового набора файлов от editor.setka.io, убедитесь, что он валидный, только после этого следует удалять старый файл стилей и подключать новый.
Вариант 2. Если вы хотите, чтобы файлы Setka Editor подключались не с CDN Setka Editor, с вашего сервера или CDN, вы можете скачать файлы по ссылкам и положить в публичную директорию проекта. Затем вы сможете статически прописать путь до файлов на нужных страницах. После запроса на обновление файлов (см. Шаг 4) нужно будет скачать новые версии и заменить старые файлы.
Если вы выбираете вариант с хранением файлов на вашем ресурсе, вам нужно провести еще ряд действий для получения дополнительных файлов и корректного их сохранения.
1. Дополнительно получить по API https://editor.setka.io/api/v1/wordpress/files.json?token=your-license-key следующие файлы:
- кастомных шрифтов (если вы загружали шрифты в .woff формате в ваши стили в Управлении дизайн системой)
- иконок (если вы загружали их или подключали из библиотеки Noun Project в ваши стили в Управлении дизайн системой)
Обращаться за шрифтами и иконками необходимо каждый раз, когда вы добавляете их в ваши стили в Управлении дизайн системой. Можно делать это при получении каждой новой версии CSS файла стилей и при обращении к API с вашим лицензионным ключом.
2. Файлы кастомных шрифтов и иконок необходимо скачать на ваш сервер или ваш CDN (в любой удобной вам структуре).
3. Заменить в конфигурационном JSON файле абсолютные пути на иконки, ссылающиеся на домен Setka Editor, на абсолютные пути на иконки на вашем домене или CDN.
Пример: нужно заменить путь https://ceditor.setka.io/clients/client-ID/css/assets/file-ID/img/icon.svg на путь https://example.com/assets/icons/icon.svg
4. Заменить в CSS файле стилей абсолютные пути на шрифты, ссылающиеся на домен Setka Editor, на абсолютные пути на шрифты на вашем домене или CDN.
Пример: нужно заменить путь https://ceditor.setka.io/clients/file-ID/css/assets/fonts/client-ID/font.woff на путь https://example.com/assets/fonts/font.woff
Шаг 3. Подключение файлов Setka Editor на страницы вашего сайта
Файлы Setka Editor нужно запускать как на странице редактирования поста (чтобы заработал инструмент редактора), так и на странице просмотра поста (чтобы подключить стили Setka Editor к оформленному вами контенту).
Файлы, которые нужно подключить на странице редактирования поста:
- JS файл редактора
- CSS файл редактора
- Конфигурационный JSON файл
- CSS файл ваших стилей
Файлы, которые нужно подключить на странице просмотра поста:
- public.js файл
- CSS файл ваших стилей
Шаг 4. Прием обновлений стилей из Управления дизайн системой и новых версий редактора
Если вы что-то изменили в ваших стилях в аккаунте на editor.setka.io и хотите увидеть эти изменения в вашей CMS в редакторе, а также регулярно получать новые версии редактора, вам нужно принимать обновленные версии файлов с editor.setka.io. Setka Editor будет обращаться на URL, указанный вами в поле Editor config url (например, test.ru/setka_editor_config) со следующим запросом:
POST test.ru/setka_editor_config;
;
Пример запроса от editor.setka.io:
{
"token": "123456",
"data": {
"plugins": [
{
"url": "https://ceditor.setka.io/public.v.1.2.3.js",
"filetype": "js",
"md5": "asdfasdfasdf"
}
],
"theme_files": [
{
"id": 1,
"url": "https://ceditor.setka.io/theme.v.1.2.3.min.css",
"filetype": "css",
},
{
"id": 1,
"url": "https://ceditor.setka.io/theme.v.1.2.3.json",
"filetype": "json",
"md5": "asdfasdfasdf"
}
],
"content_editor_files": [
{
"id": 1,
"url": "https://ceditor.setka.io/editor.v.1.2.3.min.css",
"filetype": "css",
"md5": "asdfasdfasdf"
},
{
"id": 1,
"url": "https://ceditor.setka.io/editor.v.1.2.3.min.js",
"filetype": "js",
"md5": "asdfasdfasdf"
}
]
}
}
Полезные ссылки:
- Получение сжатых файлов (.gz)
Во всех вышеуказанных методах передаются ссылки на несжатые ресурсы. CDN раздает также и сжатые версии. Их можно получить, обратившись за ресурсами с указанием специального заголовка Accept-Encoding. Пример: curl -H 'Accept-Encoding: gzip' https://ceditor.setka.io/editor.v.1.2.3.min.js -
Последняя версия документации по API находится по адресу https://editor.setka.io/docs/api2/index.html
-
Пример интеграции на Ruby on Rails: https://github.com/setkaio/grid-editor-integration
-
Основной домен, на который необходимо обращаться с запросом, и с которого вам будут приходить файлы редактора и стилей: https://editor.setka.io
Ошибки API
Ошибки, которые может отдавать API Setka Editor:
1. HTTP/1.1 401 Unauthorized
{
"error": "Not authorized!"
}
Ошибка возникает при использовании некорректного лицензионного ключа (token).
2. HTTP/1.1 422 Unprocessable Entity
{
"errors": {
"code": ["can't be blank"],
"name": ["can't be blank"]
}
}
Ошибка возникает при неправильно сформированном запросе.
Вы всегда можете обратиться в нашу службу поддержки, если столкнулись с ошибкой.
Кастомная интеграция, продолжение:
- С чего начать кастомную интеграцию
- Интеграция со Управлением дизайн системой
- Инициализации Setka Post Editor (JavaScript)