API для интеграции Setka Editor Интеграция со Style Manager (API v1, старая версия)

Интеграция со Style Manager (API v1, старая версия)

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

Прежде, чем начать интеграцию, убедитесь, что в вашем аккаунте в Style Manager, во вкладке CMS Integration заполнено поле Editor config URL. В поле указывается эндпоинт, для работы с Setka Editor на вашем домене: 

Screen_Shot_2019-01-23_at_12.37.43.png

 

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

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

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

 

Шаг 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, содержит в себе всю информацию о стилях, которые вы настраиваете в вашем личном кабинете Style Manager на editor.setka.io.
  • CSS файл ваших стилей (файл из примера ответа на GET запрос выше: https://ceditor.setka.io/company.v.1.2.3.min.css) — CSS-правила для всех стилей и сеток компании, созданных в Style Manager.
  • public.js файл (файл из примера ответа на GET запрос выше: https://ceditor.setka.io/public.v.1.2.3.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)

Обращаться за шрифтами и иконками необходимо каждый раз, когда вы добавляете их в ваши стили в Style Manager. Можно делать это при получении каждой новой версии 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. Прием обновлений стилей из 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.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"]
          }
        }
        

Ошибка возникает при неправильно сформированном запросе.

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

 

Кастомная интеграция, продолжение: