Notification#

The Notification module in the Scripting app allows you to schedule, manage, and display local notifications with advanced trigger types, interactive actions, and rich UI capabilities.

Table of Contents#

1. Scheduling Notifications

2. Notification Triggers

   • TimeIntervalNotificationTrigger
   • CalendarNotificationTrigger
   • LocationNotificationTrigger

3. Notification Actions

4. Rich Notifications with Custom UI

5. Managing Notifications

6. NotificationInfo and Request Structure

7. Comprehensive Example

Scheduling Notifications#

Use Notification.schedule to schedule a local notification. It supports text content, triggers, action buttons, custom UI, and delivery configuration:

1await Notification.schedule({
2  title: "Reminder",
3  body: "Time to stand up!",
4  trigger: new TimeIntervalNotificationTrigger({
5    timeInterval: 1800,
6    repeats: true
7  }),
8  actions: [
9    {
10      title: "OK",
11      url: Script.createRunURLScheme("My Script", { acknowledged: true })
12    }
13  ],
14  customUI: false
15})

Parameters#

Deprecated: triggerTime and repeatsType are deprecated. Use trigger instead.

Notification Triggers#

TimeIntervalNotificationTrigger#

Triggers a notification after a specified number of seconds.

1new TimeIntervalNotificationTrigger({
2  timeInterval: 3600,
3  repeats: true
4})

• timeInterval: Delay in seconds.
• repeats: Whether it repeats.
• nextTriggerDate(): Returns the next expected trigger date.

CalendarNotificationTrigger#

Triggers when the current date matches specific calendar components.

1const components = new DateComponents({ hour: 8, minute: 0 })
2new CalendarNotificationTrigger({
3  dateMatching: components,
4  repeats: true
5})

• Set any of year, month, day, hour, etc.
• Useful for daily, weekly, or one-time schedules.

LocationNotificationTrigger#

Triggers when entering or exiting a geographic region.

1new LocationNotificationTrigger({
2  region: {
3    identifier: "Work",
4    center: { latitude: 37.7749, longitude: -122.4194 },
5    radius: 100,
6    notifyOnEntry: true,
7    notifyOnExit: false
8  },
9  repeats: false
10})

• Fires based on entering/exiting the specified region.

Notification Actions#

Use the actions parameter to define buttons shown when a notification is expanded.

1actions: [
2  {
3    title: "Open Details",
4    url: Script.createRunURLScheme("Details Script", { fromNotification: true })
5  },
6  {
7    title: "Dismiss",
8    url: Script.createRunURLScheme("Dismiss Script", { dismissed: true }),
9    destructive: true
10  }
11]

• Use Script.createRunURLScheme(scriptName, parameters) to generate the correct callback URLs.
• Actions are displayed when long-pressing or pulling down the notification.

Rich Notifications with Custom UI#

You can provide a JSX-based interface for expanded notifications by:

1. Setting customUI: true in Notification.schedule.
2. Creating a notification.tsx file in your script.
3. Calling Notification.present(element) inside that file.

Notification.present(...)#

1Notification.present(element: JSX.Element): void

• Must be called within notification.tsx.
• Renders the provided element as the notification's expanded UI.

Example notification.tsx#

1import { Notification, VStack, Text, Button } from 'scripting'
2
3function NotificationView() {
4  return (
5    <VStack>
6      <Text>Need to complete your task?</Text>
7      <Button title="Done" action={() => console.log("Task completed")} />
8      <Button title="Later" action={() => console.log("Task postponed")} />
9    </VStack>
10  )
11}
12
13Notification.present(<NotificationView />)

Managing Notifications#

NotificationInfo and Request Structure#

Use Notification.current to access information when the script is launched from a notification tap.

1if (Notification.current) {
2  const { title, userInfo } = Notification.current.request.content
3  console.log(`Launched from: ${title}`, userInfo)
4}

NotificationRequest#

Comprehensive Example#

This example demonstrates a complete use of notification features: custom UI, interactive actions, time-sensitive interruption level, and repeated delivery using TimeIntervalNotificationTrigger.

Step 1: Schedule the Notification#

1await Notification.schedule({
2  title: "Hydration Reminder",
3  body: "Time to drink water!",
4  interruptionLevel: "timeSensitive",
5  customUI: true,
6  trigger: new TimeIntervalNotificationTrigger({
7    timeInterval: 3600,
8    repeats: true
9  }),
10  actions: [
11    {
12      title: "I Drank",
13      url: Script.createRunURLScheme("Hydration Reminder", { drank: true }),
14    },
15    {
16      title: "Ignore",
17      url: Script.createRunURLScheme("Hydration Reminder", { drank: false }),
18      destructive: true
19    }
20  ]
21})

Step 2: Define notification.tsx#

1import { Notification, VStack, Text, Button } from 'scripting'
2
3function HydrationUI() {
4  return (
5    <VStack>
6      <Text>Have you drunk water?</Text>
7      <Button title="Yes" action={() => console.log("Hydration confirmed")} />
8      <Button title="No" action={() => console.log("Reminder ignored")} />
9    </VStack>
10  )
11}
12
13Notification.present(<HydrationUI />)

Summary#

The Notification API in the Scripting app provides rich scheduling capabilities, including:

• Time, calendar, and location-based triggers
• Actionable notifications with structured URL callbacks
• Custom UI for interactive experiences
• Full notification lifecycle management

Migrate to the trigger-based scheduling model for full control and platform-aligned behavior.