Notifications

Send local notifications using the platform’s notification system. Every snippet below is excerpted from docs/examples/system/snippets.ts — CI links it on every PR.

Sending a notification

notificationSend("Build complete", "All targets compiled in 4.2s.")

Reacting to a tap

notificationOnTap((id: string, action?: string) => {
    console.log(`tapped notification ${id}; action=${action ?? "(default)"}`)
})

action is the action-button identifier when the user picks a button, or undefined for the default banner tap.

Cancelling a scheduled notification

notificationCancel("daily-reminder")

notificationCancel(id) is a no-op if no scheduled notification with that id exists.

Push notifications (APNs / Firebase)

notificationRegisterRemote((token: string) => {
    console.log(`APNs device token: ${token}`)
})

notificationOnReceive((payload: object) => {
    console.log(`got remote payload: ${JSON.stringify(payload)}`)
})

notificationRegisterRemote(cb) fires once when the OS returns a device token — on Apple platforms the token is the canonical uppercase hex string APNs expects. notificationOnReceive(cb) runs whenever a remote payload arrives while the app is foregrounded; the payload is the APNs aps userInfo dictionary (or equivalent platform shape) converted to a plain object.

Requires the relevant platform capability (APNs entitlement on iOS/macOS, Firebase Messaging on Android — wired via JNI through PerryFirebaseMessagingService, see #98). No-op on platforms without a push pipeline (tvOS, visionOS, watchOS, GTK4, Windows, Web).

Enabling APNs on iOS

registerForRemoteNotifications only succeeds when the signed .app carries the aps-environment entitlement. Opt in from perry.toml (#5074):

[ios]
push_notifications = true          # emit the aps-environment entitlement
# push_environment = "production"  # default "development"; set for distribution

With this set, perry compile --target ios writes aps-environment into the bundle’s app.entitlements (defaulting to development, which matches dev-signed builds), and perry setup ios / perry run --target ios enable the Push Notifications capability on the App ID when minting the development provisioning profile. For App Store / Ad Hoc distribution set push_environment = "production".

Platform Implementation

Permissions: On macOS, iOS, and Web, the user may need to grant notification permissions. On first use, the system will prompt automatically.

Next Steps

• Keychain — Secure storage
• Other — Additional system APIs
• Overview — All system APIs