Содержание

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

Шаг 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

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

Подключение полифиллов

Интеграция в одностраничные приложения (single page applications)

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

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

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

Ошибки API

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

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

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

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

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

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

Шаг 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"
              }
            ]
          }
        }
        

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

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

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

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

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

Обращение к 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"
            }
          ]
        

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

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

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

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

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

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

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

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

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

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

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

1. При внесении изменений в стили, через Управление дизайн системой.

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

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

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

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

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

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

Скачайте кастомные шрифты и иконки на сервер или 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 (если у вас в аккаунте в Управлении дизайн системой один или 2 стиля) или standalone_styles (если у вас в аккаунте много стилей и общий файл — слишком большой).

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

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

<script>
window.SEPublicConfig = {
startEvent: 'DOMContentLoaded',
};
</script>

window.SEPublicConfig = {
$scrollingElement: document.querySelector(‘.scrollable-area’)
};

Подключение полифиллов

window.SEPublicConfig = {
polyfillsPath: 'https://ceditor.setka.io/editor-polyfill/polyfills.e8c14bd888ab59184715.min.js'
};

const Post = ({ html }) => {
 useEffect(() => {
   if (window.SetkaEditorPublic) window.SetkaEditorPublic.restart();
 }, [html]);
 return <div dangerouslySetInnerHTML={{ __html: html }} />;
};

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

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

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

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

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

Если вы что-то изменили в стилях на своём аккаунте и хотите увидеть эти изменения в редакторе, интегрированном в 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"]
              }
            }
            

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

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

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

• Последняя версия документации к API

• Пример интеграции на Ruby on Rails

• Основной домен для запросов, и приёма ресурсов: https://editor.setka.io

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

• С чего начать кастомную интеграцию
• Интеграция с Управлением дизайн системой
• Инициализации Setka Post Editor (JavaScript)