Developing Intents Using Configuration Files

Overview

Starting from API version 11, you can develop intents using configuration files. This mainly involves two steps:

Define intents in the insight_intent.json file, and declare the code path of the intent executor and the bound ability component.
Implement the intent execution logic using InsightIntentExecutor.

The fields to be configured and the intention executors to be implemented vary depending on the type of ability component, as described in the table below.

Component Type	Intent Configuration	Intent Executor
UIAbility	Configure the uiAbility field in the insight_intent.json file.	When executeMode is set to foreground, implement onExecuteInUIAbilityForegroundMode to start the bound UIAbility via startAbility. When executeMode is set to background, implement onExecuteInUIAbilityBackgroundMode to start the bound UIAbility via Call.
UIExtensionAbility	Configure the uiExtension field in the insight_intent.json file.	Implement onExecuteInUIExtensionAbility.
ServiceExtensionAbility	Configure the serviceExtension field in the insight_intent.json file.	Implement onExecuteInServiceExtensionAbility.
Widget (FormExtensionAbility)	Configure the form field in the insight_intent.json file.	No separate executor required.

Available APIs

To implement an intent executor, inherit from InsightIntentExecutor and implement APIs such as onExecuteInUIAbilityForegroundMode. To respond to intent execution, implementing these APIs. The triggering timing varies based on the intent execution mode. For details about the execution timing under different modes, see the API documentation of each callback.

How to Develop

Binding an Intent to a UIAbility

You can create intents in a visualized manner using DevEco Studio. The procedure is as follows:

Right-click a module or a file in a module and choose New > Insight Intent to enter the InsightIntent framework configuration page.
Choose the intent vertical domain, the file name for the InsightIntent framework entry code, and the intent configuration, which includes the intent name and the bound application component.

When you have finished, click Finish.

An insight_intent.json file is generated in module > src > main > resources > base > profile. You can view the current InsightIntent framework configuration details in this file.

{
  "insightIntents": [
    {
      "domain": "MusicDomain",
      "intentName": "PlayMusic",
      "intentVersion": "1.0.1",
      "srcEntry": "./ets/insightintents/PlayMusicExecutor.ets",
      "uiAbility": {
        "ability": "MusicPlayerAbility",
        "executeMode": [
          "foreground",
          "background"
        ]
      }
    }
  ]
}

An entry code file is generated in module > src > main > ets > insightintents. Implement the functional code for the intent in the intent execution function.

// This file is the entry point corresponding to the 'srcEntry' field in intent configuration.
import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
// ···

export default class PlayMusicExecutor extends InsightIntentExecutor {
  // If 'executeMode' in intent configuration is set to 'foreground', this API should be implemented.
  async onExecuteInUIAbilityForegroundMode(intentName: string, params: Record<string, Object>,
    windowStage: window.WindowStage): Promise<insightIntent.ExecuteResult> {
    // Implement the playback logic.
    // ···
    const result: insightIntent.ExecuteResult = {
      code: 0
    };
    return Promise.resolve(result);
  }

  // If 'executeMode' in intent configuration is set to 'background', this API should be implemented.
  async onExecuteInUIAbilityBackgroundMode(intentName: string,
    params: Record<string, Object>): Promise<insightIntent.ExecuteResult> {
    // Background control logic.
    const result: insightIntent.ExecuteResult = {
      code: 0
    };
    return Promise.resolve(result);
  }
}

NOTE

The configuration file approach only provides basic execution capabilities. The parameter format must be negotiated between the developer and the system entry point.

You can also manually create the intent configuration file and intent executor according to the specifications. Pay attention to the following points:

You must declare the bound application component and supported intent execution mode.
The configuration file must be named insight_intent.json.
The configuration file must be stored in resources/base/profile.
Key fields in the configuration file must comply with the corresponding constraints.

Binding an Intent to a UIExtensionAbility

Create a project by referring to the procedures provided in Binding an Intent to a UIAbility.

Example intent configuration:

{
  "insightIntents": [
    {
      "domain": "MusicDomain",
      "intentName": "PlayMusic",
      "intentVersion": "1.0.1",
      "srcEntry": "./ets/insightintents/ExtensionExecutor.ets",
      "uiExtension": {
        "ability": "MusicExtensionAbility"
      }
    }
  ]
}

Implementation of the intent executor:

import { InsightIntentExecutor, insightIntent, UIExtensionContentSession } from '@kit.AbilityKit';

export default class ExtensionExecutor extends InsightIntentExecutor {
  // The uiExtension is configured for the intent. Therefore, this API should be implemented.
  async onExecuteInUIExtensionAbility(name: string, param: Record<string, Object>,
    pageLoader: UIExtensionContentSession): Promise<insightIntent.ExecuteResult> {
    const result: insightIntent.ExecuteResult = {
      code: 0
    };
    return Promise.resolve(result);
  }
}

The system entry point executes the intent via the UIExtensionComponent.

Binding an Intent to a ServiceExtensionAbility

Create a project by referring to the procedures provided in Binding an Intent to a UIAbility.

Example intent configuration:

{
  "insightIntents": [
    {
      "domain": "MusicDomain",
      "intentName": "PlayMusic",
      "intentVersion": "1.0.1",
      "srcEntry": "./ets/insightintents/DownloadExecutor.ets",
      "serviceExtension": {
        "ability": "DownloadService"
      }
    }
  ]
}

Implementation of the intent executor:

import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit';

export default class DownloadExecutor extends InsightIntentExecutor {
  // The serviceExtension is configured for the intent. Therefore, this API should be implemented.
  async onExecuteInServiceExtensionAbility(name: string,
    param: Record<string, Object>): Promise<insightIntent.ExecuteResult> {
    const result: insightIntent.ExecuteResult = {
      code: 0
    };
    return Promise.resolve(result);
  }
}

The system entry point executes this intent via startServiceExtensionAbility.

Binding an Intent to a Widget

Create a project by referring to the procedures provided in Binding an Intent to a UIAbility.

Example intent configuration:

{
  "insightIntents": [
    {
      "domain": "MusicDomain",
      "intentName": "PlayMusic",
      "intentVersion": "1.0.1",
      "srcEntry": "./ets/insightintents/WidgetExecutor.ets",
      "form": {
        "ability": "PlayerWidgetAbility",
        "formName": "mini_player"
      }
    }
  ]
}

The system entry point displays the widget content through the FormComponent.

Description of the insight_intent.json File

The intention configuration file insight_intent.json is located in the resources/base/profile directory of the project. It is used to declare intent configuration information. In this file, the insightIntents array contains all intention configurations developed through the configuration file. It contains the following properties.

Property	Description	Data Type	Optional
intentName	Intent name, which is the unique identifier of an intent. The value is a string starting with an uppercase letter and containing letters and digits.	String	No
domain	Domain name of the intent. It is used to categorize intents by domain (for example, video, music, and game).	String	No
intentVersion	Version number of the intent. It is used to distinguish and manage intents when their capabilities evolve. The value is a three-part data sequence separated by dots, for example, 1.0.1.	String	No
srcEntry	Relative path of the intent execution file. The value is a string with a maximum of 127 bytes.	String	No
uiAbility	Information about the UIAbility bound to the intent. It contains the ability and executeMode fields. - ability: mandatory; name of the UIAbility. The value must be the same as that of name in the abilities tag of the module.json5 file. - executeMode: mandatory; execution mode. The value can be foreground or background. - foreground: The intent logic can be executed when the UIAbility is launched in the foreground. - background: The intent logic can be executed when the UIAbility is launched in the background.	Object	Yes
serviceExtension	Information about the ServiceExtensionAbility bound to the intent. It contains only the ability field, which is mandatory and specifies the name of the ServiceExtensionAbility. The value must be the same as that of name in the extensionAbilities tag of the module.json5 file.	Object	Yes
uiExtension	Information about the UIExtensionAbility bound to the intent. It contains only the ability field, which is mandatory and specifies the name of the UIExtensionAbility. The value must be the same as that of name in the extensionAbilities tag of the module.json5 file.	Object	Yes
form	Information about the widget bound to the intent. It contains the ability and formName fields. - ability: mandatory; name of the FormExtensionAbility. The value must be the same as that of name in the extensionAbilities tag of the module.json5 file. - formName: mandatory; widget name. The value must be the same as that of name in Widget Configuration.	Object	Yes
displayName	Display name of the intent.	String	Yes
displayDescription	Display description of the intent.	String	Yes
icon	Icon of the intent. It supports both network and local resources.	String	Yes
keywords	Search keywords for the intent.	String array	Yes
inputParams	Data format of intent parameters. It is used to define the input data format during intent calls.	Object	Yes
outputParams	Data format for the results returned by intent calls. It defines how the data should be structured.	Object	Yes
entities	Intent entities for data transfer.	Object	Yes