Background Reminders and Agent-powered Reminders: Intelligent Reminder Management in HarmonyOS Next

This article aims to deeply explore the technical details of Huawei's HarmonyOS Next system (as of API 12 currently) and is summarized based on actual development practices. It is mainly used as a carrier for technical sharing and exchange. Inevitable errors and omissions may exist. Colleagues are welcome to put forward valuable opinions and questions for common progress. This article is original content. Any form of reprint must indicate the source and original author.

In mobile application development, timely and effective reminder functions are crucial for improving user experience. HarmonyOS Next provides the Agent-powered Reminder function, which allows the system to execute reminder tasks on behalf of the application after the application is suspended or the process is terminated in the background, such as countdowns, calendars, alarms, and more. This mechanism can ensure that users receive important reminder information in a timely manner while avoiding excessive consumption of device resources by applications.

Types and development steps of agent-powered reminders

HarmonyOS Next supports three types of agent-powered reminders:

Countdown reminder: A reminder function based on countdown, such as reminding the user after 10 seconds of countdown.
Calendar reminder: A reminder function based on calendar events, such as reminding the user at a specific date and time.
Alarm reminder: A reminder function based on the clock, such as reminding the user to get up at 7 am every day.

Development steps:

Apply for permissions: Add the ohos.permission.PUBLISH_AGENT_REMINDER permission in the application configuration file.
Request notification authorization: Only after obtaining user authorization can the agent-powered reminder function be used.
Define reminder content: Define the countdown, calendar, or alarm reminder content as needed, including reminder title, content, expired content, notification channel, and more.
Publish reminder: Call the publishReminder interface to publish the reminder task.
Cancel reminder: Call the cancelReminder or cancelAllReminders interface to cancel the reminder task as needed.

Code examples: Setting up countdown reminders, calendar reminders, and alarm reminders

The following code examples show how to set up three types of agent-powered reminders:

Countdown reminder:

import { reminderAgentManager } from '@kit.BackgroundTasksKit';
import { notificationManager } from '@kit.NotificationKit';
let targetReminderAgent: reminderAgentManager.ReminderRequestTimer = {
  reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER,
  triggerTimeInSeconds: 10,
  actionButton: [{ title: 'close', type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE }],
  wantAgent: { pkgName: 'com.example.myapplication', abilityName: 'EntryAbility' },
  maxScreenWantAgent: { pkgName: 'com.example.myapplication', abilityName: 'EntryAbility' },
  title: 'this is title',
  content: 'this is content',
  expiredContent: 'this reminder has expired',
  notificationId: 100,
  slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION
};
reminderAgentManager.publishReminder(targetReminderAgent).then((res: number) => {
  console.info('Succeeded in publishing reminder. ');
  let reminderId: number = res; // Published reminder ID
}).catch((err: BusinessError) => {
  console.error(`Failed to publish reminder. Code: ${err.code}, message: ${err.message}`);
});

Calendar reminder:

import { reminderAgentManager } from '@kit.BackgroundTasksKit';
import { notificationManager } from '@kit.NotificationKit';
let targetReminderAgent: reminderAgentManager.ReminderRequestCalendar = {
  reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_CALENDAR,
  dateTime: {
    year: 2023,
    month: 1,
    day: 1,
    hour: 11,
    minute: 14,
    second: 30
  },
  repeatMonths: [1],
  repeatDays: [1],
  actionButton: [
    { title: 'close', type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE },
    { title: 'snooze', type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE }
  ],
  wantAgent: { pkgName: 'com.example.myapplication', abilityName: 'EntryAbility' },
  maxScreenWantAgent: { pkgName: 'com.example.myapplication', abilityName: 'EntryAbility' },
  ringDuration: 5,
  snoozeTimes: 2,
  timeInterval: 5 * 60,
  title: 'this is title',
  content: 'this is content',
  expiredContent: 'this reminder has expired',
  snoozeContent: 'remind later',
  notificationId: 100,
  slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION
};
reminderAgentManager.publishReminder(targetReminderAgent).then((res: number) => {
  console.info('Succeeded in publishing reminder. ');
  let reminderId: number = res; // Published reminder ID
}).catch((err: BusinessError) => {
  console.error(`Failed to publish reminder. Code: ${err.code}, message: ${err.message}`);
});

Alarm reminder:

import { reminderAgentManager } from '@kit.BackgroundTasksKit';
import { notificationManager } from '@kit.NotificationKit';
let targetReminderAgent: reminderAgentManager.ReminderRequestAlarm = {
  reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM,
  hour: 23,
  minute: 9,
  daysOfWeek: [2],
  actionButton: [
    { title: 'close', type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE },
    { title: 'snooze', type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE }
  ],
  wantAgent: { pkgName: 'com.example.myapplication', abilityName: 'EntryAbility' },
  maxScreenWantAgent: { pkgName: 'com.example.myapplication', abilityName: 'EntryAbility' },
  ringDuration: 5,
  snoozeTimes: 2,
  timeInterval: 5 * 60,
  title: 'this is title',
  content: 'this is content',
  expiredContent: 'this reminder has expired',
  snoozeContent: 'remind later',
  notificationId: 99,
  slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION
};
reminderAgentManager.publishReminder(targetReminderAgent).then((res: number) => {
  console.info('Succeeded in publishing reminder. ');
  let reminderId: number = res; // Published reminder ID
}).catch((err: BusinessError) => {
  console.error(`Failed to publish reminder. Code: ${err.code}, message: ${err.message}`);
});

Table: Comparison of agent-powered reminder types

Reminder type	Trigger method	Repeat setting	Notification button	Applicable scenario
Countdown reminder	End of countdown	Not supported	Close	Temporary reminder, such as meeting countdown
Calendar reminder	Specified date and time	Supported monthly or daily repetition	Close, snooze	Regular reminder, such as birthdays, anniversaries
Alarm reminder	Specified time	Supported weekly repetition	Close, snooze	Daily reminder, such as wake-up alarm

Notification management and optimization of reminders

Developers can use NotificationSlot to manage the styles and channels of reminder notifications. By setting different NotificationSlot, developers can create personalized and diverse notification styles and select appropriate channels for notification, such as system notification bar, desktop widgets, and more.

Code example:

import { notificationManager } from '@kit.NotificationKit';
let slot: notificationManager.Slot = {
  slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION,
  slotId: 1,
  name: 'My Notification Slot',
  importance: notificationManager.Importance.HIGH,
  description: 'This is my custom notification slot'
};
notificationManager.addNotificationSlot(slot).then(() => {
  console.info('Notification slot added successfully');
}).catch((err: BusinessError) => {
  console.error(`Failed to add notification slot. Code: ${err.code}, message: ${err.message}`);
});

Application method for agent-powered reminder permissions

To prevent the abuse of the agent-powered reminder function, HarmonyOS Next has imposed restrictions and specifications on it. Developers need to apply to Huawei official for agent-powered reminder permissions to use this function.

Application method:

Apply to Huawei official through the email address hwpush@huawei.com.
Email subject: 【Application for Agent-powered Reminder Permissions】.
Email body: Include information such as enterprise name, application name, application package name, usage scenario, notification title, notification text, notification scenario, and notification frequency.

Summary

Agent-powered reminders provide an intelligent reminder management method for HarmonyOS Next. It can effectively improve user experience and avoid excessive consumption of device resources by applications. We can choose the appropriate agent-powered reminder type according to actual needs and combine with NotificationSlot for notification management and optimization. At the same time, we also need to pay attention to the permission application and usage specifications of agent-powered reminders to avoid abusing this function.

Blog