API для интеграции Setka Editor Интеграция со Style Manager

Интеграция со Style Manager

Перед началом интеграции

Прежде, чем начать интеграцию, убедитесь, что в вашем аккаунте в Style Manager (https://editor.setka.io), во вкладке CMS Integration заполнено поле эндпойнта (Editor config url) для работы с Setka Editor на вашем домене.

Editor config url - по этой ссылке вы будете получать в своей CMS актуальную версию редактора и обновления стилей, созданных в Style Manager. Так же при первой синхронизации вы получите `public_token`, необходимый для работы ряда функций редактора, например комментариев и вставки эмбедов по ссылке.

 

Screen_Shot_2019-01-23_at_12.37.43.png

Запросы к editor.setka.io нужно осуществлять с вашим лицензионным ключом (в этом документе в примерах запросов к API он обозначен как your-license-key). Лицензионный ключ можно получить на странице CMS Integration в вашем аккаунте на editor.setka.io:

 Setka_Editor_Style_Manager___create_more_beautiful_content_quickly_and_easily_2019-01-23_16-00-37_1_.png

 

Шаг 1. Начальная синхронизация. Получение файлов Setka Editor для подключения к вашей CMS

Для получения файлов редактора и стилей, сконфигурированных в вашем аккаунте на 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.js", "filetype": "js", "md5": "asdfasdfasdf" } ], "theme_files": [ { "id": 1, "url": "https://ceditor.setka.io/company.min.css", "filetype": "css", "md5": "asdfasdfasdf" }, { "id": 1, "url": "https://ceditor.setka.io/company.json", "filetype": "json", "md5": "asdfasdfasdf" } ], "content_editor_files": [ { "id": 1, "url": "https://ceditor.setka.io/editor.min.css", "filetype": "css", "md5": "asdfasdfasdf" }, { "id": 1, "url": "https://ceditor.setka.io/editor.min.js", "filetype": "js", "md5": "asdfasdfasdf" } ] }

Описание полученного набора файлов:

  • JS файл редактора (файл из примера ответа на GET запрос выше: https://ceditor.setka.io/editor.min.js) — JavaScript WYSIWYG-редактор Setka Editor.
  • CSS файл редактора (файл из примера ответа на GET запрос выше: https://ceditor.setka.io/editor.min.css) — файл стилей интерфейса редактора.
  • Конфигурационный JSON файл (файл из примера ответа на GET запрос выше: https://ceditor.setka.io/company.json) — необходим для корректного запуска инструмента редактора Setka Editor, содержит в себе всю информацию о стилях, которые вы настраиваете в вашем личном кабинете  Style Manager на editor.setka.io.
  • CSS файл ваших стилей (файл из примера ответа на GET запрос выше: https://ceditor.setka.io/company.min.css) — CSS-правила для всех стилей и сеток компании, созданных в Style Manager.
  • public.js файл (файл из примера ответа на GET запрос выше: https://ceditor.setka.io/public.js) — файл со скриптами для запуска интерактивных элементов поста (анимации и галереи).
  • Публичный ключ (public_token) — публичный идентификатор компании, используется для отправки вспомогательных запросов из редактора в Style Manager. Вы можете получить его в ответе на запрос при первичной синхронизации или же найти на странице CMS Integration. Публичный ключ необходимо передать в инициализацию редактора.

Шаг 2. Хранение и обработка файлов Setka Editor

 

Существует 2 варианта хранения и обработки ресурсов, получаемых от Setka Editor.

Вариант 1. Полученные ссылки на ресурсы хранить в базе и динамически подключать на страницы редактирования и просмотра поста. После запроса на обновление менять ссылки на новые. 

ВАЖНО - Запросы к Style Manager API за файлами не следует отправлять каждый раз при открытии страницы поста, так как файлы меняются только при изменении стилей в Style Manager или при появлении новой версии инструмента редактора. Мы рекомендуем сохранять ссылки в базе данных и обновлять их только при необходимости. При получении нового набора файлов от 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 формате в ваши стили в Style Manager)
  • иконок (если вы загружали их или подключали из библиотеки Noun Project в ваши стили в Style Manager)

2. Работа с кастомными шрифтами. Необходимо сохранить файлы шрифтов в определенной структуре, показанной на схеме ниже (чтобы папка assets, содержащая шрифты, была на одном уровне с сохраненным файлом темы):

structure.png

 

3. Работа с иконками.

3.1. Иконки необходимо скачать на ваш сервер или ваш CDN (в любой удобной вам структуре).

3.2. Заменить в конфигурационном JSON файле абсолютные пути на иконки, ссылающиеся на домен Setka Editor, на абсолютные пути на иконки на вашем домене или CDN.

Пример: нужно заменить путь https://ceditor.setka.io/clients/client-ID/css/assets/icon-ID/img/icon.svg на путь https://your-domain.com/assets/icons/icon.svg

Шаг 3. Подключение файлов Setka Editor на страницы вашего сайта

Файлы Setka Editor нужно запускать как на странице редактирования поста (чтобы заработал инструмент редактора), так и на странице просмотра поста (чтобы подключить стили Setka Editor к оформленному вами контенту).

Файлы, которые нужно подключить на странице редактирования поста:

  • JS файл редактора
  • CSS файл редактора
  • Конфигурационный JSON файл 
  • CSS файл ваших стилей 

Файлы, которые нужно подключить на странице просмотра поста:

  • public.js файл
  • CSS файл ваших стилей 

Шаг 4. Прием обновлений стилей из Style Manager и новых версий редактора

Если вы что-то изменили в ваших стилях в аккаунте на 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.js",
        "filetype": "js",
        "md5": "asdfasdfasdf"
      }
    ],
    "theme_files": [
      {
        "id": 1,
        "url": "https://ceditor.setka.io/theme.min.css",
        "filetype": "css",
      },
      {
        "id": 1,
        "url": "https://ceditor.setka.io/theme.json",
        "filetype": "json",
        "md5": "asdfasdfasdf"
      }
    ],
    "content_editor_files": [
      {
        "id": 1,
        "url": "https://ceditor.setka.io/editor.min.css",
        "filetype": "css",
        "md5": "asdfasdfasdf"
      },
      {
        "id": 1,
        "url": "https://ceditor.setka.io/editor.min.js",
        "filetype": "js",
        "md5": "asdfasdfasdf"
      }
    ]
  }
}

Полезные ссылки:

  • Получение сжатых файлов (.gz)
    Во всех вышеуказанных методах передаются ссылки на несжатые ресурсы. CDN раздает также и сжатые версии. Их можно получить, обратившись за ресурсами с указанием специального заголовка Accept-Encoding. Пример: curl -H 'Accept-Encoding: gzip' https://ceditor.setka.io/editor.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 Errors

Ошибки, которые может отдавать API Setka Editor:

1. HTTP/1.1 401 Unauthorized

{
  "error": "Not authorized!"
}

Данная ошибка возникает в случае, если вы делаете запрос с неверным лицензионным ключом (token).

2. HTTP/1.1 422 UnprocessableEntity

{
  "errors": {
    "code": ["can't be blank"],
    "name": ["can't be blank"]
  }
}

Данная ошибка возникает, если вы неправильно сформировали запрос.

В случае возникновения ошибки всегда можете обратиться в нашу службу поддержки по адресу https://editor.setka.io/support.

[неактуально для Setka Editor после 1.17.3 версии] Create snippet (From client CMS to Setka Editor API) 

POST /api/v1/custom/snippets 

{
  "token": "123456",
  "theme_id": 1,
  "snippet": {
    "name": "Snippet name",
    "code": "<html>snippet markup</html>"
  }
}

 

Что бы узнать об инициализации Editor.js, пройдите по ссылке.

 

Кастомная интеграция: