Agent-Powered Scheduled Reminder Development

When to Use

You can set your application to call the ReminderRequest class to create scheduled reminders for countdown timers, calendar events, and alarm clocks. When the created reminders are published, the timing and pop-up notification functions of your application will be taken over by the reminder agent in the background, even when your application is frozen or exits.

Available APIs

reminderAgent encapsulates the methods for publishing and canceling reminders.

Table 1 Major APIs in reminderAgent

ActionButtonType enumerates types of buttons displayed in a reminder notification.

Table 2 ActionButtonType enumeration

ReminderType enumerates the reminder types.

Table 3 ReminderType enumeration

ActionButton defines a button displayed in the reminder notification.

Table 4 ActionButton instance

WantAgent sets the package and ability that are redirected to when the reminder notification is clicked.

Table 5 WantAgent instance

MaxScreenWantAgent sets the name of the target package and ability to start automatically when the reminder arrives and the device is not in use. If the device is in use, a notification will be displayed.

Table 6 MaxScreenWantAgent instance

ReminderRequest defines the reminder to publish.

Table 7 ReminderRequest instance

ReminderRequestCalendar extends ReminderRequest and defines a reminder for a calendar event.

For the application to run properly, if both repeatMonths and repeatDays are not specified, the earliest reminder time must be later than the current time.

Table 8 ReminderRequestCalendar instance

ReminderRequestAlarm extends ReminderRequest and defines a reminder for the alarm clock.

Table 9 ReminderRequestAlarm instance

ReminderRequestTimer extends ReminderRequest and defines a reminder for a scheduled timer.

Table 10 ReminderRequestTimer instance

LocalDateTime defines a LocalDateTime instance.

Table 11 LocalDateTime instance

How to Develop

NOTE To publish a reminder, your application needs to apply for the ohos.permission.PUBLISH_AGENT_REMINDER permission.

Publish a 10-second countdown reminder.

1. Define a countdown timer instance.

   import reminderAgent from '@ohos.reminderAgent';
   import notification from '@ohos.notification';
   export default {
       // In JS Project:
       // timer: {
       // In eTS Project:
       let timer : reminderAgent.ReminderRequestTimer = {
           reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER,
           triggerTimeInSeconds: 10,
           actionButton: [
               {
                   title: "close",
                   type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
               }
           ],
           wantAgent: {
               pkgName: "com.example.device",
               abilityName: "com.example.device.MainAbility"
           },
           maxScreenWantAgent: {
               pkgName: "com.example.device",
               abilityName: "com.example.device.MainAbility"
           },
           title: "this is title",
           content: "this is content",
           expiredContent: "this reminder has expired",
           notificationId: 100,
           slotType: notification.SlotType.SOCIAL_COMMUNICATION
       }
   }
   

2. Publish the reminder.

   startTimer() {
       reminderAgent.publishReminder(this.timer, (err, reminderId) =>{
           this.printInfo(JSON.stringify(err));
           this.printInfo("reminderId:" + reminderId);
       });
   }
   

   HML page code:

   <div class="container">
       <button type="text" value="publishReminder" onclick="startTimer"></button>
   </div>
   

Sample code for defining a calendar reminder instance:

// In JS Project:
// calendar: {
// In eTS Project:
let calendar : reminderAgent.ReminderRequestCalendar = {
    reminderType: reminderAgent.ReminderType.REMINDER_TYPE_CALENDAR,
    dateTime: {
        year: 2050,
        month: 7,
        day: 30,
        hour: 11,
        minute: 14,
        second: 30
    },
    repeatMonths: [1],
    repeatDays: [1],
    actionButton: [
        {
            title: "close",
            type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
        },
        {
            title: "snooze",
            type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
        },
    ],
    wantAgent: {
        pkgName: "com.example.device",
        abilityName: "com.example.device.MainAbility"
    },
    maxScreenWantAgent: {
        pkgName: "com.example.device",
        abilityName: "com.example.device.MainAbility"
    },
    ringDuration: 5,
    snoozeTimes: 2,
    timeInterval: 5,
    title: "this is title",
    content: "this is content",
    expiredContent: "this reminder has expired",
    snoozeContent: "remind later",
    notificationId: 100,
    slotType: notification.SlotType.SOCIAL_COMMUNICATION
}

Sample code for defining an alarm reminder instance:

// In JS Project:
// alarm: {
// In eTS Project:
let alarm : reminderAgent.ReminderRequestAlarm = {
    reminderType: reminderAgent.ReminderType.REMINDER_TYPE_ALARM,
    hour: 11,
    minute: 14,
    daysOfWeek: [0],
    actionButton: [
        {
            title: "close",
            type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
        },
        {
            title: "snooze",
            type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
        },
    ],
    wantAgent: {
        pkgName: "com.example.device",
        abilityName: "com.example.device.MainAbility"
    },
    maxScreenWantAgent: {
        pkgName: "com.example.device",
        abilityName: "com.example.device.MainAbility"
    },
    ringDuration: 5,
    snoozeTimes: 2,
    timeInterval: 5,
    title: "this is title",
    content: "this is content",
    expiredContent: "this reminder has expired",
    snoozeContent: "remind later",
    notificationId: 100,
    slotType: notification.SlotType.SOCIAL_COMMUNICATION
}