Notification#

The Notification module in the Scripting app allows you to create, manage, and display local notifications with optional rich content and interactive actions. It provides APIs to schedule notifications, customize their appearance, and define actions that users can perform directly within the notification interface.

Table of Contents#

1. Scheduling Notifications
2. Fetching Notifications
3. Removing Notifications
4. Setting Badge Count
5. Displaying Custom UI for Rich Notifications
6. Accessing Notification Data in Custom UI

1. Scheduling Notifications#

The Notification.schedule method is used to schedule a local notification with various options, including custom actions and the ability to display a rich notification UI when expanded.

Method: Notification.schedule(options: NotificationScheduleOptions): Promise<boolean>

NotificationScheduleOptions#

Use this type to define the configuration for your notification:

1type NotificationScheduleOptions = {
2  title: string
3  subtitle?: string
4  body?: string
5  badge?: number
6  silent?: boolean
7  userInfo?: Record<string, any>
8  threadIdentifier?: string
9  triggerTime?: number
10  repeatsType?: 'hourly' | 'daily' | 'weekly' | 'monthly'
11  actions?: NotificationAction[]
12  customUI?: boolean
13}

NotificationAction#

1type NotificationAction = {
2  title: string          // Button title
3  url: string            // URL to open when tapped; supports Scripting URL scheme or https:// links
4  destructive?: boolean  // Optional: Marks the action as destructive
5}

Example with Custom UI and Actions:

Suppose we’re delivering a notification that reminds the user to drink water. In notification.tsx, we can display a custom interface with buttons to confirm that the user has taken action (e.g., "Drank Water") or to ignore the reminder. Additionally, we can set actions with NotificationAction to allow the user to perform similar tasks directly in the notification.

1// Hydration Reminder index.tsx
2
3await Notification.schedule({
4  title: "Hydration Reminder",
5  body: "Time to drink water!",
6  customUI: true,
7  repeatsType: "hourly", // remind once an hour
8  triggerTime: 
9  actions: [
10    {
11      title: "I Drank",
12      url: Script.createRunURLScheme("Hydration Reminder", {drank: true}),
13    },
14    {
15      title: "Ignore",
16      url: Script.createRunURLScheme("Hydration Reminder", {drank: false}),
17      destructive: true
18    }
19  ]
20})
21
22// When Hydration Reminder is running,
23// the index.tsx is the entry point. 
24// Check the value of `Script.queryParameter["drank"]`.
25const drank = Script.queryParameters["drank"]
26if (drank === "true") {
27  // drank
28} else if (drank === "false") {
29  // ignored
30}

2. Fetching Notifications#

Get Delivered Notifications
Method: Notification.getAllDelivereds(): Promise<NotificationInfo[]>

Returns all delivered notifications still visible in Notification Center.

1type NotificationInfo = {
2  // The unique identifier for this notification request.
3  identifier: string
4  // The delivery timestamp of the notification.
5  deliveryTime: number
6  // The notification title.
7  title: string
8  // The notification subtitle.
9  subtitle: string
10  // The notification body.
11  body: string
12  // The custom data to associate with the notification.
13  userInfo: Record<string, any>
14  // The identifier that groups related notifications.
15  threadIdentifier: string
16}

Get Pending Notifications
Method: Notification.getAllPendings(): Promise<NotificationInfo[]>

Returns all pending notifications that have not yet been delivered.

3. Removing Notifications#

Remove All Delivered Notifications
Method: Notification.removeAllDelivereds(): Promise<void>

Removes all delivered notifications for the current script from Notification Center.

Remove All Pending Notifications
Method: Notification.removeAllPendings(): Promise<void>

Removes all pending notifications for the current script.

Remove Specific Delivered Notifications
Method: Notification.removeDelivereds(identifiers: string[]): Promise<void>

Removes specific delivered notifications by their identifiers.

Remove Specific Pending Notifications
Method: Notification.removePendings(identifiers: string[]): Promise<void>

Removes specific pending notifications by their identifiers.

4. Setting Badge Count#

Method: Notification.setBadgeCount(count: number): Promise<boolean>

Updates the Scripting app icon’s badge count.

Example:

1await Notification.setBadgeCount(5)

5. Displaying Custom UI for Rich Notifications#

By setting customUI to true in NotificationScheduleOptions, you can enable rich notifications. When the user expands the notification (e.g., by long-pressing), the custom UI defined in notification.tsx will render, allowing you to display interactive elements and capture user input.

Method: Notification.present(element: JSX.Element)

This method is used within notification.tsx to present custom UI when a notification is expanded.

Example in notification.tsx:

1import { Notification, VStack, Text, Button, } from 'scripting'
2
3function HydrationNotification() {
4  const handleDrinkWater = () => {
5    // Logic to log that water was consumed
6    console.log("User drank water")
7  }
8
9  const handleIgnore = () => {
10    // Logic to ignore this reminder
11    console.log("User ignored the reminder")
12  }
13
14  return (
15    <VStack>
16      <Text>Remember to stay hydrated!</Text>
17      <Button title="I Drank" action={handleDrinkWater} />
18      <Button title="Ignore" action={handleIgnore} />
19    </VStack>
20  )
21}
22
23Notification.present(<HydrationNotification />)

6. Accessing Notification Data#

Property: Notification.current

When a notification opens the script or when rendering the rich notification UI, you can access the notification’s information via Notification.current.

Example:

1const notificationData = Notification.current
2if (notificationData != null) {
3  console.log(notificationData.title, notificationData.body)
4}

This documentation provides an overview of how to use the Notification module in the Scripting app to deliver, manage, and customize notifications with actionable elements and rich content. Happy coding!