example output from your editor
" } ``` The `bundleVersion` property inside the `config.cloudServices` object is required. > **Note** > > Remember that the uploaded editor bundle is only available within the environment to which it was assigned. If you use the same editor for different environments, you must upload it separately for each of them. ### Editor configuration The `bundleVersion` property set during an upload acts as a unique build identifier. It tells CKEditor Cloud Services which editor should be used when a user starts the collaboration session. You need to make sure that the editor configuration in your application also has the [`bundleVersion`](../../../../ckeditor5/latest/api/module_cloud-services_cloudservicesconfig-CloudServicesConfig.md#member-bundleVersion) property and its value matches the editor uploaded to the CKEditor Cloud Services server. An example editor configuration with set `bundleVersion` looks like this: ```js return CKEditorCS.create( { cloudServices: { tokenUrl: 'TOKEN_URL', uploadUrl: 'UPLOAD_URL', webSocketUrl: 'WEBSOCKET_URL', bundleVersion: 'editor-1.0.0' }, collaboration: { channelId: 'CHANNEL_ID' }, toolbar: [ // Toolbar items ], // Other config options } ); ``` > **Note** > > The editor configuration uploaded to the CKEditor Cloud Services server should be in `JSON` format. Therefore, in some cases, the config object needs to be modified before sending: > > * properties of particular plugins that require DOM elements should be set to `null`, > * regex values in [General HTML Support](../../../../ckeditor5/latest/features/html/general-html-support.md) configuration should be converted to strings, e.g. `"/.*/"`. ### Multi-root editor builds For [**multi-root** editor builds](../../../../ckeditor5/latest/examples/builds/multi-root-editor.md), an upload request body requires an additional `is_multi_root_editor` field set to `true`. The field indicates that the uploaded editor is a multi-root build. Additionally, the `test_data` property is expected to be a stringified JSON structure where the keys are the root names and the values are the HTML content for particular roots. Moreover, if you want to use the roots’ attributes you must provide example values for each root in the editor config. ```json { "bundle": "the content of a multi-root editor bundle file", "config": { "cloudServices": { "bundleVersion": "unique_multiroot_editor_bundle_version" }, "removePlugins": [ "myCustomAutoSavePlugin" ], "rootsAttributes": { "main": { "order": 1 } }, ... other config options }, "test_data": "{\"header\":\"Multi-root document header.
\",\"footer\":\"Multi-root document footer.
\"}", "is_multi_root_editor": true } ``` ### Example Follow this example to learn how to properly upload the editor bundle to CKEditor Cloud Services. This example is using Node.js and `npm`, hence it is required to have these tools installed. It also assumes that you have already [built the editor bundle](#building-the-editor-bundle). This example will continue using the files from the previous example. 1. In your terminal, use `cd` to get into the extracted folder and install the `axios` package with the `npm i axios` command. 2. Create a new `upload.js` file inside the extracted folder with the following content: ```js const crypto = require( 'crypto' ); const fs = require( 'fs' ); const path = require( 'path' ); const axios = require( 'axios' ); // Update with your credentials and application endpoint const environmentId = 'txQ9sTfqmXUyWU5LmDbr'; const apiSecret = '4zZBCQoPfRZ7Rr7TEnGAuRsGgbfF58Eg0PA8xcLD2kvPhjGjy4VGgB8k0hXn'; const applicationEndpoint = 'https://33333.cke-cs.com'; const apiEndpoint = `${ applicationEndpoint }/api/v5/${ environmentId }/editors/`; const editorBundle = fs.readFileSync( path.resolve( './dist/editor.bundle.js' ) ); const body = { bundle: editorBundle.toString(), config: { cloudServices: { bundleVersion: 'editor-1.0.0' // Set a unique name for the uploaded bundle }, toolbar: [ // Toolbar items ], // Other config options } }; const CSTimestamp = Date.now(); const axiosConfig = { headers: { 'X-CS-Timestamp': CSTimestamp, 'X-CS-Signature': generateSignature( apiSecret, 'POST', apiEndpoint, CSTimestamp, body ) } }; axios.post( apiEndpoint, body, axiosConfig ) .then( response => { console.log ( response.status ); } ).catch( error => { console.log( error.message ); console.log( error.response.data ); } ); function generateSignature( apiSecret, method, uri, timestamp, body ) { const url = new URL( uri ); const path = url.pathname + url.search; const hmac = crypto.createHmac( 'SHA256', apiSecret ); hmac.update( `${ method.toUpperCase() }${ path }${ timestamp }` ); if ( body ) { hmac.update( Buffer.from( JSON.stringify( body ) ) ); } return hmac.digest( 'hex' ); } ``` Run the above code with the `node upload.js` command. You should see the `201` status code in your console. You can run `node upload.js` once again to make sure that the bundle is already uploaded. In this case, you will get a 409 error with message `Editor editor-1.0.0 already exists`. ## Updating the editor bundle As shown in the example above, it is not possible to overwrite an editor bundle on the CKEditor Cloud Services server. You may, however, encounter situations where you need to rebuild your editor, for example when you add a new plugin, update CKEditor 5 version or fix a bug in your custom plugin. You should follow these steps to start using a new editor bundle: 1. Rebuild your editor with the necessary changes to the configuration or plugins. 2. Upload the new editor bundle with the `bundleVersion` value being new and unique for your environment. 3. Update the [`bundleVersion`](../../../../ckeditor5/latest/api/module_cloud-services_cloudservicesconfig-CloudServicesConfig.md#member-bundleVersion) in the editor configuration in your application to match the new value from step 2. 4. Wait for the active collaboration sessions [to be removed automatically](data.md#temporary-and-permanent-data) or remove them manually using the [`DELETE /collaborations/{document_id}`](https://help.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument_id%7D/delete) from the CKEditor Cloud Services REST API. 5. Open the document in your new editor. A collaboration session initiated with certain `bundleVersion` can be opened only by editors with the same `bundleVersion` value. Because of this you can not connect to the previously edited documents with the new editor, without reinitializing such collaboration session (steps 4 and 5). > **Note** > > To ensure data consistency you should update the editor bundle on CKEditor Cloud Services every time there is a change in your editor. This is especially important when the changes are related to the conversions or the data outputs. --- Full index of the Cloud Services documentation: [llms.txt](../../../llms.txt)