Skip to main content
Contact SalesFree Trial
Contact SalesFree Trial
Platform:
Language:

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.

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.

File:
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');
}