Search
Loading...
Skip to content

Class: AssetAPI

Manage asset sources and apply assets to scenes.

Asset sources provide assets like images, videos, fonts, and other media that can be applied to design blocks. This API allows registering custom asset sources, querying available assets, and applying them to scenes or specific blocks. It supports both local and remote asset sources, with extensible middleware for custom asset handling.

Event Subscriptions#

Subscribe to asset source changes and lifecycle events.

onAssetSourceAdded()#


Subscribe to asset source addition events.

engine.asset.onAssetSourceAdded((sourceID) => {
console.log(`Added source: ${sourceID}`);
});

Parameters#

ParameterTypeDescription
callback(sourceID) => voidThe function called whenever an asset source is added.

Returns#

A method to unsubscribe from the event.

(): void;
Returns#

void

Signature#

onAssetSourceAdded(callback: (sourceID: string) => void): () => void

onAssetSourceRemoved()#


Subscribe to asset source removal events.

engine.asset.onAssetSourceRemoved((sourceID) => {
console.log(`Removed source: ${sourceID}`);
});

Parameters#

ParameterTypeDescription
callback(sourceID) => voidThe function called whenever an asset source is removed.

Returns#

A method to unsubscribe from the event.

(): void;
Returns#

void

Signature#

onAssetSourceRemoved(callback: (sourceID: string) => void): () => void

onAssetSourceUpdated()#


Subscribe to asset source content change events.

engine.asset.onAssetSourceUpdated((sourceID) => {
console.log(`Updated source: ${sourceID}`);
});

Parameters#

ParameterTypeDescription
callback(sourceID) => voidThe function called whenever an asset source’s contents are updated.

Returns#

A method to unsubscribe from the event.

(): void;
Returns#

void

Signature#

onAssetSourceUpdated(callback: (sourceID: string) => void): () => void

Asset Source Management#

Register, remove, and query asset sources for different types of media.

addSource()#


Add a custom asset source with unique ID.

The asset source provides methods for finding assets, applying them to scenes or blocks, and managing asset lifecycle. All source operations are handled asynchronously.

engine.asset.addSource({
id: 'foobar',
async findAssets(queryData) {
return Promise.resolve({
assets: [
{
id: 'logo',
meta: {
uri: 'https://img.ly/static/ubq_samples/imgly_logo.jpg',
}
}
],
total: 1,
currentPage: queryData.page,
nextPage: undefined
});
},
});

Parameters#

ParameterTypeDescription
sourceAssetSourceThe asset source configuration.

Returns#

void

Signature#

addSource(source: AssetSource): void

addLocalSource()#


Add a local asset source.

Local asset sources allow dynamic asset management through the add/remove methods. You can specify supported MIME types to restrict what assets can be added.

engine.asset.addLocalSource('local-source');

Parameters#

ParameterTypeDescription
idstringUnique identifier for the asset source.
supportedMimeTypes?string[]The mime types of assets that are allowed to be added to this local source.
applyAsset?(asset) => Promise<undefinednumber>
applyAssetToBlock?(asset, block) => Promise<void>An optional callback that can be used to override the default behavior of applying an asset result to a given block.

Returns#

void

Signature#

addLocalSource(id: string, supportedMimeTypes?: string[], applyAsset?: (asset: CompleteAssetResult) => Promise<undefined | number>, applyAssetToBlock?: (asset: CompleteAssetResult, block: number) => Promise<void>): void

removeSource()#


Remove a registered asset source.

This permanently removes the asset source and all its associated assets. Any ongoing operations with this source will be cancelled.

engine.asset.removeSource('asset-source-id');

Parameters#

ParameterTypeDescription
idstringThe ID of the asset source to remove.

Returns#

void

Signature#

removeSource(id: string): void

findAllSources()#


Get all registered asset source IDs.

engine.asset.findAllSources();

Returns#

string[]

A list with the IDs of all registered asset sources.

Signature#

findAllSources(): string[]

Asset Discovery#

Search and filter assets from registered sources with advanced query options.

findAssets()#


Search for assets in a specific source with advanced filtering.

Supports pagination, text search, tag filtering, grouping, and sorting options. Results include asset metadata, thumbnails, and application context.

const result = await engine.asset.findAssets('asset-source-id', {
page: 0,
perPage: 100
});
const asset = result.assets[0];

Parameters#

ParameterTypeDescription
sourceIdstringThe ID of the asset source.
queryAssetQueryDataQuery options to filter and sort the search results.

Returns#

Promise<AssetsQueryResult<CompleteAssetResult>>

Promise resolving to paginated search results.

Signature#

findAssets(sourceId: string, query: AssetQueryData): Promise<AssetsQueryResult<CompleteAssetResult>>

Asset Information#

Retrieve metadata, credits, licenses, and supported formats from asset sources.

getGroups()#


Get available asset groups from a source.

Groups provide categorization for assets within a source, enabling filtered discovery.

const groups = engine.asset.getGroups(customSource.id);

Parameters#

ParameterTypeDescription
idstringThe ID of the asset source.

Returns#

Promise<string[]>

Promise resolving to list of available group names.

Signature#

getGroups(id: string): Promise<string[]>

getSupportedMimeTypes()#


Get supported MIME types for an asset source.

Returns the file types that can be added to this source. An empty result means all MIME types are supported.

const mimeTypes = engine.asset.getSupportedMimeTypes('asset-source-id');

Parameters#

ParameterTypeDescription
sourceIdstringThe ID of the asset source.

Returns#

string[]

Array of supported MIME type strings.

Signature#

getSupportedMimeTypes(sourceId: string): string[]

getCredits()#


Get attribution credits for an asset source.

const credits = engine.asset.getCredits('asset-source-id');

Parameters#

ParameterTypeDescription
sourceIdstringThe ID of the asset source.

Returns#

| undefined | { name: string; url: undefined | string; }

The asset source’s credits info consisting of a name and an optional URL.

Signature#

getCredits(sourceId: string): undefined | object

getLicense()#


Get license information for an asset source.

const license = engine.asset.getLicense('asset-source-id');

Parameters#

ParameterTypeDescription
sourceIdstringThe ID of the asset source.

Returns#

| undefined | { name: string; url: undefined | string; }

The asset source’s license info consisting of a name and an optional URL.

Signature#

getLicense(sourceId: string): undefined | object

canManageAssets()#


Check if an asset source supports asset management.

Returns true if the source allows adding and removing assets dynamically, via ‘Add File’ and ‘Delete’ button on the UI. This is typically true for local asset sources and false for remote sources.

engine.asset.canManageAssets('asset-source-id');

Parameters#

ParameterTypeDescription
sourceIdstringThe ID of the asset source to check.

Returns#

boolean

True if the source supports asset management operations.

Signature#

canManageAssets(sourceId: string): boolean

Asset Application#

Apply assets to scenes, blocks, or specific properties with customizable behavior.

apply()#


Apply an asset to the active scene.

Creates a new block configured according to the asset’s properties and adds it to the scene. The behavior can be customized by providing an applyAsset function when registering the asset source.

await engine.asset.apply('asset-source-id', assetResult.assets[0]);

Parameters#

ParameterTypeDescription
sourceIdstringThe ID of the asset source.
assetResultAssetResultA single asset result from a findAssets query.

Returns#

Promise<undefined | number>

Promise resolving to the created block ID, or undefined if no block was created.

Signature#

apply(sourceId: string, assetResult: AssetResult): Promise<undefined | number>

applyToBlock()#


Apply an asset to a specific block.

Modifies the target block’s properties according to the asset’s configuration. The behavior can be customized by providing an applyAssetToBlock function when registering the asset source.

await engine.asset.applyToBlock('asset-source-id', assetResult.assets[0]);

Parameters#

ParameterTypeDescription
sourceIdstringThe ID of the asset source.
assetResultAssetResultA single asset result from a findAssets query.
blocknumberThe block to apply the asset to.

Returns#

Promise<void>

Signature#

applyToBlock(sourceId: string, assetResult: AssetResult, block: number): Promise<void>

applyProperty()#


Apply a specific asset property to the currently selected element.

Allows applying individual properties (like colors, fonts, or effects) from an asset without creating a new block. The behavior can be customized by providing an applyAssetProperty function.

const asset = assetResult.assets[0];
if (asset.payload && asset.payload.properties) {
for (const property of asset.payload.properties) {
await engine.asset.applyProperty('asset-source-id', asset, property);
}
}

Parameters#

ParameterTypeDescription
sourceIdstringThe ID of the asset source.
assetResultAssetResultA single asset result from a findAssets query.
propertyAssetPropertyThe specific asset property to apply.

Returns#

Promise<void>

Signature#

applyProperty(sourceId: string, assetResult: AssetResult, property: AssetProperty): Promise<void>

defaultApplyAsset()#


Apply an asset using the engine’s default implementation.

The default implementation already handles various different kinds of assets and acts as a good starting point.

engine.asset.addSource({
id: 'foobar',
async findAssets(queryData) {
return Promise.resolve({
assets: [
{
id: 'logo',
meta: {
uri: 'https://img.ly/static/ubq_samples/imgly_logo.jpg',
}
}
],
total: 1,
currentPage: queryData.page,
nextPage: undefined
});
},
async applyAsset(assetResult) {
return engine.asset.defaultApplyAsset(assetResult);
},
});

Parameters#

ParameterTypeDescription
assetResultAssetResultA single asset result from a findAssets query.

Returns#

Promise<undefined | number>

Promise resolving to the created block ID, or undefined if no block was created.

Signature#

defaultApplyAsset(assetResult: AssetResult): Promise<undefined | number>

defaultApplyAssetToBlock()#


Apply an asset to a block using the engine’s default implementation.

The default implementation already handles various different kinds of assets and acts as a good starting point.

engine.asset.addSource({
id: 'foobar',
async findAssets(queryData) {
return Promise.resolve({
assets: [
{
id: 'logo',
meta: {
uri: 'https://img.ly/static/ubq_samples/imgly_logo.jpg',
}
}
],
total: 1,
currentPage: queryData.page,
nextPage: undefined
});
},
async applyAssetToBlock(assetResult, block) {
engine.asset.defaultApplyAssetToBlock(assetResult, block);
},
});

Parameters#

ParameterTypeDescription
assetResultAssetResultA single asset result from a findAssets query.
blocknumberThe block to apply the asset to.

Returns#

Promise<void>

Signature#

defaultApplyAssetToBlock(assetResult: AssetResult, block: number): Promise<void>

Asset Lifecycle#

Add, remove, and manage assets within local asset sources.

addAssetToSource()#


Add an asset to a local asset source.

Only works with local asset sources that support asset management. The asset will be validated against the source’s supported MIME types.

engine.asset.addAssetToSource('local-source', {
id: 'asset-id',
label: {
en: 'My Asset'
},
meta: {
uri: 'https://example.com/asset.jpg',
mimeType: 'image/jpeg'
}
});

Parameters#

ParameterTypeDescription
sourceIdstringThe local asset source ID that the asset should be added to.
assetAssetDefinitionThe asset definition to add to the source.

Returns#

void

Signature#

addAssetToSource(sourceId: string, asset: AssetDefinition): void

removeAssetFromSource()#


Remove an asset from a local asset source.

Only works with local asset sources that support asset management. The asset will be permanently deleted from the source.

engine.asset.removeAssetFromSource('local-source', 'asset-id');

Parameters#

ParameterTypeDescription
sourceIdstringThe id of the local asset source that currently contains the asset.
assetIdstringThe id of the asset to be removed.

Returns#

void

Signature#

removeAssetFromSource(sourceId: string, assetId: string): void

assetSourceContentsChanged()#


Notify the engine that an asset source’s contents have changed.

This triggers refresh of any UI components that display assets from this source and notifies subscribers to the asset source update events.

engine.asset.assetSourceContentsChanged('asset-source-id');

Parameters#

ParameterTypeDescription
sourceIDstringThe asset source whose contents changed.

Returns#

void

Signature#

assetSourceContentsChanged(sourceID: string): void

Experimental Features#

Experimental middleware system for custom asset processing workflows.

unstable_registerApplyAssetMiddleware()#

Register middleware that intercepts asset application to scenes.

The middleware function receives the source ID, asset result, and the original apply function. It can perform custom logic before, after, or instead of the default asset application.

Parameters#

ParameterTypeDescription
middleware(sourceId, assetResult, apply) => Promise<undefinednumber>

Returns#

VoidFunction

A function that can be used to remove the middleware. This API is experimental and may change or be removed in future versions.

Example#

engine.asset.unstable_registerApplyAssetMiddleware(async (sourceId, assetResult, apply) => {
// do something before applying the asset
// You still have the choice to call apply or skip it
const blockId = await apply(sourceId, assetResult);
// do something after applying the asset
return blockId;
})

unstable_registerApplyAssetToBlockMiddleware()#

Register middleware that intercepts asset application to specific blocks.

The middleware function receives the source ID, asset result, target block, and the original apply function. It can perform custom logic before, after, or instead of the default block asset application.

Parameters#

ParameterTypeDescription
middleware(sourceId, assetResult, block, applyToBlock) => Promise<void>The middleware function that is called before applying the asset.

Returns#

VoidFunction

A function that can be used to remove the middleware. This API is experimental and may change or be removed in future versions.

Example#

engine.asset.unstable_registerApplyAssetToBlockMiddleware(async (sourceId, assetResult, block, applyToBlock) => {
// do something before applying the asset
// You still have the choice to call applyToBlock or skip it
await applyToBlock(sourceId, assetResult, block);
// do something after applying the asset
})