• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Adding a WantAgent Object to a Notification
2
3A **WantAgent** 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 [WantAgent](../reference/apis/js-apis-wantAgent.md).
15
16| Name| 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. Import the modules.
28
29   ```ts
30   import NotificationManager from '@ohos.notificationManager';
31   import wantAgent from '@ohos.app.ability.wantAgent';
32   ```
33
342. Create a **WantAgentInfo** object.
35
36   Scenario 1: Create a [WantAgentInfo](../reference/apis/js-apis-inner-wantAgent-wantAgentInfo.md) object for starting a UIAbility component.
37
38   ```ts
39   let wantAgentObj = null; // Save the WantAgent object created. It will be used to complete the trigger operations.
40
41   // Set the action type through operationType of WantAgentInfo.
42   let wantAgentInfo = {
43       wants: [
44           {
45               deviceId: '',
46               bundleName: 'com.example.test',
47               abilityName: 'com.example.test.MainAbility',
48               action: '',
49               entities: [],
50               uri: '',
51               parameters: {}
52           }
53       ],
54       operationType: wantAgent.OperationType.START_ABILITY,
55       requestCode: 0,
56       wantAgentFlags:[wantAgent.WantAgentFlags.CONSTANT_FLAG]
57   }
58   ```
59
60   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).
61
62   ```ts
63   let wantAgentObj = null; // Save the WantAgent object created. It will be used to complete the trigger operations.
64
65   // Set the action type through operationType of WantAgentInfo.
66   let wantAgentInfo = {
67       wants: [
68           {
69               action: 'event_name', // Set the action name.
70               parameters: {},
71           }
72       ],
73       operationType: wantAgent.OperationType.SEND_COMMON_EVENT,
74       requestCode: 0,
75       wantAgentFlags: [wantAgent.WantAgentFlags.CONSTANT_FLAG],
76   }
77   ```
78
793. Create a **WantAgent** object.
80
81   ```ts
82   // Create a WantAgent object.
83   wantAgent.getWantAgent(wantAgentInfo, (err, data) => {
84       if (err) {
85           console.error('[WantAgent]getWantAgent err=' + JSON.stringify(err));
86       } else {
87           console.info('[WantAgent]getWantAgent success');
88           wantAgentObj = data;
89       }
90   });
91   ```
92
934. Create a **NotificationRequest** object.
94
95   ```ts
96   // Create a NotificationRequest object.
97   let notificationRequest = {
98       content: {
99           contentType: NotificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
100           normal: {
101               title: 'Test_Title',
102               text: 'Test_Text',
103               additionalText: 'Test_AdditionalText',
104           },
105       },
106       id: 1,
107       label: 'TEST',
108       wantAgent: wantAgentObj,
109   }
110   ```
111
1125. Publish a notification that carries the **WantAgent** object.
113
114   ```ts
115   // Publish a notification.
116   NotificationManager.publish(notificationRequest, (err) => {
117       if (err) {
118           console.error(`[ANS] failed to publish, error[${err}]`);
119           return;
120       }
121       console.info(`[ANS] publish success `);
122   });
123   ```
124
1256. When the user touches the notification from the notification panel, the system automatically triggers the action specified in the **WantAgent** object.
126
127   ```ts
128   // Trigger the WantAgent object.
129   let triggerInfo = {
130       code: 0
131   }
132   wantAgent.trigger(wantAgentObj, triggerInfo, (completeData) => {
133       console.info('[WantAgent]getWantAgent success, completeData: ',  + JSON.stringify(completeData));
134   });
135   ```
136