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

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

Содержание

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

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

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

Файлы массива theme_files

Файлы массива content_editor_files

Файлы массива standalone_styles

Обращение к API с дополнительными параметрами

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

Файлы массива amp_styles

Обращение к API за определенным набором файлов

Список доступных файлов

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

1. Хранение ссылок на ресурсы, динамическое подключение файлов с Setka CDN

2. Хранение ресурсов на вашем сервере или CDN

После скачивания файлов

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

На странице редактирования поста

На страницах просмотра постов

Дополнительные параметры инициализации public.js

На AMP-страницах

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

Получение сжатых файлов (.gz)

Ошибки API

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

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

 

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

Прежде, чем начать интеграцию, убедитесь, что в вашем аккаунте в 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

Для получения файлов редактора и стилей, сконфигурированных в вашем аккаунте, выполните  следующий запрос, добавив лицензионный ключ:

GET https://editor.setka.io/api/v2/integration?token=your-license-key

 

Пример ответа на запрос:


        {
          "public_token": "123456789123456789123456789",
          "plugins": [
            {
              "url": "https://ceditor.setka.io/public.v.1.2.3.js",
              "filetype": "js",
              "md5": "asdfasdfasdf"
            }
          ],
          "content_editor_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.min.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/public.v.1.2.3.json",
              "filetype": "json",
              "md5": "asdfasdfasdf"
            }
          ],
          "standalone_styles": {
            "common": [
              {
                "id": 1,
                "url": "https://ceditor.setka.io/common_css/common_css_1.css",
                "filetype": "css"
              }
            ],
            "themes": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/css/1.css",
                "filetype": "css"
              }
            ],
            "layouts": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/layout_option_builds/1/1.css",
                "filetype": "css"
              }
            ]
          }
        }
        

 

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

Файл URL Описание

public_token

 

Публичный ключ. Используется для отправки вспомогательных запросов из редактора в Style Manager. Можно получить в ответе на запрос при первичной синхронизации, либо найти на странице CMS Integration.

Ключ необходимо передать в инициализацию редактора.

plugins

https://ceditor.setka.io/public.v.1.2.3.js

Скрипты для запуска интерактивных элементов поста (анимаций и галерей).
content_editor_files

 

Массив файлов редактора.
theme_files

 

Массив файлов, необходимых для отображения постов. Содержит общий файл стилей и конфигурационный файл редактора.
standalone_styles   Массив CSS-файлов. Подключаются на страницы материалов. Описывают поведение конкретных стилей и систем сеток из Style Manager.

 

Файлы массива content_editor_files

Тип

URL

Описание

CSS

https://ceditor.setka.io/company.v.1.2.3.min.css

Стили интерфейса редактора Setka Editor.
JS

https://ceditor.setka.io/company.v.1.2.3.min.js

JS WYSIWYG-редактора Setka Editor.

 

Файлы массива theme_files

Тип

URL

Описание
CSS

https://ceditor.setka.io/company.v.1.2.3.min.css

Общий файл стилей. Описывает все стили и сетки компании, настроенные в личном кабинете.
JSON

https://ceditor.setka.io/public.v.1.2.3.json

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

 

Файлы массива standalone_styles

Для корректного отображения контента, подключите на страницу просмотра 3 CSS-файла из массива standalone_styles:

Файл

URL

Описание

common

https://ceditor.setka.io/common_css/common_css_1.css

Общие правила стилей Setka Editor
themes

https://ceditor.setka.io/clients/company/css/1.css

Стиль конкретного поста
layouts

https://ceditor.setka.io/clients/company/layout_option_builds/1/1.css

Система сеток, использованная при оформлении контента

  

Обращение к API с дополнительными параметрами

Чтобы обратиться к API за дополнительными файлами, используйте параметр options

GET https://editor.setka.io/api/v2/integration?token=your-license-key
options=amp,fonts,icons

Пример ответа на запрос:

{
          "public_token": "123456789123456789123456789",
          "plugins": [
            {
              "url": "https://ceditor.setka.io/public.v.1.2.3.js",
              "filetype": "js",
              "md5": "asdfasdfasdf"
            }
          ],
          "content_editor_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.js",
              "filetype": "js",
              "md5": "asdfasdfasdf"
            }
          ],
          "theme_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/public.v.1.2.3.json",
              "filetype": "json",
              "md5": "asdfasdfasdf"
            }
          ],
          "standalone_styles": {
            "common": [
              {
                "id": 1,
                "url": "https://ceditor.setka.io/common_css/common_css_1.css",
                "filetype": "css"
              }
            ],
            "themes": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/css/1.css",
                "filetype": "css"
              }
            ],
            "layouts": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/layout_option_builds/1/1.css",
                "filetype": "css"
              }
            ]
          },
          "amp_styles": {
            "common": [
              {
                "id": 1,
                "url": "https://ceditor.setka.io/common_css/common_css_1_amp.css",
                "filetype": "css"
              }
            ],
            "themes": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/theme_builds/1/2.css",
                "filetype": "css",
                "fonts": [
                  "https://fonts.googleapis.com/css?family=Open+Sans:400,700%7COpen+Sans+Condensed:400,400i,700&subset=cyrillic&display=swap"
                ]
              }
            ],
            "layouts": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/1/layout_option_builds/1/2.css",
                "filetype": "css"
              }
            ]
          },
          "icons": [
            {
              "id": 1,
              "url": "https://ceditor.setka.io/clients/company/css/assets/1/img/icon-name.png",
              "filetype": "image"
            }
          ],
          "fonts": [
            {
              "id": 1,
              "url": "https://ceditor.setka.io/clients/company/css/assets/fonts/1/font-name.woff",
              "filetype": "font"
            }
          ]
        

 

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

Файл URL Описание
amp_styles   Массив файлов, необходимых для отображения контента на AMP-страницах.
icons

https://ceditor.setka.io/client/company/css/assets

/1/img/icon-name.png

Иконки, загруженные в стиль. Скачивайте эти файлы, только если стиль хранится на вашем сервере. По умолчанию, иконки подключаются с Setka CDN, без дополнительных действий. Достаточно подключить файлы Общий, либо Раздельные файлы стилей.
fonts

https://ceditor.setka.io/clients/company/css/assets

/fonts/1/font-name.woff

Кастомные шрифты в формате .woff, загруженные в стиль. Скачивайте эти файлы, только если стиль хранится на вашем сервере. По умолчанию, кастомные шрифты подключаются с Setka CDN, без дополнительных действий. Достаточно подключить Общий, либо Раздельные файлы стилей.

 

Файлы массива amp_styles

Файл

URL

Описание

common

https://ceditor.setka.io/common_css/common_css_1_amp.css

Общие правила стилей AMP-страниц
themes

https://ceditor.setka.io/clients/company/theme_builds/1/2.css

Стиль конкретного поста
layouts

https://ceditor.setka.io/clients/1/layout_option_builds/1/2.css

Система сеток, использованная при оформлении контента

 

Обращение к API за определенным набором файлов

Чтобы получить по API конкретный набор файлов, добавьте в запрос параметр select. Затем перечислите файлы через запятую:

GET https://editor.setka.io/api/v2/integration?token=your-license-key
select=plugins,editor,theme,standalone,amp,fonts,icons

 

Список доступных файлов

Файл Тип Описание
plugins JS Скрипты для запуска интерактивных элементов поста.
content_editor_files JS, CSS JS и CSS файлы редактора
theme_files JSON, CSS Конфигурационный JSON файл и общий CSS файл стилей
standalone_styles CSS Раздельные файлы стилей
amp_styles CSS AMP стили
fonts WOFF Кастомные шрифты
icons PNG, SVG Иконки

 

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

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

 

1. Хранение ссылок на ресурсы, динамическое подключение файлов с Setka CDN

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

 

Важно: Не отправляйте запросы к Style Manager API при каждом открытии страницы поста. Файлы меняются только в двух случаях:

1. При внесении изменений в стили, через Style Manager.

2. При выходе новой версии редактора.

Рекомендуем сохранять ссылки в базе данных и обновлять их только при необходимости. Получив новый набор файлов от editor.setka.io, убедитесь в его валидности. Только после этого удаляйте старый файл стилей и подключайте новый.

 

2. Хранение ресурсов на вашем сервере или CDN

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

После запроса на обновление файлов (Шаг 4), скачайте новые версии и замените старые файлы.

Файлы, которые можно сохранить на ваш сервер или CDN:

Файл Описание
theme_files Конфигурационный JSON файл и общий CSS файл стилей
standalone_styles Раздельные файлы стилей (standalone styles)
amp_styles AMP стили
fonts Кастомные шрифты
icons Иконки

Скачайте кастомные шрифты и иконки на сервер или CDN, в любой удобной вам структуре.

 

После скачивания файлов:

1. В конфигурационном JSON файле: замените абсолютные ссылки к иконкам. Вместо  домена Setka Editor, они должны вести на ваш домен или CDN.

Пример:

Если ссылка ведёт на https://ceditor.setka.io/clients/client-ID/css/assets/file-ID/img/icon.svg,  замените его на https://yourdomain.com/assets/icons/icon.svg

2. В общем или раздельном CSS файле стилей: замените абсолютные ссылки к шрифтам. Вместо  домена Setka Editor, они должны вести на ваш домен или CDN.

Пример:

Если ссылка ведёт на https://ceditor.setka.io/clients/file-ID/css/assets/fonts/client-ID/font.woff, замените её на https://yourdomain.com/assets/fonts/font.woff.

 

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

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

 

На странице редактирования поста

  • content_editor_files — JS и CSS файлы редактора.
  • theme_files — Конфигурационный JSON файл и Общий CSS файл ваших стилей.

 

На страницах просмотра постов

  • plugins — Скрипты для запуска интерактивных элементов поста (анимаций и галерей).
  • theme_files  файлы стилей.
  • Общий CSS файл стилей из theme_files (если у вас в аккаунте в Style Manager один или 2 стиля) или standalone_styles (если у вас в аккаунте много стилей и общий файл — слишком большой).

 

Обратите внимание: при использовании раздельных стилей, нужно подключить на страницу 3 файла из массива standalone_styles:

  • common — общие правила стилей Setka Editor.
  • themes  стиль конкретного поста. Ориентируйтесь на ID стиля, сохранив его в метаданные материала на вашей платформе.
  • layouts  система сеток, использованная при оформлении контента. Ориентируйтесь на ID системы сеток, сохранив его в метаданные материала на вашей платформе.

 

Дополнительные параметры инициализации public.js

Выбор контейнера прокрутки страницы

Если контейнером, в котором происходит прокрутка страницы, является не window, а другой DOM-элемент, передайте в инициализацию следующий параметр:
window.SEPublicConfig = {
$scrollingElement: document.querySelector(‘.scrollable-area’)
};
Где .scrollable-area  контейнер, в котором происходит прокрутка страницы.

 

На AMP-страницах

AMP не позволяет подключать отдельные файлы стилей на страницы. Необходимо сохранить содержимое файлов и подключить его в общий файл стилей для AMP-страниц.

 

Обратите внимание: нужно сохранить содержимое 3-х файлов из массива amp_styles:

  • common  общие правила стилей AMP-страниц.
  • themes  стиль конкретного поста. Ориентируйтесь на ID стиля, сохранив его в метаданные материала на вашей платформе.
  • layouts  система сеток, использованная при оформлении контента. Ориентируйтесь на ID системы сеток, сохранив его в метаданные материала на вашей платформе.

 

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

Если вы что-то изменили в стилях на своём аккаунте и хотите увидеть эти изменения в редакторе, интегрированном в CMS, а также регулярно получать новые версии редактора  принимайте обновления файлов с editor.setka.io.

Setka Editor будет обращаться на URL, указанный в поле Editor config url (например, yourdomain.com/setka_editor_config), со следующим запросом:

POST yourdomain.com/setka_editor_config

 

Пример запроса от editor.setka.io:


        {
          "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"
            }
          ],
          "standalone_styles": {
            "common": [
              {
                "id": 1,
                "url": "https://ceditor.setka.io/common_css/common_css_1.css",
                "filetype": "css"
              }
            ],
            "themes": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/css/1.css",
                "filetype": "css"
              }
            ],
            "layouts": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/layout_option_builds/1/1.css",
                "filetype": "css"
              }
            ]
          },
          "amp_styles": {
            "common": [
              {
                "id": 1,
                "url": "https://ceditor.setka.io/common_css/common_css_1_amp.css",
                "filetype": "css"
              }
            ],
            "themes": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/company/theme_builds/1/1.css",
                "filetype": "css",
                "fonts": [
                  "https://fonts.googleapis.com/css?family=Open+Sans:400,700%7COpen+Sans+Condensed:400,400i,700&subset=cyrillic&display=swap"
                ]
              }
            ],
            "layouts": [
              {
                "id": "1",
                "url": "https://ceditor.setka.io/clients/1/layout_option_builds/1/1.css",
                "filetype": "css"
              }
            ]
          }
        }
        

Если файлы шрифтов и иконок хранятся на вашем сервере или CDN, при добавлении новых шрифтов и иконок в стили, обратитесь за ними по API самостоятельно.

 

Получение сжатых файлов (.gz)

Во всех вышеуказанных методах передаются ссылки на несжатые ресурсы. CDN раздает также и сжатые версии. Их можно получить, указав при обращении заголовок Accept-Encoding.

Пример:

curl -H 'Accept-Encoding: gzip' https://ceditor.setka.io/editor.v.1.2.3.min.js

 

Ошибки API

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

HTTP/1.1 401 Unauthorized

{
              "error": "Not authorized!"
            }
            

Ошибка возникает при использовании некорректного лицензионного ключа (token).

 

HTTP/1.1 422 Unprocessable Entity

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

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

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

 

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

 

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