1# @ohos.app.ability.InsightIntentExecutor (Base Class for InsightIntent Call Execution)
2
3The **InsightIntentExecutor** module provides the base class for InsightIntent call execution. Through this base class, you can access the InsightIntent framework on the device side. You need to implement the service logic to respond to InsightIntent calls. To access the InsightIntent framework, you need to declare the InsightIntent name and InsightIntent access mode in the InsightIntent configuration file. The system calls the InsightIntent based on the user interaction and InsightIntent configuration file and triggers the corresponding InsightIntent call execution callback.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> The APIs of this module can be used only in the stage model.
10
11## Modules to Import
12
13```ts
14import { InsightIntentExecutor } from '@kit.AbilityKit';
15```
16
17## Properties
18
19**Model restriction**: This API can be used only in the stage model.
20
21**Atomic service API**: This API can be used in atomic services since API version 11.
22
23**System capability**: SystemCapability.Ability.AbilityRuntime.Core
24
25| Name| Type| Read-only| Optional| Description|
26| -------- | -------- | -------- | -------- | -------- |
27| context | [InsightIntentContext](js-apis-app-ability-insightIntentContext.md) | No| No| InsightIntent call execution context.|
28
29## InsightIntentExecutor.onExecuteInUIAbilityForegroundMode
30
31onExecuteInUIAbilityForegroundMode(name: string, param: Record<string, Object>, pageLoader: window.WindowStage):
32  insightIntent.ExecuteResult | Promise<insightIntent.ExecuteResult>
33
34Called when the InsightIntent call displays a UIAbility in the foreground. Both synchronous calls and asynchronous calls using Promise are supported.
35
36**Model restriction**: This API can be used only in the stage model.
37
38**Atomic service API**: This API can be used in atomic services since API version 11.
39
40**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
41
42**Parameters**
43
44| Name| Type| Mandatory| Description|
45| -------- | -------- | -------- | -------- |
46| name | string | Yes| InsightIntent name.|
47| param | Record<string, Object> | Yes| InsightIntent call parameter.|
48| pageLoader | [window.WindowStage](../apis-arkui/js-apis-window.md#windowstage9) | Yes| Page loader.|
49
50**Return value**
51
52| Type| Description|
53| -------- | -------- |
54| [insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult) | InsightIntent call execution result.|
55| Promise<[insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult)> | Promise used to return the InsightIntent call execution result.|
56
57**Example**
58
59The code snippet below shows the synchronous call that returns the InsightIntent call result:
60  ```ts
61  import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit';
62  import { window } from '@kit.ArkUI';
63  import { hilog } from '@kit.PerformanceAnalysisKit';
64
65  export default class IntentExecutorImpl extends InsightIntentExecutor {
66    onExecuteInUIAbilityForegroundMode(name: string, param: Record<string, Object>, pageLoader: window.WindowStage): insightIntent.ExecuteResult {
67      let result: insightIntent.ExecuteResult;
68      if (name !== 'SupportedInsightIntentName') {
69        hilog.warn(0x0000, 'testTag', 'Unsupported insight intent %{public}s', name);
70        result = {
71          // decided by developer
72          code: 404,
73          result: {
74            message: 'Unsupported insight intent.',
75          }
76        };
77        return result;
78      }
79
80      // if developer need load content
81      pageLoader.loadContent('pages/Index', (err, data) => {
82        if (err.code) {
83          hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
84        } else {
85          hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in loading the content');
86        }
87      });
88
89      result = {
90        code: 0,
91        result: {
92          message: 'Execute insight intent succeed.',
93        }
94      };
95      return result;
96    }
97  }
98  ```
99
100The code snippet below shows the promise-based asynchronous call that returns the InsightIntent call result:
101  ```ts
102  import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit';
103  import { window } from '@kit.ArkUI';
104  import { hilog } from '@kit.PerformanceAnalysisKit';
105
106  async function executeInsightIntent(param: Record<string, Object>): Promise<insightIntent.ExecuteResult> {
107    return new Promise((resolve, reject) => {
108      let result: insightIntent.ExecuteResult = {
109        code: 0,
110        result: {
111          message: 'Execute insight intent succeed.',
112        }
113      };
114      resolve(result);
115    })
116  }
117
118  export default class IntentExecutorImpl extends InsightIntentExecutor {
119    async onExecuteInUIAbilityForegroundMode(name: string, param: Record<string, Object>, pageLoader: window.WindowStage): Promise<insightIntent.ExecuteResult> {
120      let result: insightIntent.ExecuteResult;
121      if (name !== 'SupportedInsightIntentName') {
122        hilog.warn(0x0000, 'testTag', 'Unsupported insight intent %{public}s', name);
123        result = {
124          // decided by developer
125          code: 404,
126          result: {
127            message: 'Unsupported insight intent.',
128          }
129        };
130        return result;
131      }
132
133      result = await executeInsightIntent(param);
134      return result;
135    }
136  }
137  ```
138
139## InsightIntentExecutor.onExecuteInUIAbilityBackgroundMode
140
141onExecuteInUIAbilityBackgroundMode(name: string, param: Record<string, Object>):
142    insightIntent.ExecuteResult | Promise<insightIntent.ExecuteResult>
143
144Called when the InsightIntent call displays a UIAbility in the background. Both synchronous calls and asynchronous calls using Promise are supported.
145
146**Model restriction**: This API can be used only in the stage model.
147
148**Atomic service API**: This API can be used in atomic services since API version 11.
149
150**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
151
152**Parameters**
153
154| Name| Type| Mandatory| Description|
155| -------- | -------- | -------- | -------- |
156| name | string | Yes| InsightIntent name.|
157| param | Record<string, Object> | Yes| InsightIntent call parameter.|
158
159**Return value**
160
161| Type| Description|
162| -------- | -------- |
163| [insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult) | InsightIntent call execution result.|
164| Promise<[insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult)> | Promise used to return the InsightIntent call execution result.|
165
166**Example**
167
168The code snippet below shows the synchronous call that returns the InsightIntent call result:
169  ```ts
170  import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit';
171
172  export default class IntentExecutorImpl extends InsightIntentExecutor {
173    onExecuteInUIAbilityBackgroundMode(name: string, param: Record<string, Object>): insightIntent.ExecuteResult {
174      let result: insightIntent.ExecuteResult = {
175        code: 0,
176        result: {
177          message: 'Execute insight intent succeed.',
178        }
179      };
180      return result;
181    }
182  }
183  ```
184
185The code snippet below shows the promise-based asynchronous call that returns the InsightIntent call result:
186  ```ts
187  import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit';
188
189  async function executeInsightIntent(param: Record<string, Object>): Promise<insightIntent.ExecuteResult> {
190    return new Promise((resolve, reject) => {
191      let result: insightIntent.ExecuteResult = {
192        code: 0,
193        result: {
194          message: 'Execute insight intent succeed.',
195        }
196      };
197      resolve(result);
198    })
199  }
200
201  export default class IntentExecutorImpl extends InsightIntentExecutor {
202    async onExecuteInUIAbilityBackgroundMode(name: string, param: Record<string, Object>): Promise<insightIntent.ExecuteResult> {
203      let result: insightIntent.ExecuteResult = await executeInsightIntent(param);
204      return result;
205    }
206  }
207  ```
208
209## InsightIntentExecutor.onExecuteInUIExtensionAbility
210
211onExecuteInUIExtensionAbility(name: string, param: Record<string, Object>, pageLoader: UIExtensionContentSession):
212  insightIntent.ExecuteResult | Promise<insightIntent.ExecuteResult>
213
214Called when the InsightIntent call starts a UIExtensionAbility. Both synchronous calls and asynchronous calls using Promise are supported.
215
216**Model restriction**: This API can be used only in the stage model.
217
218**System capability**: SystemCapability.Ability.AbilityRuntime.Core
219
220**Parameters**
221
222| Name| Type| Mandatory| Description|
223| -------- | -------- | -------- | -------- |
224| name | string | Yes| InsightIntent name.|
225| param | Record<string, Object> | Yes| InsightIntent call parameter.|
226| pageLoader | [UIExtensionContentSession](js-apis-app-ability-uiExtensionContentSession.md) | Yes| Page loader.|
227
228**Return value**
229
230| Type| Description|
231| -------- | -------- |
232| [insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult) | InsightIntent call execution result.|
233| Promise<[insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult)> | Promise used to return the InsightIntent call execution result.|
234
235**Example**
236
237The code snippet below shows the synchronous call that returns the InsightIntent call result:
238  ```ts
239  import { InsightIntentExecutor, insightIntent, UIExtensionContentSession } from '@kit.AbilityKit';
240  import { hilog } from '@kit.PerformanceAnalysisKit';
241
242  export default class IntentExecutorImpl extends InsightIntentExecutor {
243    onExecuteInUIExtensionAbility(name: string, param: Record<string, Object>, pageLoader: UIExtensionContentSession): insightIntent.ExecuteResult {
244      let result: insightIntent.ExecuteResult;
245      if (name !== 'SupportedInsightIntentName') {
246        hilog.warn(0x0000, 'testTag', 'Unsupported insight intent %{public}s', name);
247        result = {
248          // decided by developer
249          code: 404,
250          result: {
251            message: 'Unsupported insight intent.',
252          }
253        };
254        return result;
255      }
256
257      // if developer need load content
258      pageLoader.loadContent('pages/Index');
259
260      result = {
261        code: 0,
262        result: {
263          message: 'Execute insight intent succeed.',
264        }
265      };
266      return result;
267    }
268  }
269  ```
270
271The code snippet below shows the promise-based asynchronous call that returns the InsightIntent call result:
272  ```ts
273  import { InsightIntentExecutor, insightIntent, UIExtensionContentSession } from '@kit.AbilityKit';
274  import { hilog } from '@kit.PerformanceAnalysisKit';
275
276  async function executeInsightIntent(param: Record<string, Object>): Promise<insightIntent.ExecuteResult> {
277    return new Promise((resolve, reject) => {
278      let result: insightIntent.ExecuteResult = {
279        code: 0,
280        result: {
281          message: 'Execute insight intent succeed.',
282        }
283      };
284      resolve(result);
285    })
286  }
287
288  export default class IntentExecutorImpl extends InsightIntentExecutor {
289    async onExecuteInUIExtensionAbility(name: string, param: Record<string, Object>, pageLoader: UIExtensionContentSession): Promise<insightIntent.ExecuteResult> {
290      let result: insightIntent.ExecuteResult;
291      if (name !== 'SupportedInsightIntentName') {
292        hilog.warn(0x0000, 'testTag', 'Unsupported insight intent %{public}s', name);
293        result = {
294          // decided by developer
295          code: 404,
296          result: {
297            message: 'Unsupported insight intent.',
298          }
299        };
300        return result;
301      }
302
303      result = await executeInsightIntent(param);
304      return result;
305    }
306  }
307  ```
308
309## InsightIntentExecutor.onExecuteInServiceExtensionAbility
310
311onExecuteInServiceExtensionAbility(name: string, param: Record<string, Object>):
312    insightIntent.ExecuteResult | Promise<insightIntent.ExecuteResult>
313
314Called when the InsightIntent call starts a ServiceExtensionAbility. Both synchronous calls and asynchronous calls using Promise are supported.
315
316**Model restriction**: This API can be used only in the stage model.
317
318**System capability**: SystemCapability.Ability.AbilityRuntime.Core
319
320**Parameters**
321
322| Name| Type| Mandatory| Description|
323| -------- | -------- | -------- | -------- |
324| name | string | Yes| InsightIntent name.|
325| param | Record<string, Object> | Yes| InsightIntent call parameter.|
326
327**Return value**
328
329| Type| Description|
330| -------- | -------- |
331| [insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult) | InsightIntent call execution result.|
332| Promise<[insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult)> | Promise used to return the InsightIntent call execution result.|
333
334**Example**
335
336The code snippet below shows the synchronous call that returns the InsightIntent call result:
337  ```ts
338  import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit';
339  import { hilog } from '@kit.PerformanceAnalysisKit';
340
341  export default class IntentExecutorImpl extends InsightIntentExecutor {
342    onExecuteInServiceExtensionAbility(name: string, param: Record<string, Object>): insightIntent.ExecuteResult {
343      let result: insightIntent.ExecuteResult;
344      if (name !== 'SupportedInsightIntentName') {
345        hilog.warn(0x0000, 'testTag', 'Unsupported insight intent %{public}s', name);
346        result = {
347          // decided by developer
348          code: 404,
349          result: {
350            message: 'Unsupported insight intent.',
351          }
352        };
353        return result;
354      }
355
356      result = {
357        code: 0,
358        result: {
359          message: 'Execute insight intent succeed.',
360        }
361      };
362      return result;
363    }
364  }
365  ```
366
367The code snippet below shows the promise-based asynchronous call that returns the InsightIntent call result:
368  ```ts
369  import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit';
370  import { hilog } from '@kit.PerformanceAnalysisKit';
371
372  async function executeInsightIntent(param: Record<string, Object>): Promise<insightIntent.ExecuteResult> {
373    return new Promise((resolve, reject) => {
374      let result: insightIntent.ExecuteResult = {
375        code: 0,
376        result: {
377          message: 'Execute insight intent succeed.',
378        }
379      };
380      resolve(result);
381    });
382  }
383
384  export default class IntentExecutorImpl extends InsightIntentExecutor {
385    async onExecuteInServiceExtensionAbility(name: string, param: Record<string, Object>): Promise<insightIntent.ExecuteResult> {
386      let result: insightIntent.ExecuteResult;
387      if (name !== 'SupportedInsightIntentName') {
388        hilog.warn(0x0000, 'testTag', 'Unsupported insight intent %{public}s', name);
389        result = {
390          // decided by developer
391          code: 404,
392          result: {
393            message: 'Unsupported insight intent.',
394          }
395        };
396        return result;
397      }
398
399      result = await executeInsightIntent(param);
400      return result;
401    }
402  }
403  ```
404