Before starting the integration, make sure that the Editor config url field is specified in your Setka Account (Integration tab), for Setka Editor to work on your domain:

Editor config url is a link on which you will receive the latest version of the editor and updates for styles, created in the Content Design System Manager (CDSM). On initial sync, you will also receive a public_token, which is required for several editor functions to work, e.g. for commenting and inserting embeds via URL.

Requests to editor.setka.io should contain your license key (hereinafter, in request samples, it is marked as your-license-key). You can get the license key on your account's CMS Integration page in your account:

1. Initial sync. Receiving Setka Editor files to connect them to your CMS

Note: an article for users of the previous API version

To get style and editor files, configured in your account, make the following request with your license key:

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

Response sample:

       {
          "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"
              }
            ]
          }
        }

Description for the received set of files:

File	URL	Description
public_token		Public key (public_token) — a public ID of the company, used to send auxiliary requests from the editor to the CDSM. You can receive it in response to initial synchronization or copy it from your CMS Integration page. The public key needs to be handled to editor initialization.
plugins	https://ceditor.setka.io /public.v.1.2.3.js	Scripts to launch interactive elements of a post (animations and galleries)
content_editor_files		An array of files for the editor
theme_files		An array of files responsible for posts display. Includes a general style file and an editor config file
standalone_styles		An array of CSS files and rules for all the styles and layout grids of a company, created in the CDSM

Array of content_editor_files

Type

URL

Description

CSS

https://ceditor.setka.io

/company.v.1.2.3.min.css

editor interface style file

https://ceditor.setka.io

/company.v.1.2.3.min.js

JavaScript of the Setka WYSIWYG Editor

Array of theme_files

Type

URL

Description

CSS

https://ceditor.setka.io

/company.v.1.2.3.min.css

Rules for all the styles and layout grids of a company, created in CDSM

JSON

https://ceditor.setka.io

/public.v.1.2.3.json

Required for a proper launch of the Setka Editor tool. Contains all the info on styles configured in CDSM

Array of standalone_styles

To have your post reflected correctly, enable 3 CSS-files from standalone_styles array of files:

File	URL	Description
common	https://ceditor.setka.io /common_css/common_css_1.css	Common rules for Setka Editor styles
themes	https://ceditor.setka.io/clients /company/css/1.css	A style for specific post
layouts	https://ceditor.setka.io/clients /company/layout_option_builds/1/1.css	Layout Grid used for your posts

API request with additional parameters

To make an API request for the additional files use an options parameter:

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

Response sample:

{
          "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"
            }
          ]

Description of a received array of files

File	URL	Description
amp_styles		An array of files needed to reflect posts correctly on AMP pages
icons	https://ceditor.setka.io/clients /company/css/assets /1/img/icon-name.png	Icons that are uploaded in your style. You should download these files only if the style is hosted on your server. Icons are downloaded via Setka CDN by default in General or Separated style files, no additional actions needed
fonts	https://ceditor.setka.io/clients /company/css/assets /fonts/1/font-name.woff	Custom .woff fonts uploaded into your styles in the CDSM. You should download these files only if the style is hosted on your server. Icons are downloaded via Setka CDN by default in General or Separated style files, no additional actions needed

amp_styles array of files

File	URL	Description
common	https://ceditor.setka.io /common_css/common_css_1_amp.css	Common rules for AMP pages styles
themes	https://ceditor.setka.io /clients/company/theme_builds/1/2.css	A style for specific post
layouts	https://ceditor.setka.io /clients/1/layout_option_builds/1/2.css	Layout Grid used for your posts

API request for specific arrays of files

To get the needed array of files add select parameter to your request, then enumerate these files separated by commas:

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

List of available files

File	Type	Description
plugins	JS	Scripts that help running interactive elements of your posts
content_editor_files	JS, CSS	JS and CSS editor files
theme_files	JSON, CSS	JSON config file and a concatenated CSS file
standalone_styles	CSS	Separate style files
amp_styles	CSS	AMP styles
fonts	WOFF	Custom fonts
icons	PNG, SVG	Icons

Step 2. Storing and processing Setka Editor files

There are 2 ways to store and process resources, received from Setka Editor.

1. Storing links to resources, dynamic linking to Setka CDN

You can receive links to resources via API and save them to your database. Dynamically link resources to editor and preview pages. Update the links once there is a request for it.

Important: do not send Content Design System Manager API requests each time you open your post. There are two cases when files can be changed:

1. When updating styles through Content Design System Manager

2. When a new version of the editor is released

We recommend saving links in a database and updating them only if it is necessary. On getting a new set of files from editor.setka.io, make sure that it is valid. Delete the old style file and connect the new one only after validation.

2. Storing resources on your server or CDN

If you want Setka Editor files to be grabbed from your server or CDN, with no dependencies on Setka CDN, you can use links to download them and put them into a public directory of the project. Then you will be able to markup paths to files on required pages.

After the file update request (Step 4) you will need to download new versions and replace old files.

Files can be saved to your server or CDN:

File	Description
theme_files	JSON config file and a concatenated CSS file
standalone_styles	Standalone styles
amp_styles	AMP styles
fonts	Custom fonts
icons	Icons

Download custom fonts and icons to your server or CDN in any structure preferable for you.

After files download:

1. JSON config file: replace absolute paths that are referred to a Setka Editor domain, with the absolute paths to icons on your domain or CDN

Example:

If the path leads to https://ceditor.setka.io/clients/client-ID/css/assets/file-ID/img/icon.svg, replace it with https://yourdomain.com/assets/icons/icon.svg

2. Replace absolute paths for fonts in a concatenated or separate CSS file with the ones that lead to your CDN instead of Setka Editor domain

Example:

If the path leads to https://ceditor.setka.io/clients/file-ID/css/assets/fonts/client-ID/font.woff, replace it with https://yourdomain.com/assets/fonts/font.woff.

Step 3. Connecting Setka Editor files to the pages of your site

Setka Editor files should be launched both on the post editing page (for the operation of the editor tool), and on the post preview page (to connect Setka Editor styles to your content).

On a post editing page:

content_editor_files — JS и CSS editor files
theme_files — JSON config file and a concatenated CSS file of your styles

On a post preview page

plugins — scripts to launch interactive post elements (animations and galleries)
theme_files — style files
concatenated CSS file for styles from theme_files (if there are 1 or 2 styles in your CDSM) and standalone_styles (if there are many styles in your account and the common style is too large)

Note: to use separate styles, there are 3 files from standalone_styles array needed:

common — common rules of Setka Editor styles
themes — a style of a specific post. Take a style ID into your account when saving it to metadata on your stack.
layouts — layout grid used for your content. Take a layout grid ID into your account when saving it to metadata on your stack.

Public.js additional initialization parameters

A choice of page scrolling container

If a page scrolling container is not a window but some other DOM-element, send the following parameter to initialization:

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

Where .scrollable-area is a container where page scrolling occurs.

Enabling polyfills

To optimize the size of public.js file, since version 2.11.21, we don't include a polyfill for ResizeObserver and Web Animations API into it by default. If visitor's browser does not support any of these APIs, public.js will automatically load the polyfill from Setka CDN before initialization.

To enable custom polyfills, pass this parameter into the initialization:

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

Where polyfillsPath is an absolute polyfill URL.

Single page applications (SPA) integration

To integrate Setka with a single page application, public.js adds window.SetkaEditorPublic into window. This object contains start, stop and restart methods. If your site loads posts dynamically, call window.SetkaEdutorPublic.restart() after inserting the post into DOM.

Sample made on React:

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

On AMP pages

AMP does not allow to connect separate style files to pages. In order to do that you need to save files' content and connect it to common files of AMP pages styles.

Note: there are 3 files from amp-styles array of files that need to be saved:

common — common rules of AMP pages styles
themes — a style of a specific post. Take a style ID into account when saving it to metadata on your stack
layouts — layout grid used for your content. Take a grid ID into account when saving it to metadata on your stack

Step 4. Receiving style updates from the Content Design System Manager and new editor versions

If you have applied any changes to your styles from your account and you want to have these changes to be reflected in the editor integrated with your CMS, as well as you would like to receive new versions of the editor on a regular basis, you need to receive updates from editor.setka.io.

Setka Editor will address a URL, specified in the Editor config url field on the CMS Integration page (e.g., yourdomain.com/setka_editor_config) with the following request:

POST yourdomain.com/setka_editor_config

A request sample from 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"
              }
            ]
          }
        }

If icons and fonts are stored on your server or CDN, you will have to make an API request for them yourself.

Receiving compressed files (.gz)

In all the above mentioned methods you receive links to uncompressed resources. You can receive compressed versions from CDN by identifying an Accept-Encoding heading in a request.

E.g.:

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

API Errors

Errors that Setka Editor API may return:

1. HTTP/1.1401Unauthorized

 {
              "error": "Not authorized!"
            }

The error occurs as a result of a request with an incorrect license key (token).

HTTP/1.1 422 Unprocessable Entity

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

The error appears as a result of an incorrect request.

You can contact our support team on any error. We will be glad to help!

Links that might be useful

Latest version of API documentation
Ruby on Rails integration example
Master domain for requests acceptance and resources recipient: https://editor.setka.io

More about custom integration: