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#

Parameter	Type	Description
`callback`	(`sourceID`) => `void`	The 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#

Parameter	Type	Description
`callback`	(`sourceID`) => `void`	The 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#

Parameter	Type	Description
`callback`	(`sourceID`) => `void`	The 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#

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#

Parameter	Type	Description
`source`	`AssetSource`	The 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#

Parameter	Type	Description
`id`	`string`	Unique 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`<`undefined`	`number`>
`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#

Parameter	Type	Description
`id`	`string`	The 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#

Parameter	Type	Description
`sourceId`	`string`	The ID of the asset source.
`query`	`AssetQueryData`	Query 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#

Parameter	Type	Description
`id`	`string`	The 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#

Parameter	Type	Description
`sourceId`	`string`	The 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#

Parameter	Type	Description
`sourceId`	`string`	The 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#

Parameter	Type	Description
`sourceId`	`string`	The 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#

Parameter	Type	Description
`sourceId`	`string`	The 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#

Parameter	Type	Description
`sourceId`	`string`	The ID of the asset source.
`assetResult`	`AssetResult`	A 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#

Parameter	Type	Description
`sourceId`	`string`	The ID of the asset source.
`assetResult`	`AssetResult`	A single asset result from a `findAssets` query.
`block`	`number`	The 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#

Parameter	Type	Description
`sourceId`	`string`	The ID of the asset source.
`assetResult`	`AssetResult`	A single asset result from a `findAssets` query.
`property`	`AssetProperty`	The 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#

Parameter	Type	Description
`assetResult`	`AssetResult`	A 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#

Parameter	Type	Description
`assetResult`	`AssetResult`	A single asset result from a `findAssets` query.
`block`	`number`	The 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#

Parameter	Type	Description
`sourceId`	`string`	The local asset source ID that the asset should be added to.
`asset`	`AssetDefinition`	The 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#

Parameter	Type	Description
`sourceId`	`string`	The id of the local asset source that currently contains the asset.
`assetId`	`string`	The 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#

Parameter	Type	Description
`sourceID`	`string`	The asset source whose contents changed.

Returns#

void

Signature#

assetSourceContentsChanged(sourceID: string): void

Experimental Features#

Experimental middleware system for custom asset processing workflows.

unstable_registerApplyAssetMiddleware()#

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#

Parameter	Type	Description
`middleware`	(`sourceId`, `assetResult`, `apply`) => `Promise`<`undefined`	`number`>

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()#

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#

Parameter	Type	Description
`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
})