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. A system application supports a maximum of 10,000 valid reminders. The entire system supports a maximum of 12,000 valid reminders. (A reminder is considered valid as long as it is published.)
18
19- **Redirection limit**: The application that is redirected to upon a click on the notification must be the application that requested the agent-powered reminder.
20
21<!--RP2--><!--RP2End-->
22
23
24## Available APIs
25
26The 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).
27
28**Table 1** Main APIs for agent-powered reminders
29
30| API| Description|
31| -------- | -------- |
32| publishReminder(reminderReq: ReminderRequest): Promise&lt;number&gt; | Publishes a reminder.|
33| cancelReminder(reminderId: number): Promise&lt;void&gt; | Cancels a reminder.|
34| getValidReminders(): Promise&lt;Array&lt;ReminderRequest&gt;&gt; | Obtains all valid reminders set by the current application.|
35| cancelAllReminders(): Promise&lt;void&gt; | Cancels all reminders set by the current application.|
36| addNotificationSlot(slot: NotificationSlot): Promise&lt;void&gt; | Adds a notification slot.|
37| removeNotificationSlot(slotType: notification.SlotType): Promise&lt;void&gt; | Removes a notification slot.|
38
39
40## How to Develop
41
421. Declare the **ohos.permission.PUBLISH_AGENT_REMINDER** permission. For details, see [Declaring Permissions](../security/AccessToken/declare-permissions.md).
43
442. [Request notification authorization](../notification/notification-enable.md). Agent-powered reminders can be used only after being authorized by the user.
45
463. Import the modules.
47   
48   ```ts
49   import { reminderAgentManager } from '@kit.BackgroundTasksKit';
50   import { notificationManager } from '@kit.NotificationKit';
51   import { BusinessError } from '@kit.BasicServicesKit';
52   ```
53
544. Define a reminder. You can define the following types of reminders based on project requirements.
55
56   - Timer
57     
58      ```ts
59      let targetReminderAgent: reminderAgentManager.ReminderRequestTimer = {
60        reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER,   // The reminder type is timer.
61        triggerTimeInSeconds: 10,
62        actionButton: [ // Set the button type and title displayed for the reminder in the notification panel.
63          {
64            title: 'close',
65            type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
66          }
67        ],
68        wantAgent: {     // Information about the target UIAbility that is displayed after the reminder notification is touched.
69          pkgName: 'com.example.myapplication',
70          abilityName: 'EntryAbility'
71        },
72        maxScreenWantAgent: { // Information about the target UIAbility that is automatically started when the specified reminder time arrives is displayed in full screen.
73          pkgName: 'com.example.myapplication',
74          abilityName: 'EntryAbility'
75        },
76        title: 'this is title', // Reminder title.
77        content: 'this is content', // Reminder content.
78        expiredContent: 'this reminder has expired', // Content to be displayed after the reminder expires.
79        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.
80        slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // Type of the slot used by the reminder.
81      }
82      ```
83
84   - Calendar
85     
86      ```ts
87      let targetReminderAgent: reminderAgentManager.ReminderRequestCalendar = {
88        reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_CALENDAR, // The reminder type is calendar.
89        dateTime: {   // Reminder time.
90          year: 2023,
91          month: 1,
92          day: 1,
93          hour: 11,
94          minute: 14,
95          second: 30
96        },
97        repeatMonths: [1], // Month in which the reminder repeats.
98        repeatDays: [1], // Date on which the reminder repeats.
99        actionButton: [ // Set the button type and title displayed for the reminder in the notification panel.
100          {
101            title: 'close',
102            type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
103          },
104          {
105            title: 'snooze',
106            type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
107          },
108        ],
109        wantAgent: { // Information about the target UIAbility that is displayed after the reminder notification is touched.
110          pkgName: 'com.example.myapplication',
111          abilityName: 'EntryAbility'
112        },
113        maxScreenWantAgent: { // Information about the target UIAbility that is automatically started when the specified reminder time arrives is displayed in full screen.
114          pkgName: 'com.example.myapplication',
115          abilityName: 'EntryAbility'
116        },
117        ringDuration: 5, // Ringing duration, in seconds.
118        snoozeTimes: 2, // Number of reminder snooze times.
119        timeInterval: 5*60, // Reminder snooze interval, in seconds.
120        title: 'this is title', // Reminder title.
121        content: 'this is content', // Reminder content.
122        expiredContent: 'this reminder has expired', // Content to be displayed after the reminder expires.
123        snoozeContent: 'remind later', // Content to be displayed when the reminder is snoozed.
124        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.
125        slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // Type of the slot used by the reminder.
126      }
127      ```
128
129   - Alarm
130   
131      ```ts
132      let targetReminderAgent: reminderAgentManager.ReminderRequestAlarm = {
133        reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM, // The reminder type is alarm.
134        hour: 23, // Hour portion of the reminder time.
135        minute: 9, // Minute portion of the reminder time.
136        daysOfWeek: [2], // Days of a week when the reminder repeats..
137        actionButton: [ // Set the button type and title displayed for the reminder in the notification panel.
138          {
139            title: 'close',
140            type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
141          },
142          {
143            title: 'snooze',
144            type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
145          },
146        ],
147        wantAgent: { // Information about the target UIAbility that is displayed after the reminder notification is touched.
148          pkgName: 'com.example.myapplication',
149          abilityName: 'EntryAbility'
150        },
151        maxScreenWantAgent: { // Information about the target UIAbility that is automatically started when the specified reminder time arrives is displayed in full screen.
152          pkgName: 'com.example.myapplication',
153          abilityName: 'EntryAbility'
154        },
155        ringDuration: 5, // Ringing duration, in seconds.
156        snoozeTimes: 2, // Number of reminder snooze times.
157        timeInterval: 5*60, // Reminder snooze interval, in seconds.
158        title: 'this is title', // Reminder title.
159        content: 'this is content', // Reminder content.
160        expiredContent: 'this reminder has expired', // Content to be displayed after the reminder expires.
161        snoozeContent: 'remind later', // Content to be displayed when the reminder is snoozed.
162        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.
163        slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // Type of the slot used by the reminder.
164      }
165      ```
166
1675. Publish the reminder. After the reminder is published, your application can use the agent-powered reminder feature.
168   
169   ```ts
170    reminderAgentManager.publishReminder(targetReminderAgent).then((res: number) => {
171      console.info('Succeeded in publishing reminder. ');
172      let reminderId: number = res; // ID of the published reminder.
173    }).catch((err: BusinessError) => {
174      console.error(`Failed to publish reminder. Code: ${err.code}, message: ${err.message}`);
175    })
176   ```
177
1786. Delete the reminder as required.
179   
180   ```ts
181    let reminderId: number = 1;
182    // The reminder ID is obtained from the callback after the reminder is published.
183    reminderAgentManager.cancelReminder(reminderId).then(() => {
184      console.log('Succeeded in canceling reminder.');
185    }).catch((err: BusinessError) => {
186      console.error(`Failed to cancel reminder. Code: ${err.code}, message: ${err.message}`);
187    });
188   ```
189
190