Configure the Engine to use Assets served from your own Servers
In this example, we explain how to configure the Creative Engine to use assets hosted on your own servers. While we serve all assets from our own CDN by default, it is highly recommended to serve the assets from your own servers in a production environment.
Prerequisites#
1. Add the CreativeEngine to Your Project#
npm install --save @cesdk/engine@1.41.0
2. Decide what Assets you need#
We offer two sets of assets:
- Core Assets - Files required for the engine to function.
- Default Assets - Demo assets to quickstart your development.
⚠️ Warning#
Prior to v1.10.0
, the CreativeEngine
and CreativeEditorSDK
would load referenced default assets from the assets/extensions/*
directories and hardcode them as /extensions/…
references in serialized scenes.
To maintain compatibility for such scenes, make sure you're still serving version v1.9.2 the /extensions
directory from your baseURL
. You can download them from our CDN.
3. Register IMG.LY's default assets#
If you want to use our default asset sources in your integration, call CreativeEngine.addDefaultAssetSources({ baseURL?: string, excludeAssetSourceIds?: string[] }): void
. Right after initialization:
CreativeEngine.init(config).then((engine) => {engine.addDefaultAssetSources();});
This call adds IMG.LY's default asset sources for stickers, vectorpaths and filters to your engine instance. By default, these include the following source ids:
'ly.img.sticker'
- Various stickers.'ly.img.vectorpath'
- Shapes and arrows.'ly.img.filter.lut'
- LUT effects of various kinds.'ly.img.filter.duotone'
- Color effects of various kinds.'ly.img.colors.defaultPalette'
- Default color palette.'ly.img.effect'
- Default effects.'ly.img.blur'
- Default blurs.'ly.img.typeface'
- Default typefaces.
If you don't specify a baseURL
option, the assets are parsed and served from the IMG.LY CDN.
It's it is highly recommended to serve the assets from your own servers in a production environment, if you decide to use them.
To do so, follow the steps below and pass a baseURL
option to addDefaultAssetSources
.
If you only need a subset of the IDs above, use the excludeAssetSourceIds
option to pass a list of ignored Ids.
4. Copy Assets#
Copy the CreativeEngine core
, demo
, i18n
, ui
, etc. asset folders to your application's asset folder.
The name of the folder depends on your setup and the used bundler, but it's typically a folder called
assets
or public
in the project root.
cp -r ./node_modules/@cesdk/engine/assets public/
Furthermore, if you are using our IMG.LY default assets, download them from our CDN and extract them to your public directory as well.
If you deploy the site that embeds the CreativeEngine together with all its assets and static files, this might be all you need to do for this step.
In different setups, you might need to upload this folder to your CDN.
5. Configure the CreativeEngine to use your self-hosted assets#
Next, we need to configure the SDK to use our local assets instead of the ones served via our CDN. There are two configuration options that are relevant for this:
baseURL
should ideally point to theassets
folder that was copied in the previous step.This can be either an absolute URL, or a path. A path will be resolved using the
window.location.href
of the page where the CreativeEngine is embedded. By defaultbaseURL
is set to our CDN.core.baseURL
must point to the folder containing the core sources and data file for the CreativeEngine. Defaults to${baseURL}/core
This can be either an absolute URL, or a relative path. A relative path will be resolved using the the previous
baseURL
. By default,core.baseURL
is set tocore/
.Normally you would simply serve the assets directory from the previous step. That directory already contains the
core
folder, and this setting does not need to be changed. For highly customized setups that separate hosting of the WASM files from the hosting of other assets that are used inside scenes, you can set this to a different URL.CreativeEngine.addDefaultAssetSources
offers abaseURL
option, that needs to be set to an absolute URL.The given URL will be used to lookup the asset definitions from
{{baseURL}}/<id>/content.json
and for all file references, like{{baseURL}}/<id>/images/example.png
. By default, default sources parse and reference assets fromhttps://cdn.img.ly/assets/v3
.
const config = {...// Specify baseURL for all relative URLs.baseURL: '/assets' // or 'https://cdn.mydomain.com/assets'core: {// Specify location of core assets, required by the engine.baseURL: 'core/'},...};// Setup engine and add default sources served from your own server.CreativeEngine.init(config).then((engine) => {engine.addDefaultAssetSources({ baseURL: 'https://cdn.mydomain.com/assets'})})
Versioning of the WASM assets#
The files that the CreativeEngine loads from core.baseURL
(.wasm
and.data
files, and the worker-host.js
) are changing between different versions of the
CreativeEngine. You need to ensure that after a version update, you update your
copy of the assets.
The filenames of these assets will also change between updates. This makes it safe to store different versions of these files in the same folder during migrations, as the CreativeEngine will always locate the correct files using the unique filenames.
It also means that if you forget to copy the new assets, the CreativeEngine will fail to load them during initialization and abort with an Error message on the console. Depending on your setup this might only happen in your production or staging environments, but not during development where the assets might be served from a local server. Thus we recommend to ensure that copying of the assets is taken care of by your automated deployments and not performed manually.