Get started with CE.SDK Engine
In this example, we will show you how to initialize the CreativeEditor SDK's headless engine on your page. The engine enables you to power your own UI and creative workflows. Whether you want to keep your current UI or design a new one from scratch, our API can do the heavy lifting for you no matter what your starting point is.
Explore a full code sample of the integration on CodeSandbox or view the code on GitHub.
Import#
By loading the modules we provide through our CDN, you can get started right away by importing the CreativeEngine module into your own code.
Using the package from NPM#
If you use a bundler like Webpack, Rollup, or Parcel to build your app and want to integrate
the CreativeEngine module using your regular workflows, add the @cesdk/engine
npm
package as a dependency to your project.
Initialization#
To initialize the CreativeEngine
, call its static init
method and pass the
configuration object. While the
configuration object is optional, you probably want to at least provide your
license
and a baseURL
.
The instance returned by the init
call has a property element
, containing
the engine's <cesdk-canvas/>
. Add this element to your page wherever you like.
By default, it will fill out its container 100% and manage the internal rendering
resolution automatically.
If you want to check if the current browser is supported to run the engine, we provide a couple of helper methods that can be used to display a warning to the user.
supportsWasm()
: As a minimal requirement for the engine, we have the support for WebAssembly. This method returns false if the current browser cannot execute any WebAssembly code.
supportsBrowser()
: This method checks for crucial technologies which are needed to run CE.SDK. This check covers our supported browsers list.
supportsVideo()
: In some use cases, you might want to use video with our editor. This method returns false if the current browser does not support video editing.Alternatively a separate method can be imported and used to check browser support.
Custom canvas#
For special use cases, you can also pass either an existing canvas element,
or an OffscreenCanvas as viaconfig.canvas
to the init
method.
The element
property of the engine instance will be undefined in this case.
Most use cases won't need this, and we strongly recommend against it, because it comes with
some challenges:
- You will have to manage the external canvas dimensions and its rendering resolution yourself. This can be tricky to get right if you want to support flexible resolutions and sizes.
- It is also possible to introduce memory leaks through the canvas rendering context. You need to make sure to remove your canvas from the DOM and remove all references to it from Javascript variables and objects after you dispose of the engine. Failing to do so will prevent the garbage collector from freeing up memory. In single-page apps with client-side navigation, this can lead to the browser running out of memory quickly, especially on mobile devices.
Use the CreativeEngine#
After these setup steps, you can use our APIs to interact with the CreativeEngine. The next couple of pages will document the methods available.
Dispose of the CreativeEngine#
Since the CreativeEngine is implemented in WebAssembly, it does not participate in
JavaScript's garbage collection.
When you don't need the instance anymore, it is important to call its dispose()
method to free up resources used by the engine.
If you mounted the provided element
to the DOM, you also need to take care of
removing it again.
import CreativeEngine, {supportsWasm,supportsVideo} from 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.11.1/index.js';// Import a node module when you work with a bundler:// import CreativeEngine from '@cesdk/engine';const config = {baseURL: 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.11.1/assets'};if (supportsWasm()// If you use video in your scene you can check if the browser supports it as well.// supportsVideo()) {CreativeEngine.init(config).then(async (engine) => {document.getElementById('root').append(engine.element);await engine.scene.loadFromURL('https://cdn.img.ly/packages/imgly/cesdk-js/latest/assets/templates/cesdk_postcard_1.scene');engine.block.findByType('//ly.img.ubq/text').forEach((id) => {engine.block.setOpacity(id, 0.5);});engine.element.remove();engine.dispose();});} else {alert('Unsupported browser detected');}