API для интеграции Setka Editor Интеграция с Управлением дизайн системой (API v1, старая версия)

Интеграция с Управлением дизайн системой (API v1, старая версия)

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

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

Screen_Shot_2019-01-23_at_12.37.43.png

По указанной ссылке вы будете получать актуальную версию редактора и обновления стилей из Управления дизайн системой. Также, при первой синхронизации, вы получите `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, содержит в себе всю информацию о стилях, которые вы настраиваете в вашем личном кабинете Управления дизайн системой на 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)