• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Adding a WantAgent Object to a Notification
2
3A [WantAgent](../reference/apis/js-apis-app-ability-wantAgent.md) object encapsulates an intention to start a specified ability, release a common event, and more. In OpenHarmony, a **WantAgent** object can be passed in a notification from the publisher to the subscriber, so as to trigger the intention specified. For example, you may want the user to start a specific ability by touching the notification published by your application. In this case, you can add a **WantAgent** object that encapsulates such an action to the notification. After receiving the **WantAgent** object, the system triggers it once the user touches the notification from the notification panel, starting the specified ability.
4
5Below you can see the process of adding a **WantAgent** object to a notification. The notification publisher requests a **WantAgent** object from the Ability Manager Service (AMS), and then sends a notification carrying the **WantAgent** object to the home screen. When the user touches the notification from the notification panel on the home screen, the **WantAgent** object is triggered.
6
7**Figure 1** Publishing a notification with a WantAgent object
8
9![notification-with-wantagent](figures/notification-with-wantagent.png)
10
11
12## Available APIs
13
14For details about the APIs, see [@ohos.app.ability.wantAgent](../reference/apis/js-apis-app-ability-wantAgent.md).
15
16| API | Description|
17| -------- | -------- |
18| getWantAgent(info: WantAgentInfo, callback: AsyncCallback<WantAgent>): void | Creates a **WantAgent** object.|
19| trigger(agent: WantAgent, triggerInfo: TriggerInfo, callback?: Callback<CompleteData>): void | Triggers a **WantAgent** object.|
20| cancel(agent: WantAgent, callback: AsyncCallback<void>): void | Cancels a **WantAgent** object.|
21| getWant(agent: WantAgent, callback: AsyncCallback<Want>): void | Obtains a **WantAgent** object.|
22| equal(agent: WantAgent, otherAgent: WantAgent, callback: AsyncCallback<boolean>): void | Checks whether two **WantAgent** objects are equal.|
23
24
25## How to Develop
26
271. [Enable notification](notification-enable.md). An application can use the notification feature only after being authorized by the user.
28
292. Import the modules.
30
31   ```typescript
32   import notificationManager from '@ohos.notificationManager';
33   import wantAgent from '@ohos.app.ability.wantAgent';
34   import { WantAgent } from '@ohos.app.ability.wantAgent';
35   import Base from '@ohos.base';
36   ```
37
383. Create a **WantAgentInfo** object.
39
40   Scenario 1: Create a [WantAgentInfo](../reference/apis/js-apis-inner-wantAgent-wantAgentInfo.md) object for starting a UIAbility component.
41
42   ```typescript
43   let wantAgentObj:WantAgent; // Save the created WantAgent object for completing the trigger operations at a later time.
44
45   // Set the action type through operationType of WantAgentInfo.
46   let wantAgentInfo:wantAgent.WantAgentInfo = {
47     wants: [
48       {
49         deviceId: '',
50         bundleName: 'com.example.myapplication',
51         abilityName: 'EntryAbility',
52         action: '',
53         entities: [],
54         uri: '',
55         parameters: {}
56       }
57     ],
58     operationType: wantAgent.OperationType.START_ABILITY,
59     requestCode: 0,
60     wantAgentFlags:[wantAgent.WantAgentFlags.CONSTANT_FLAG]
61   };
62   ```
63
64   Scenario 2: Create a [WantAgentInfo](../reference/apis/js-apis-inner-wantAgent-wantAgentInfo.md) object for publishing a [common event](../application-models/common-event-overview.md).
65
66   ```typescript
67   let wantAgentObj:WantAgent; // Save the created WantAgent object for completing the trigger operations at a later time.
68
69   // Set the action type through operationType of WantAgentInfo.
70   let wantAgentInfo:wantAgent.WantAgentInfo = {
71     wants: [
72       {
73         action: 'event_name', // Set the action name.
74         parameters: {},
75       }
76     ],
77     operationType: wantAgent.OperationType.SEND_COMMON_EVENT,
78     requestCode: 0,
79     wantAgentFlags: [wantAgent.WantAgentFlags.CONSTANT_FLAG],
80   };
81   ```
82
834. Invoke the [getWantAgent()](../reference/apis/js-apis-app-ability-wantAgent.md#wantagentgetwantagent) API to create a **WantAgent** object.
84
85   ```typescript
86   // Create a WantAgent object.
87   wantAgent.getWantAgent(wantAgentInfo, (err:Base.BusinessError, data:WantAgent) => {
88     if (err) {
89       console.error(`Failed to get want agent. Code is ${err.code}, message is ${err.message}`);
90       return;
91     }
92     console.info('Succeeded in geting want agent.');
93     wantAgentObj = data;
94   });
95   ```
96
975. Create a **NotificationRequest** object and publish a notification that carries the **WantAgent** object.
98
99   ```typescript
100   // Create a NotificationRequest object.
101   let notificationRequest: notificationManager.NotificationRequest = {
102     content: {
103       contentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
104       normal: {
105         title: 'Test_Title',
106         text: 'Test_Text',
107         additionalText: 'Test_AdditionalText',
108       },
109     },
110     id: 1,
111     label: 'TEST',
112     wantAgent: wantAgentObj,
113   }
114
115   notificationManager.publish(notificationRequest, (err:Base.BusinessError) => {
116     if (err) {
117       console.error(`Failed to publish notification. Code is ${err.code}, message is ${err.message}`);
118       return;
119     }
120     console.info('Succeeded in publishing notification.');
121   });
122   ```
123
1246. When the user touches the notification from the notification panel, the system automatically triggers the action specified in the **WantAgent** object.
125