1# Agent-powered Reminder (ArkTS)
2
3## Overview
4
5### Introduction
6
7After an application switches to the background or an application process is terminated, it may have scheduled tasks for reminding users, for example, flash sale reminders for shopping applications. To meet this requirement, the system provides agent-powered reminders (implemented by **reminderAgentManager**). When the application switches to the background or the process is terminated, the system sends reminders on behalf of the application. Currently, the following reminder types are supported: timer, calendar, and alarm.<!--RP1--><!--RP1End-->
8
9- Timer: reminders based on countdown timers
10
11- Calendar: reminders based on calendar events
12
13- Alarm: reminders based on alarm clocks
14
15### Constraints
16
17- **Quantity limit**: A third-party application supports a maximum of 30 valid reminders.<!--Del--> A system application supports a maximum of 10,000 valid reminders. The entire system supports a maximum of 12,000 valid reminders.<!--DelEnd-->
18
19   > **NOTE**
20   >
21   > When the reminder time arrives, the notification center displays the relevant reminder. The reminder remains active and unexpired unless the user touches the CLOSE button, at which point the reminder becomes expired.
22   >
23   > For a recurring reminder (for example, a daily reminder), the reminder is always valid regardless of whether the user touches the CLOSE button.
24
25- **Redirection limit**: The application that is redirected to upon a click on the notification must be the application that requested the agent-powered reminder.
26
27<!--RP2--><!--RP2End-->
28
29
30## Available APIs
31
32The table below uses promise as an example to describe the APIs used for developing agent-powered reminders. For details about more APIs and their usage, see [reminderAgentManager](../reference/apis-backgroundtasks-kit/js-apis-reminderAgentManager.md).
33
34**Table 1** Main APIs for agent-powered reminders
35
36| API| Description|
37| -------- | -------- |
38| publishReminder(reminderReq: ReminderRequest): Promise&lt;number&gt; | Publishes a reminder.|
39| cancelReminder(reminderId: number): Promise&lt;void&gt; | Cancels a reminder.|
40| getValidReminders(): Promise&lt;Array&lt;ReminderRequest&gt;&gt; | Obtains all valid reminders set by the current application.|
41| cancelAllReminders(): Promise&lt;void&gt; | Cancels all reminders set by the current application.|
42| addNotificationSlot(slot: NotificationSlot): Promise&lt;void&gt; | Adds a notification slot.|
43| removeNotificationSlot(slotType: notification.SlotType): Promise&lt;void&gt; | Removes a notification slot.|
44
45
46## How to Develop
47
481. Declare the **ohos.permission.PUBLISH_AGENT_REMINDER** permission. For details, see [Declaring Permissions](../security/AccessToken/declare-permissions.md).
49
502. [Request notification authorization](../notification/notification-enable.md). Agent-powered reminders can be used only after being authorized by the user.
51
523. Import the modules.
53
54   ```ts
55   import { reminderAgentManager } from '@kit.BackgroundTasksKit';
56   import { notificationManager } from '@kit.NotificationKit';
57   import { BusinessError } from '@kit.BasicServicesKit';
58   ```
59
604. Define a reminder. You can define the following types of reminders based on project requirements.
61
62   - Timer
63
64      ```ts
65      let targetReminderAgent: reminderAgentManager.ReminderRequestTimer = {
66        reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER,   // The reminder type is timer.
67        triggerTimeInSeconds: 10,
68        actionButton: [ // Set the button type and title displayed for the reminder in the notification panel.
69          {
70            title: 'close',
71            type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
72          }
73        ],
74        wantAgent: {     // Information about the target UIAbility that is displayed after the reminder notification is touched.
75          pkgName: 'com.example.myapplication',
76          abilityName: 'EntryAbility'
77        },
78        maxScreenWantAgent: { // Information about the target UIAbility that is automatically started when the specified reminder time arrives is displayed in full screen.
79          pkgName: 'com.example.myapplication',
80          abilityName: 'EntryAbility'
81        },
82        title: 'this is title', // Reminder title.
83        content: 'this is content', // Reminder content.
84        expiredContent: 'this reminder has expired', // Content to be displayed after the reminder expires.
85        notificationId: 100, // Notification ID used by the reminder. If there are reminders with the same notification ID, the later one will overwrite the earlier one.
86        slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // Type of the slot used by the reminder.
87      }
88      ```
89
90   - Calendar
91
92      ```ts
93      let targetReminderAgent: reminderAgentManager.ReminderRequestCalendar = {
94        reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_CALENDAR, // The reminder type is calendar.
95        dateTime: {   // Reminder time.
96          year: 2023,
97          month: 1,
98          day: 1,
99          hour: 11,
100          minute: 14,
101          second: 30
102        },
103        repeatMonths: [1], // Month in which the reminder repeats.
104        repeatDays: [1], // Date on which the reminder repeats.
105        actionButton: [ // Set the button type and title displayed for the reminder in the notification panel.
106          {
107            title: 'close',
108            type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
109          },
110          {
111            title: 'snooze',
112            type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
113          },
114        ],
115        wantAgent: { // Information about the target UIAbility that is displayed after the reminder notification is touched.
116          pkgName: 'com.example.myapplication',
117          abilityName: 'EntryAbility'
118        },
119        maxScreenWantAgent: { // Information about the target UIAbility that is automatically started when the specified reminder time arrives is displayed in full screen.
120          pkgName: 'com.example.myapplication',
121          abilityName: 'EntryAbility'
122        },
123        ringDuration: 5, // Ringing duration, in seconds.
124        snoozeTimes: 2, // Number of reminder snooze times.
125        timeInterval: 5*60, // Reminder snooze interval, in seconds.
126        title: 'this is title', // Reminder title.
127        content: 'this is content', // Reminder content.
128        expiredContent: 'this reminder has expired', // Content to be displayed after the reminder expires.
129        snoozeContent: 'remind later', // Content to be displayed when the reminder is snoozed.
130        notificationId: 100, // Notification ID used by the reminder. If there are reminders with the same notification ID, the later one will overwrite the earlier one.
131        slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // Type of the slot used by the reminder.
132      }
133      ```
134
135   - Alarm
136
137      ```ts
138      let targetReminderAgent: reminderAgentManager.ReminderRequestAlarm = {
139        reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM, // The reminder type is alarm.
140        hour: 23, // Hour portion of the reminder time.
141        minute: 9, // Minute portion of the reminder time.
142        daysOfWeek: [2], // Days of a week when the reminder repeats..
143        actionButton: [ // Set the button type and title displayed for the reminder in the notification panel.
144          {
145            title: 'close',
146            type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
147          },
148          {
149            title: 'snooze',
150            type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
151          },
152        ],
153        wantAgent: { // Information about the target UIAbility that is displayed after the reminder notification is touched.
154          pkgName: 'com.example.myapplication',
155          abilityName: 'EntryAbility'
156        },
157        maxScreenWantAgent: { // Information about the target UIAbility that is automatically started when the specified reminder time arrives is displayed in full screen.
158          pkgName: 'com.example.myapplication',
159          abilityName: 'EntryAbility'
160        },
161        ringDuration: 5, // Ringing duration, in seconds.
162        snoozeTimes: 2, // Number of reminder snooze times.
163        timeInterval: 5*60, // Reminder snooze interval, in seconds.
164        title: 'this is title', // Reminder title.
165        content: 'this is content', // Reminder content.
166        expiredContent: 'this reminder has expired', // Content to be displayed after the reminder expires.
167        snoozeContent: 'remind later', // Content to be displayed when the reminder is snoozed.
168        notificationId: 99, // Notification ID used by the reminder. If there are reminders with the same notification ID, the later one will overwrite the earlier one.
169        slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // Type of the slot used by the reminder.
170      }
171      ```
172
1735. Publish the reminder. After the reminder is published, your application can use the agent-powered reminder feature.
174
175   ```ts
176    reminderAgentManager.publishReminder(targetReminderAgent).then((res: number) => {
177      console.info('Succeeded in publishing reminder. ');
178      let reminderId: number = res; // ID of the published reminder.
179    }).catch((err: BusinessError) => {
180      console.error(`Failed to publish reminder. Code: ${err.code}, message: ${err.message}`);
181    })
182   ```
183
1846. Delete the reminder as required.
185
186   ```ts
187    let reminderId: number = 1;
188    // The reminder ID is obtained from the callback after the reminder is published.
189    reminderAgentManager.cancelReminder(reminderId).then(() => {
190      console.log('Succeeded in canceling reminder.');
191    }).catch((err: BusinessError) => {
192      console.error(`Failed to cancel reminder. Code: ${err.code}, message: ${err.message}`);
193    });
194   ```
195
196