Integration with Style Manager (API v1, previous version)

Integration with Style Manager (API v1, previous version)

Before you start

Before starting the integration, make sure that the Editor config url field is specified in your Style Manager account ("CMS 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 Style Manager. 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.

Screenshot of specifying the Editor config url in the Style Manager account

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

Screenshot of the CMS Integration page to get the Setka Editor licency key

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

To get style and editor files configured on editor.serka.io, make the following request with your license key:

GET https://editor.setka.io/api/v1/custom/builds/current?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"
     }
     ],
     "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"
     }
     ]
    }

Description for the received set of files:

• JS file of the editor (from the GET-request sample above: https://ceditor.setka.io/editor.v.1.2.3.min.js) — JavaScript of the Setka WYSIWYG Editor.

• Editor CSS file (from the GET-request sample above: https://ceditor.setka.io/editor.v.1.2.3.min.css) — editor interface style file.

• JSON config file (from the GET-request sample above: https://ceditor.setka.io/company.v.1.2.3.json) — required for a proper launch of the Setka Editor tool. Contains all the info on styles configured in the Style Manager.

• CSS file of your styles (from the GET-request sample above: https://ceditor.setka.io/company.v.1.2.3.min.css) — CSS rules for all the styles and grids of a company, created in the Style Manager.

• public.js file (from the GET-request sample above: https://ceditor.setka.io/public.v.1.2.3.js) — file with scripts to launch interactive elements of a post (animations and galleries).

• The public key (public_token) — a public ID of the company, used to send auxiliary requests from the editor to the Style Manager. You can receive it in response to the initial synchronization or copy it from your CMS Integration page. The public key must be handled to editor initialization.

Step 2. Storing and processing Setka Editor files

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

Option 1. Storing received links to resources in the database and dynamically including them on editor and preview pages. Change them to new ones after each update request.

Important Note: Style Manager API should not be requested for files each time the post page is opened, because files are changed only on changes in Style Manager or on a new release of the editor tool. 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 the validation.

Option 2. If you want Setka Editor files to be grabbed from your server or CDN, with no dependencies on Setka CDN, you can download the files by links 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 (see step 4) you will need to download new versions and replace old files.

If you are going to keep the data on your own supply, you will need to take several actions to get additional files and store them correctly:

1. Get additional files via API https://editor.setka.io/api/v1/wordpress/files.json?token=your-license-key:

• Custom fonts (if you have uploaded .woff fonts into your styles in the Style Manager);

• Icons (if you have uploaded them or gathered them from the Noun Project library, into your styles in the Style Manager).

You need to request fonts and styles each time you add them to the Style Manager. It can be done by getting each new CSS file version and on API requests with your license key.

2. Download files of custom fonts and icons on your server or CDN (in any structure you like).

3. Replace absolute paths in the JSON config file that are referred to Setka Editor domain, with the absolute paths to icons on your domain or CDN.

For instance: you will need to replace the https://ceditor.setka.io/clients/client-ID/css/assets/file-ID/img/icon.svg path with https://example.com/assets/icons/icon.svg

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

Setka Editor files should be launched as on the post editing page (for the operation of the editor tool), as also on the post preview page (to connect Setka Editor styles to the content you have issued).

Files to be connected on the post-editing page:

• JS file of the editor

• CSS file of the editor

• JSON config file

• CSS file of your styles.

Files to be connected on the post preview page:

• public.js file

• CSS file of your styles.

Step 4. Receiving style updates from the Style Manager and new editor versions

If you have changed something in a style on editor.setka.io, and want to see these changes in the editor of a CMS, and also receive editor updates regularly, you will need to receive updated file versions from editor.setka.io. Setka Editor will address a URL, specified in the "Editor config url" field on the CMS Integration page (e.g., test.com/setka_editor_config) with the following request:

POST test.ru/setka_editor_config

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

Useful links:

• Receiving compressed files (.gz) In all the methods mentioned above, the links to uncompressed resources are handed. CDN also distributes the compressed versions. They can be obtained by requesting resources with a special accept-encoding header. E.g: curl -H 'Accept-Encoding: gzip' https://ceditor.setka.io/editor.v.1.2.3.min.js
• The latest version of the API documentation
• Ruby on Rails integration sample
• The main domain to request and receive editor and styles: https://editor.setka.io

API Errors

Errors that Setka Editor API may give:

1. HTTP/1.1401Unauthorized

{
     "error": "Not authorized!"
    }

The error appears if you make a request with an incorrect license key (token).

2. HTTP/1.1422UnprocessableEntity

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

The error appears if you have formed an incorrect request.

You can contact our support team with any errors. We will be glad to help!

More about custom integration:

• Introduction to Custom Integration
• Integration with Style Manager
• Setka Post Editor initialization (JavaScript)