目录

AssetAccelerationExtensionAbility (ExtensionAbility for Resource Acceleration)

This module is the framework for resource package background download and provides key lifecycle functions. Corresponding callback functions are called when background download tasks succeed, fail, or end.

Since: 5.1.0(18)

Constraints

The module has the following restrictions:

Modules to Import

import { AssetAccelerationExtensionAbility } from '@kit.GraphicsAccelerateKit';

AssetAccelerationExtensionInfo

Describes information about the resource acceleration ExtensionAbility.

System capability: SystemCapability.GraphicsGame.AssetAcceleration

Model restriction: APIs of this module can be used only in the stage model.

Since: 5.1.0(18)

Name Type Read-Only Optional Description
maxBackgroundDownloadSize number Yes No

Maximum resource size, in bytes. The resource acceleration ExtensionAbility is enabled only when the remaining storage space on a user device is greater than three times the value of maxBackgroundDownloadSize.

The default value is 0.

The value of maxBackgroundDownloadSize is the package size specified when you apply for the resource pre-download service in AppGallery Connect.
domainList string[] Yes No Domain name trustlist. Download tasks with domain names not in this trustlist will directly fail.

ContentRequestType

type ContentRequestType = 'INSTALL' | 'UPDATE' | 'IDLE'

Describes the content request type.

System capability: SystemCapability.GraphicsGame.AssetAcceleration

Model restriction: APIs of this module can be used only in the stage model.

Since: 5.1.0(18)

Type Description
'INSTALL' Install.
'UPDATE' Update.
'IDLE' Idle.

AssetAccelerationExtensionAbility

Describes the resource acceleration extension capability class.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GraphicsGame.AssetAcceleration

Since: 5.1.0(18)

[h2]Properties

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GraphicsGame.AssetAcceleration

Since: 5.1.0(18)

Name Type Read-Only Optional Description
context AssetAccelerationExtensionContext No No Context of AssetAccelerationExtensionAbility, which inherits from ExtensionContext.

[h2]onDownloadContentRequest

onDownloadContentRequest(requestType: ContentRequestType, manifestUrl: string, assetAccelerationExtensionInfo: AssetAccelerationExtensionInfo): Promise<assetDownloadManager.AssetDownloadConfig[]>

Obtains the resource package download task list when the app is installed or updated, or when the user device is idle. The number of tasks returned cannot exceed 200. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GraphicsGame.AssetAcceleration

Since: 5.1.0(18)

Parameters

Parameter Type Mandatory Description
requestType ContentRequestType Yes Content request type.
manifestUrl string Yes

Resource package download URL.

- If a Huawei CDN is used, this parameter is not empty.

- If a third-party CDN is used, leave this parameter empty.

The default value is an empty string.
assetAccelerationExtensionInfo AssetAccelerationExtensionInfo Yes Information about the resource acceleration ExtensionAbility.

Return value

Type Description
Promise<assetDownloadManager.AssetDownloadConfig[]> Promise that returns a configuration information list of a maximum of 200 download tasks.

Example

import { common } from '@kit.AbilityKit';
import { assetDownloadManager, AssetAccelerationExtensionAbility, AssetAccelerationExtensionInfo, ContentRequestType } from '@kit.GraphicsAccelerateKit';

// In this example, AssetAccelExtAbility inherits from AssetAccelerationExtensionAbility.
export default class AssetAccelExtAbility extends AssetAccelerationExtensionAbility {
  async onDownloadContentRequest(requestType: ContentRequestType, manifestUrl: string,
    _assetAccelerationExtensionInfo: AssetAccelerationExtensionInfo):
        Promise<assetDownloadManager.AssetDownloadConfig[]> {
    const context = this.context as common.ExtensionContext; // If the API needs to use a context of the common.Context type, you can obtain the context object of the common.ExtensionContext type from **this.context**.
    console.info('AssetAccelDemo', `application file directory = ${context.filesDir}`);
    console.info('AssetAccelDemo', `onDownloadContentRequest enter, requestType: ${requestType}, manifestUrl: ${manifestUrl}.`);
    // Construct the download task configuration information used as the API's return value. The fields in the download object are for demonstration only and should not be directly used in the production environment.
    let downloadList: Array<assetDownloadManager.AssetDownloadConfig> = [];
    let download: assetDownloadManager.AssetDownloadConfig = {
        identifier: 'identifier', // Identifier of a resource to be downloaded.
        url: 'url', // URL of a resource to be downloaded.
        isEssential: false, // Indicates whether the resource to be downloaded is essential.
        groupId: 'groupId' // Group ID, which is used to identify the resource version information.
        fileName: 'fileName', // File name of a resource to be downloaded.
      };
    downloadList.push(download);
    await Promise.resolve();
    return downloadList;
  }
}

[h2]onDownloadWithAppControl

onDownloadWithAppControl(requestType: ContentRequestType, manifestUrl: string, assetAccelerationExtensionInfo: AssetAccelerationExtensionInfo): Promise<boolean>

Triggers the ExtensionAbility to initiate coordinated download when the app is installed or updated, or when the user device is idle. If there is a resource package download task, true is returned. Otherwise, false is returned. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GraphicsGame.AssetAcceleration

Since: 5.1.1(19)

Parameters

Parameter Type Mandatory Description
requestType ContentRequestType Yes Content request type.
manifestUrl string Yes

Resource package download URL.

- If a Huawei CDN is used to host resources, the URL is provided by the Huawei CDN.

- If a third-party CDN is used, leave this parameter empty.

The default value is an empty string.
assetAccelerationExtensionInfo AssetAccelerationExtensionInfo Yes Information about the resource acceleration ExtensionAbility.

Return value

Type Description
Promise<boolean>

Promise object.

- true: There is a download task in the app's downloader.

- false: There is no download task in the app's downloader.

Example

import { common } from '@kit.AbilityKit';
import { AssetAccelerationExtensionAbility, AssetAccelerationExtensionInfo, ContentRequestType } from '@kit.GraphicsAccelerateKit';

// In this example, AssetAccelExtAbility inherits from AssetAccelerationExtensionAbility.
export default class AssetAccelExtAbility extends AssetAccelerationExtensionAbility {
  async onDownloadWithAppControl(requestType: ContentRequestType, manifestUrl: string,
    _assetAccelerationExtensionInfo: AssetAccelerationExtensionInfo): Promise<boolean> {
    const context = this.context as common.ExtensionContext; // If the API needs to use a context of the common.Context type, you can obtain the context object of the common.ExtensionContext type from **this.context**.
    console.info('AssetAccelDemo', `application file directory = ${context.filesDir}`);
    console.info('AssetAccelDemo', `onDownloadWithAppControl enter, requestType: ${requestType}, manifestUrl: ${manifestUrl}.`);
    // If there is a download task, true is returned and the app's downloader is called to download resource packages. Otherwise, false is returned.
    // ...
    let hasDownloadTask = true;
    await Promise.resolve();
    return hasDownloadTask;
  }
}

[h2]onBackgroundDownloadSucceeded

onBackgroundDownloadSucceeded(downloadTask: assetDownloadManager.AssetDownloadTask, filePath: string): Promise<void>

Notifies the resource acceleration ExtensionAbility of download success. The API is executed when a system background download task is successful. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GraphicsGame.AssetAcceleration

Since: 5.1.0(18)

Parameters

Parameter Type Mandatory Description
downloadTask assetDownloadManager.AssetDownloadTask Yes Download task information.
filePath string Yes

Local sandbox address of a downloaded file. Downloaded files are stored in the app's cache directory.

Example path:

/data/storage/el2/base/haps/entry/cache/asset_acceleration/1.8.2/xxx.bin

The value contains a maximum of 512 bytes.

Return value

Type Description
Promise<void> Promise that returns no value.

Example

import { assetDownloadManager, AssetAccelerationExtensionAbility } from '@kit.GraphicsAccelerateKit';

// In this example, AssetAccelExtAbility inherits from AssetAccelerationExtensionAbility.
export default class AssetAccelExtAbility extends AssetAccelerationExtensionAbility {
  // Receive the background download success notification.
  async onBackgroundDownloadSucceeded(downloadTask: assetDownloadManager.AssetDownloadTask,
    filePath: string): Promise<void> {
    console.info('AssetAccelDemo', `onBackgroundDownloadSucceeded enter, taskId is ${downloadTask.taskId}, filePath = ${filePath}`);
    // Add the logic for transferring files.
    await Promise.resolve();
  }
}

[h2]onBackgroundDownloadFailed

onBackgroundDownloadFailed(downloadTask: assetDownloadManager.AssetDownloadTask, fault: assetDownloadManager.DownloadFault): Promise<void>

Notifies the resource acceleration ExtensionAbility of download failure. The API is executed when a system background download task fails. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GraphicsGame.AssetAcceleration

Since: 5.1.0(18)

Parameters

Parameter Type Mandatory Description
downloadTask assetDownloadManager.AssetDownloadTask Yes Download task information.
fault assetDownloadManager.DownloadFault Yes Download failure cause.

Return value

Type Description
Promise<void> Promise that returns no value.

Example

import { assetDownloadManager, AssetAccelerationExtensionAbility } from '@kit.GraphicsAccelerateKit';

// In this example, AssetAccelExtAbility inherits from AssetAccelerationExtensionAbility.
export default class AssetAccelExtAbility extends AssetAccelerationExtensionAbility {
  // Receive the background download failure notification.
  async onBackgroundDownloadFailed(downloadTask: assetDownloadManager.AssetDownloadTask,
    fault: assetDownloadManager.DownloadFault): Promise<void> {
    console.info('AssetAccelDemo', `onBackgroundDownloadFailed enter, download url: ${downloadTask.config.url}, err: ${fault}`);
    // Add the logic for handling download exceptions.
    await Promise.resolve();
  }
}

[h2]onExtensionWillTerminate

onExtensionWillTerminate(error?: BusinessError<void>): Promise<void>

Notifies the resource acceleration ExtensionAbility that the resource package background download function is to be disabled. The API is executed when the resource acceleration ExtensionAbility will terminate, either normally or due to a scheduling error. You are advised to perform resource clearing operations in this method. Do not perform time-consuming operations. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GraphicsGame.AssetAcceleration

Since: 5.1.0(18)

Parameters

Parameter Type Mandatory Description
error BusinessError<void> No

Error codes:

401: Parameter error.

1016600005: The execution of a resource acceleration ExtensionAbility method times out.

1016600006: There is an abnormal method within the resource acceleration ExtensionAbility lifecycle.

1016600094: Service error.

Return value

Type Description
Promise<void> Promise that returns no value.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { AssetAccelerationExtensionAbility } from '@kit.GraphicsAccelerateKit';

// In this example, AssetAccelExtAbility inherits from AssetAccelerationExtensionAbility.
export default class AssetAccelExtAbility extends AssetAccelerationExtensionAbility {
  // This callback is executed when AssetAccelerationExtensionAbility will terminate, either normally or due to a scheduling error.
  async onExtensionWillTerminate(error?: BusinessError<void>): Promise<void> {
    // Add the logic for performing operations such as resource cleanup. Avoid time-consuming operations.
    if (!error) {
      console.info('AssetAccelDemo', `onExtensionWillTerminate enter, BusinessError is null;`);
      return;
    }
    console.error('AssetAccelDemo', `onExtensionWillTerminate enter, BusinessError: ${error?.code}, msg: ${error?.message}`);
    await Promise.resolve();
  }
}