We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Cookie Settings
Only Essential Cookies
Accept All
MaterialsConsole

HarmonyOS

输入关键字搜索
HMS Core
AppGallery Connect
HUAWEI HiAI
CTRL+K
GuidesApplication FrameworkBackground Tasks KitContinuous Task (ArkTS)

Continuous Task (ArkTS)

Last updated: 2026-06-15 01:03
Content overview
Expand

Overview

Introduction

If an application has a perceivable task that needs to run in an extended period of time in the background, it can request a continuous task to prevent itself from being suspended. Examples of continuous tasks include music playback and navigation in the background. Within a continuous task, the application can concurrently request multiple types of tasks and update the task types. When the application operates in the background, the system performs consistency check to ensure that the application is executing the corresponding continuous task. Upon successful request for a continuous task, the notification panel displays the message associated with the task. If the user deletes the message, the system automatically terminates the task.

NOTE

After an application is moved to the background, its lifecycle changes vary depending on the device type. For details, see Differentiated Lifecycle Behaviors Across Different Devices.

Use Cases

The table below lists the types of continuous tasks, which are used in various scenarios. You can select a task type suitable for your case based on the description.

Table 1 Continuous task types

Expand
Name Description Item Example Scenario
DATA_TRANSFER Data transfer. dataTransfer Non-hosting uploading and downloading operations, like those occurring in the background of a web browser for data transfer.
AUDIO_PLAYBACK Audio and video playback. audioPlayback

Audio and video playback in the background; audio and video casting.

Note: It can be used in atomic services.
AUDIO_RECORDING Recording. audioRecording Recording and screen capture in the background.
LOCATION Positioning and navigation. location Positioning and navigation.
BLUETOOTH_INTERACTION Bluetooth-related services. bluetoothInteraction An application transitions into the background during the process of file transfer using Bluetooth.
MULTI_DEVICE_CONNECTION Multi-device connection. multiDeviceConnection

Distributed service connection and casting.

Note: It can be used in atomic services.
VOIP

Audio and video calls.

Note: It is supported since API version 13.

 voip Chat applications (with audio and video services) transition into the background during audio and video calls.
TASK_KEEPING

Computing tasks.

Note: Starting from API version 21, this capability is available for 2-in-1 devices, and non-2-in-1 devices that have obtained the ACL permission ohos.permission.KEEP_BACKGROUND_RUNNING_SYSTEM. In API version 20 and earlier versions, this task type is limited to PCs/2-in-1 devices only.

 taskKeeping Antivirus software is running.
MODE_AV_PLAYBACK_AND_RECORD

Multimedia services.

Note: It is supported since API version 22.

 avPlaybackAndRecord When an application is in the background during audio/video playback, recording, or audio/video calls, you can select either this task type or the corresponding continuous task type for these three scenarios. For example, in the audio/video playback scenario, you can choose either AUDIOPLAYBACK or MODE_AVPLAYBACK_AND_RECORD.
MODE_SPECIAL_SCENARIO_PROCESSING

Special scenarios (available only for smartphones, tablets, PCs/2-in-1 devices).

Note: It is supported since API version 22.

 specialScenarioProcessing Exporting media files in the background, and using third-party casting components for background casting.

Description of DATA_TRANSFER:

  • During data transfer, if an application uses the @ohos.request (Upload and Download) to hand over tasks to the system, the application will be suspended in the background even if it has requested the continuous task of the DATA_TRANSFER type.

  • During data transfer, the application needs to update the progress. If the progress is not updated for a long time (more than 10 minutes after the first update), the continuous task of the DATA_TRANSFER type will be canceled. The notification type of the progress update must be live view. For details, see the example in startBackgroundRunning().

Description of AUDIO_PLAYBACK:

  • Casting audio and video involves transmitting content from one device to another for playback purposes. If the application transitions to the background while casting, the continuous task checks the audio and video playback and casting services. The task will persist as long as either the audio and video playback or casting service is running properly.

  • If the application needs to play media (STREAM_USAGE_MUSIC, STREAM_USAGE_MOVIE, or STREAM_USAGE_AUDIOBOOK) or games (STREAM_USAGE_GAME) in the background, it must access the AVSession service and request a continuous task of the AUDIO_PLAYBACK type.

  • In addition to the aforementioned playback types, when an application needs to run other user-perceptible tasks in the background for a long time, it must request continuous tasks of the AUDIO_PLAYBACK type, without accessing AVSession.

  • If the application does not comply with the preceding access specifications, it will be muted and suspended by the system when switched to the background. It can resume playback only when it returns to the foreground.

  • Starting from API version 20, if a continuous task of the AUDIO_PLAYBACK type is requested without being connected to AVSession, a notification will appear in the notification panel once the task is successfully requested. Once AVSession is connected, the background task module will no longer send notifications; instead, notifications will be sent by AVSession. For API version 19 and earlier versions, the background task module does not display notifications in the notification panel.

  • The system may freeze an application that requests a continuous task of the AUDIO_PLAYBACK type if no audio is playing while the application is in the background.

Description of BLUETOOTH_INTERACTION (Bluetooth-related services):

If an application applies only for a Bluetooth continuous task, it will be canceled upon Bluetooth disconnection caused by device distance. To ensure a seamless Bluetooth connection experience, the system allows applications that meet the following conditions to keep alive for a period of time (depending on the system load, up to 10 minutes) after the connection is restored, so that the applications can run in the background for a long time.

  1. Register the event of suspending the listening of a continuous task so that the task is marked as suspended instead of being immediately canceled by the system. For details, see on('continuousTaskSuspend').
  2. To enable timely reconnection after Bluetooth disconnection, subscribe to the Bluetooth connection state change event via on('connectionStateChange'). After disconnection, initiate a BLE scan using startScan, subscribe to the BLE device scan result reporting event via on('BLEDeviceFind'), and check whether the device is back within the connectable range.
  3. After successfully scanning the device, the application needs to proactively restore the Bluetooth connection via connect. The system then reactivates the suspended continuous task and keeps it alive.

Constraints

Ability restrictions: In the stage model, only the UIAbility can request continuous tasks. In the FA model, only the ServiceAbility can request continuous tasks. Continuous tasks can be requested by the current application on the current device or across devices or by other applications. However, the capability to make cross-device or cross-application requests is restricted to system applications.

Quantity restrictions:

  • Since API version 21, a single UIAbility can request multiple continuous tasks simultaneously, with a maximum limit of 10. For details, see startBackgroundRunning(). For API version 20 and earlier versions, a UIAbility (ServiceAbility in the FA model) can only request one continuous task at a time. If a UIAbility already has an ongoing continuous task, it can only submit a new request after the existing task is completed. If an application needs to request multiple continuous tasks simultaneously, it must create multiple UIAbilities.
  • If an application has multiple UIAbilities, once one UIAbility successfully requests a continuous task, all processes of the entire application will not be suspended.

Running restrictions:

  • If an application requests a continuous task but does not carry out the relevant service, the system imposes restrictions on the application. For example, if the system detects that an application has requested a continuous task of the AUDIO_PLAYBACK type but does not play audio, the application will be suspended when it returns to the background.

  • If an application requests a continuous task but carries out a service that does not match the requested type, the system imposes restrictions on the application. The application will be suspended when it returns to the background. For example, if the system detects that an application requests a continuous task of the AUDIO_PLAYBACK type, but the application is playing audio (corresponding to the AUDIO_PLAYBACK type) and recording (corresponding to the AUDIO_RECORDING type), the system enforces management measures.

  • When an application's operations are completed after a continuous task request, the system imposes restrictions on the application. The application will be suspended when it returns to the background.

  • If the background load of the process that runs a continuous task is higher than the corresponding typical load for a long period of time, the system performs certain control. The application will be suspended or terminated when it is switched to the background.

NOTE

An application must proactively cancel a continuous task once the task is completed. Otherwise, the application will be suspended when moved to the background. For example, when a user taps the UI to pause music playback, the application must cancel the continuous task in a timely manner. When the user taps the UI again to continue music playback, the application needs to request a continuous task.

If an application that plays an audio in the background is interrupted, the system automatically detects and stops the continuous task. The application must request a continuous task again to restart the playback.

When an application that plays audio in the background stops a continuous task, it must suspend or stop the audio stream. Otherwise, the application will be forcibly terminated by the system.

Available APIs

Table 2 Main APIs for continuous tasks

The table below uses promise as an example to describe the APIs used for developing continuous tasks. For details about more APIs and their usage, see Background Task Management.

Expand
API Description
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void> Requests a continuous task. A UIAbility can apply for only one continuous task at a time. If a UIAbility already has an ongoing continuous task, it can only submit a new request after the existing task is completed.
stopBackgroundRunning(context: Context): Promise<void> Cancels a continuous task.
startBackgroundRunning(context: Context, request: ContinuousTaskRequest): Promise<ContinuousTaskNotification> Requests multiple continuous tasks. This API enables a UIAbility to request multiple continuous tasks simultaneously, with a maximum limit of 10.
stopBackgroundRunning(context: Context, continuousTaskId: number): Promise<void> Cancels a continuous task with the specified ID.

How to Develop

The following walks you through how to request a continuous task for recording to implement the following functionalities:

  • When a user touches Request Continuous Task, the application requests a continuous task for recording, and a message is displayed in the notification bar, indicating that a recording task is running.

  • When a user touches Cancel Continuous Task, the application cancels the continuous task, and the notification message is removed.

Stage Model

  1. Declare the ohos.permission.KEEP_BACKGROUND_RUNNING permission. For details, see Declaring Permissions.

  2. Declare the continuous task type.

    Declare the type of the continuous task for the target UIAbility under abilities in the module.json5 file. Set the corresponding configuration item in the configuration file.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. "module": {
    2.     "abilities": [
    3.         {
    4.            "backgroundModes": [
    5.            // Configuration item of the continuous task type
    6.            "audioRecording",
    7.            "bluetoothInteraction",
    8.            "audioPlayback"
    9.            ]
    10.         }
    11.     ],
    12.     // ...
    13. }

  3. Import the modules.

    Import the modules related to continuous tasks: @ohos.resourceschedule.backgroundTaskManager and @ohos.app.ability.wantAgent. Import other modules based on the project requirements.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1.  import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
    2.  import { BusinessError } from '@kit.BasicServicesKit';
    3.  import { wantAgent, WantAgent } from '@kit.AbilityKit';
    4.  // In atomic services, remove the WantAgent import.

  4. Request and cancel a continuous task.

    The code snippet below shows how an application requests and cancels a continuous task for itself.

    Since API version 15, you can use on('continuousTaskCancel') to listen for the cancellation of a continuous task.

    Since API version 16, you can use BackgroundSubMode to implement the Bluetooth car key function.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. function callback(info: backgroundTaskManager.ContinuousTaskCancelInfo) {
    2.   // ID of a continuous task.
    3.   console.info('OnContinuousTaskCancel callback id ' + info.id);
    4.   // Reason for canceling the continuous task.
    5.   console.info('OnContinuousTaskCancel callback reason ' + info.reason);
    6. }
    7. 

    8. @Entry
    9. @Component
    10. struct Index {
    11.   @State message: string = 'ContinuousTask';
    12.   // Obtain the UIAbility context of the page by calling getUIContext().getHostContext().
    13.   private context: Context | undefined = this.getUIContext().getHostContext();
    14. 

    15.   // ...
    16. 

    17.   OnContinuousTaskCancel() {
    18.     try {
    19.       backgroundTaskManager.on('continuousTaskCancel', callback);
    20.       console.info(`Succeeded in operationing OnContinuousTaskCancel.`);
    21.     } catch (error) {
    22.       console.error(`Operation OnContinuousTaskCancel failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
    23.     }
    24.   }
    25. 

    26.   OffContinuousTaskCancel() {
    27.     try {
    28.       // If the callback parameter is not passed, all callbacks associated with the specified event are canceled.
    29.       backgroundTaskManager.off('continuousTaskCancel', callback);
    30.       console.info(`Succeeded in operationing OffContinuousTaskCancel.`);
    31.     } catch (error) {
    32.       console.error(`Operation OffContinuousTaskCancel failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
    33.     }
    34.   }
    35. 

    36.   // Request a continuous task using .then().
    37.   startContinuousTask() {
    38.     let wantAgentInfo: wantAgent.WantAgentInfo = {
    39.       // List of operations to be executed after the notification is clicked.
    40.       // Add the bundleName and abilityName of the application to start.
    41.       wants: [
    42.         {
    43.           bundleName: 'ohos.samples.continuoustask',
    44.           abilityName: 'MainAbility'
    45.         }
    46.       ],
    47.       // Specify the action to perform (starting the ability) after the notification message is clicked.
    48.       actionType: wantAgent.OperationType.START_ABILITY,
    49.       // Custom request code.
    50.       requestCode: 0,
    51.       // Execution attribute of the operation to perform after the notification is clicked.
    52.       actionFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG],
    53.       // CAR_KEY subtype, which takes effect only when a continuous task of the bluetoothInteraction type is requested. This subtype is supported since API version 16.
    54.       // Ensure that the key value in the extraInfo parameter is backgroundTaskManager.BackgroundModeType.SUB_MODE. Otherwise, the subtype does not take effect.
    55.       // extraInfo: {
    56.         // [backgroundTaskManager.BackgroundModeType.SUB_MODE] :backgroundTaskManager.BackgroundSubMode.CAR_KEY
    57.       // }
    58.     };
    59. 

    60.     try {
    61.       // Obtain the WantAgent object by using the getWantAgent API of the wantAgent module.
    62.       // In atomic services, replace the following line of code with wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: object) => {.
    63.       wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: WantAgent) => {
    64.         try {
    65.           let list: string[] = ['audioPlayback'];
    66.           // let list: string[] = ['bluetoothInteraction']; The bluetoothInteraction type is included in the continuous task, and the CAR_KEY subtype is valid.
    67.           backgroundTaskManager.startBackgroundRunning(this.context, list, wantAgentObj).
    68.             then((res: backgroundTaskManager.ContinuousTaskNotification) => {
    69.             console.info('Operation startBackgroundRunning succeeded');
    70.             // Execute the continuous task logic, for example, audio playback.
    71.             // The system checks the authenticity of the service scenario. If the corresponding service is not executed, the system may cancel the continuous task and suspend the application.
    72.             // ...
    73.           }).catch((error: BusinessError) => {
    74.             console.error(`Failed to Operation startBackgroundRunning. code is ${error.code} message is ${error.message}`);
    75.           });
    76.         } catch (error) {
    77.           console.error(`Failed to Operation startBackgroundRunning. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
    78.         }
    79.       });
    80.     } catch (error) {
    81.       console.error(`Failed to Operation getWantAgent. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
    82.     }
    83.   }
    84. 

    85.   // Cancel a continuous task using .then().
    86.   stopContinuousTask() {
    87.     backgroundTaskManager.stopBackgroundRunning(this.context).then(() => {
    88.       console.info(`Succeeded in operationing stopBackgroundRunning.`);
    89.       // ...
    90.     }).catch((err: BusinessError) => {
    91.       console.error(`Failed to operation stopBackgroundRunning. Code is ${err.code}, message is ${err.message}`);
    92.     });
    93.   }
    94. 

    95.   build() {
    96.     Row() {
    97.       Column() {
    98.         Text('Index')
    99.           .fontSize(50)
    100.           .fontWeight(FontWeight.Bold)
    101. 

    102.         Button() {
    103.           Text('Request continuous task').fontSize(25).fontWeight(FontWeight.Bold)
    104.         }
    105.         .type(ButtonType.Capsule)
    106.         .margin({ top: 10 })
    107.         .backgroundColor('#0D9FFB')
    108.         .width(250)
    109.         .height(40)
    110.         .id('applyContinuousTask')
    111.         .onClick(() => {
    112.           // Request a continuous task by clicking a button.
    113.           this.startContinuousTask();
    114.         })
    115. 

    116.         Button() {
    117.           Text ('Cancel continuous task').fontSize (25).fontWeight (FontWeight.Bold)
    118.         }
    119.         .type(ButtonType.Capsule)
    120.         .margin({ top: 10 })
    121.         .backgroundColor('#0D9FFB')
    122.         .width(250)
    123.         .height(40)
    124.         .id('resetContinuousTask')
    125.         .onClick(() => {
    126.           // Stop the continuous task.
    127. 

    128.           // Cancel the continuous task through a button.
    129.           this.stopContinuousTask();
    130.         })
    131. 

    132.         Button() {
    133.           Text('Register a callback for canceling a continuous task').fontSize (25).fontWeight(FontWeight.Bold)
    134.         }
    135.         .type(ButtonType.Capsule)
    136.         .margin({ top: 10 })
    137.         .backgroundColor('#0D9FFB')
    138.         .width(250)
    139.         .height(40)
    140.         .onClick(() => {
    141.           // Use a button to register a callback for canceling a continuous task.
    142.           this.OnContinuousTaskCancel();
    143.         })
    144. 

    145.         Button() {
    146.           Text('Unregister a callback for canceling the continuous task').fontSize (25).fontWeight(FontWeight.Bold)
    147.         }
    148.         .type(ButtonType.Capsule)
    149.         .margin({ top: 10 })
    150.         .backgroundColor('#0D9FFB')
    151.         .width(250)
    152.         .height(40)
    153.         .onClick(() => {
    154.           // Use a button to unregister a callback for canceling a continuous task.
    155.           this.OffContinuousTaskCancel();
    156.         })
    157.         // ...
    158.       }
    159.       .width('100%')
    160.     }
    161.     .height('100%')
    162.   }
    163. }

  5. Request and cancel a continuous task using async/await.

    The code snippet below shows how an application requests and cancels a continuous task using async/await for itself.

    Since API version 15, you can use on('continuousTaskCancel') to listen for the cancellation of a continuous task.

    Since API version 16, you can use BackgroundSubMode to implement the Bluetooth car key function.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. @Entry
    2. @Component
    3. struct IndexAsyncAndAwait {
    4.   @State message: string = 'ContinuousTask';
    5.   // Obtain the UIAbility context of the page by calling getUIContext().getHostContext().
    6.   private context: Context | undefined = this.getUIContext().getHostContext();
    7. 

    8.   // ...
    9. 

    10.   // Request a continuous task using async/await.
    11.   async startContinuousTask() {
    12.     let wantAgentInfo: wantAgent.WantAgentInfo = {
    13.       // List of operations to be executed after the notification is clicked.
    14.       // Add the bundleName and abilityName of the application to start.
    15.       wants: [
    16.         {
    17.           bundleName: 'ohos.samples.continuoustask',
    18.           abilityName: 'MainAbility'
    19.         }
    20.       ],
    21.       // Specify the action to perform (starting the ability) after the notification message is clicked.
    22.       actionType: wantAgent.OperationType.START_ABILITY,
    23.       // Custom request code.
    24.       requestCode: 0,
    25.       // Execution attribute of the operation to perform after the notification is clicked.
    26.       actionFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG],
    27.       // CAR_KEY subtype, which takes effect only when a continuous task of the bluetoothInteraction type is requested. This subtype is supported since API version 16.
    28.       // Ensure that the key value in the extraInfo parameter is backgroundTaskManager.BackgroundModeType.SUB_MODE. Otherwise, the subtype does not take effect.
    29.       // extraInfo: {
    30.         // [backgroundTaskManager.BackgroundModeType.SUB_MODE] :backgroundTaskManager.BackgroundSubMode.CAR_KEY
    31.       // }
    32.     };
    33. 

    34.     try {
    35.       // Obtain the WantAgent object by using the getWantAgent API of the wantAgent module.
    36.       // In atomic services, replace the following line of code with const wantAgentObj: object = await wantAgent.getWantAgent(wantAgentInfo);.
    37.       const wantAgentObj: WantAgent = await wantAgent.getWantAgent(wantAgentInfo);
    38.       try {
    39.         let list: string[] = ['audioPlayback'];
    40.         // let list: string[] = ['bluetoothInteraction']; The bluetoothInteraction type is included in the continuous task, and the CAR_KEY subtype is valid.
    41.         // In atomic services, let list: Array<string> = ["audioPlayback"];
    42.         const res: backgroundTaskManager.ContinuousTaskNotification =
    43.           await backgroundTaskManager.startBackgroundRunning(this.context as Context, list, wantAgentObj);
    44.         console.info(`Operation startBackgroundRunning succeeded, notificationId: ${res.notificationId}`);
    45.         // Execute the continuous task logic, for example, audio playback.
    46.         // ...
    47.       } catch (error) {
    48.         console.error(`Failed to Operation startBackgroundRunning. Code is ${(error as BusinessError).code}, message is ${(error as BusinessError).message}`);
    49.       }
    50.     } catch (error) {
    51.       console.error(`Failed to Operation getWantAgent. Code is ${(error as BusinessError).code}, message is ${(error as BusinessError).message}`);
    52.     }
    53.   }
    54. 

    55.   // Cancel a continuous task using async/await.
    56.   async stopContinuousTask() {
    57.     try {
    58.       await backgroundTaskManager.stopBackgroundRunning(this.context);
    59.       console.info(`Succeeded in operationing stopBackgroundRunning.`);
    60.       // ...
    61.     } catch (error) {
    62.       console.error(`Failed to operation stopBackgroundRunning. Code is ${(error as BusinessError).code}, message is ${(error as BusinessError).message}`)
    63.     }
    64.   }
    65. 

    66.   build() {
    67.     Row() {
    68.       Column() {
    69.         Text('Index')
    70.           .fontSize(50)
    71.           .fontWeight(FontWeight.Bold)
    72. 

    73.         Button() {
    74.           Text('Request continuous task').fontSize(25).fontWeight(FontWeight.Bold)
    75.         }
    76.         .type(ButtonType.Capsule)
    77.         .margin({ top: 10 })
    78.         .backgroundColor('#0D9FFB')
    79.         .width(250)
    80.         .height(40)
    81.         .id('applyContinuousTask')
    82.         .onClick(() => {
    83.           // Request a continuous task by clicking a button.
    84.           this.startContinuousTask();
    85.         })
    86. 

    87.         Button() {
    88.           Text ('Cancel continuous task').fontSize (25).fontWeight (FontWeight.Bold)
    89.         }
    90.         .type(ButtonType.Capsule)
    91.         .margin({ top: 10 })
    92.         .backgroundColor('#0D9FFB')
    93.         .width(250)
    94.         .height(40)
    95.         .id('resetContinuousTask')
    96.         .onClick(() => {
    97.           // Stop the continuous task.
    98. 

    99.           // Cancel the continuous task through a button.
    100.           this.stopContinuousTask();
    101.         })
    102.         // ...
    103.       }
    104.       .width('100%')
    105.     }
    106.     .height('100%')
    107.   }
    108. }
Transient Task (C/C++)
Deferred Task (ArkTS)
English
©2026 HUAWEI Developers. All rights reserved.
Terms of Use
Statement About HUAWEI Developers and Privacy
Cookies
Cookie Settings
Open-Source Software Notice
Search in Guides
Enter a keyword.