Common Asset API Reference

Contains functions to load predefined Common Asset groups at mobile runtime.

note

Common Asset API only runs on TikTok phone preview instead of the Effect House preview.

Common Asset List

See the Common Assets for more details.

CommonAssetController

Loads predefined Common Asset groups at mobile runtime.

Type	Name	Description
Static Functions	loadAssets(info: CommonAssetControllerRequestInfo, onLoadFinished: () => void): void	Starts a one-time download of the requested remote asset groups Call once from onStart and read results in onLoadFinished Parameters: info: The remote asset groups to request onLoadFinished: Called once after the load settles
Static Functions	getAssetGroup(groupKey: string): CommonAssetItem[] \| undefined	Returns the assets that succeeded for a group after onLoadFinished Returns undefined if the group is missing or empty Parameters: groupKey: The asset group to read Returns: The succeeded items, or undefined
Static Functions	getAsset(groupKey: string, assetKey: string): CommonAssetItem \| null	Returns one asset that succeeded, or null if it is missing or failed to load Parameters: groupKey: The group that contains the asset assetKey: The asset to read Returns: The asset, or null

loadAssets(info: CommonAssetControllerRequestInfo, onLoadFinished: () => void): void

APJS.CommonAssetController.loadAssets(
  {
    remoteAssetGroupInfos: [
      { groupKey: 'countries', explicitAssetKeys: ['uk', 'usa'] },
      { groupKey: 'food', explicitAssetKeys: ['pizza'], randomAssetCount: 3 },
    ],
  },
  () => {
    // Read assets only inside this callback.
  }
);

getAssetGroup(groupKey: string): CommonAssetItem[] | undefined

const foods = APJS.CommonAssetController.getAssetGroup('food');
if (!foods) {
  return;
}

getAsset(groupKey: string, assetKey: string): CommonAssetItem | null

const uk = APJS.CommonAssetController.getAsset('countries', 'uk');
if (uk === null) {
  return;
}

Use Case

@component()
export class NewBehaviourScript extends APJS.BasicScriptComponent {
  onStart() {
    APJS.CommonAssetController.loadAssets(
      {
        remoteAssetGroupInfos: [
          {
            groupKey: 'countries',
            explicitAssetKeys: ['uk', 'usa'],
          },
          {
            groupKey: 'food',
            explicitAssetKeys: ['pizza'],
            randomAssetCount: 3,
          },
        ],
      },
      () => {
        const foods = APJS.CommonAssetController.getAssetGroup('food');
        const pizza = APJS.CommonAssetController.getAsset('food', 'pizza');
        const uk = APJS.CommonAssetController.getAsset('countries', 'uk');
        const texture = uk !== null ? uk.texture : null;
        const meta = uk !== null && uk.textData !== null ? JSON.parse(uk.textData) : null;
        const ukName = meta !== null ? meta['name'] : null;
        const ukCapital = meta !== null ? meta['capital'] : null;
      }
    );
  }
}

CommonAssetControllerRequestInfo

Request payload passed to CommonAssetController.loadAssets.

Type	Name	Description
Variables	remoteAssetGroupInfos: CommonAssetGroupRequest[]	The list of remote asset groups to request Must be a non-empty array

CommonAssetGroupRequest

One asset group to request during loadAssets.

Type	Name	Description
Variables	groupKey: string	The stable key of the asset group to request
Variables	explicitAssetKeys?: string[]	Exact asset keys to request Combined random picks exclude these keys
Variables	randomAssetCount?: number	Number of random assets to request Combined results are de-duplicated and capped by group size

CommonAssetItem

One loaded common asset returned by getAssetGroup or getAsset.

Type	Name	Description
Variables	groupKey: string	The asset group that contains this item
Variables	assetKey: string	The stable key of this asset
Variables	texture: Texture \| null	The loaded texture for downloaded media assets null for text-only assets
Variables	textData: string \| null	JSON object string for this asset's metadata null when there is no metadata