Migrating to v1.13

Version v1.13, the way the CreativeEngine and CreativeEditor SDK are configured has changed. Several configuration options that were previously passed to CreativeEngine.init() or CreativeEditor SDK.init() have been removed or replaced. This document will explain the changes and describe the steps you can take to adapt them to your setup.

CreativeEditorSDK initialization#

We are also introducing a new way of instantiating the CreativeEditorSDK, that provides more precise control over the initialization. Using CreativeEditorSDK.create(), you have the chance to configure the SDK before loading or creating a scene. This was not possible before. When using CreativeEditorSDK.init(), the SDK would create the initial scene before giving you the option to perform additional configuration via the API.

The create() method will not create an initial scene for you. You need to do that yourself, using either the Scene API at cesdk.editor.scene, or one of the methods on the CreativeEditorSDK instance itself (createDesignScene, createVideoScene, loadFromUrl, loadFromString).

Rationale#

Over time the number options you could pass into the call to CreativeEngine.init({...config}) has grown quite a bit. Initially this was the only place where you could configure the behavior and settings of the CreativeEngine, but over the past year we introduced several new APIs. One of those APIs is the EditorAPI, which lets you adjust many settings at runtime, not just at the launch of the app.

To improve consistency of our APIs, we decided to scale back the options available in the configuration object in favor of changing settings via the EditorAPI. The only options that remain are those that are strictly necessary for the initialization of the CreativeEngine, such as the baseUrl and license.

These changes were performed with the Creative Engine in mind, but since the CreativeEditor SDK shares a lot of the same code, the changes described in this document also apply to the configuration for the CE.SDK.

Changed configuration options#

The following is a list of all configuration options that have been changed or removed, along with instructions on how to migrate the use of these options in your codebase:

• scene options (dpi, pixelScaleFactor) have been removed. scene/dpi and scene/pixelScaleFactor can now be found as properties on the scene in the BlockAPI.
• page options have been removed.
  • page.title.show has been replaced with cesdk.engine.editor.setSettingBool('page/title/show', enabled)
  • page.title.fontFileUri has been replaced with cesdk.engine.editor.setSettingString('page/title/fontFileUri', uri)
  • page.dimOutOfPageAreas has been replaced with cesdk.engine.editor.setSettingBool('page/dimOutOfPageAreas', dimEnabled)
• assetSources have been removed. To add asset sources, use the AssetAPI at cesdk.engine.asset.
• preset.colors has been removed as it was never used, previously.
• presets.colorPalettes has been removed from CreativeEngine as it was not used. It has been moved to ui.colorPalette in the CESDK.
• presets.images has been removed. To add assets and asset sources, use the AssetAPI at cesdk.engine.asset.
• presets.pageFormats has been removed from the CreativeEngine as it was not used. Is has been moved to ui.pageFormats in the CESDK. Previously it was possible to mark a page format as default by setting meta: {default: true} in it. In ui.pageFormats, this has been simplified, to just default: true.
• variables has been removed. Use the VariableAPI instead.
• callbacks.log has been moved to logger. Previously the logger callback would take a Loglevel enum as a second parameter. This enum has been removed. Instead you can define the loglevel with plain strings 'Warning' | 'Error' | 'Info'

Change initialization code#

To ensure your users perceive a consistent UI experience, settings that have been moved to api calls should be made immediately after initializing the CreativeEngine. For the Creative Editor SDK, use the create() method, instead of init()

const engine = await CreativeEngine.init(config);
// 1. Configure Engine
engine.editor.setSettingEnum('doubleClickSelectionMode', 'Direct');
// ... other settings

// 2. Create/load scene
const sceneId = await engine.scene.create();

// 3. Append Engine canvas element to the DOM
document.getElementById('my-engine-container').append(engine.element);

// ... your application code

Fallback and warnings#

The CreativeEngine and CreativeEditor SDK still interpret the config object with its previous settings. If removed configuration options are detected during intialization, a warning is printed to the console, with individual instructions on how to migrate them. It is recommended to adjust your configuration as described above for the best compatibility with future developments and to get rid of these warnings.

The fallback mechanism is not enabled for the new CreativeEditorSDK.create() method! Passing removed configuration options to create() will cause that option to be ignored and an error will be printed to the console.

CreativeEngine Typescript definitions#

The more complex parts of our configuration (such as the page format definitions) were previously exporting type definitions under the ConfigTypes namespace in the CreativeEngine package. This namespace and all the types in it have been removed or moved elsewhere.

For now we still export ConfigTypes, but have marked it and its members as @deprecated. Most of them are not used at all anymore, the rest have been moved elsewhere:

• ConfigTypes.Color can now be imported directly as PaletteColor
• ConfigTypes.TypefaceDefinition can be imported directly, as TypefaceDefinition.
• ConfigTypes.PageFormatDefinition can be imported directly as PageFormatDefinition (CE.SDK only).
• ConfigTypes.Logger can be imported directly as Logger

The LogLevel enum that was previously used by Logger has been replaced with a string union ('Warning' | 'Error' | 'Info').

CreativeEditorSDK Typescript definitions#

The CreativeEditor SDK package still does export a ConfigTypes namespace.

For use with the new CreativeEditorSDK.create(), we are offering a new type CreateConfiguration, which is lacking all of the removed keys instead of marking them as deprecated.

Demo asset sources#

When adding demo asset sources using cesdk.addDemoAssetSources(), or engine.addDemoAssetSources(), make sure to specify the correct scene mode. The installed demo asset sources vary between Design and Video modes.

If you don't specify a scene mode, addDemoAssetSources() will try to add the correct sources based on the current scene, and default to 'Design'. If you call addDemoAssetSources() without a scene mode, and before loading or creating a video scene, the audio and video asset sources will not be added.

const engine = await CreativeEngine.init(config);
await engine.addDemoAssetSources({ sceneMode: 'Video' });
const sceneId = await engine.scene.createVideo();
// ... your application code