perry-push

Push notification bindings for Perry native apps. Provides cross-platform push notification support with APNs on iOS/macOS and a stub implementation on Android (ready for FCM integration later).

Platforms

Platform	Backend	Minimum Version
iOS	APNs	iOS 16.0
macOS	APNs	macOS 13.0
Android	Stub	FCM planned

Installation

Add to your Perry app's package.json dependencies:

{
  "dependencies": {
    "perry-push": "file:../perry-push"
  }
}

Then add the required frameworks to your perry.toml if not automatically picked up.

Usage

import { perry_push_request_permission, perry_push_get_token, perry_push_set_badge } from "perry-push";

// Request permission (must be called first)
const permResult = await perry_push_request_permission();
const perm = JSON.parse(permResult);
if (perm.granted) {
  // Get the APNs device token
  const tokenResult = await perry_push_get_token();
  const tokenData = JSON.parse(tokenResult);
  if (tokenData.token) {
    // Send tokenData.token to your server for push delivery
    console.log("APNs token:", tokenData.token);
    console.log("Platform:", tokenData.platform); // "apns"
  }
}

// Set the app badge count
perry_push_set_badge(5);  // Set badge to 5
perry_push_set_badge(0);  // Clear badge

API Reference

perry_push_request_permission() -> Promise<string>

Requests notification permission from the user. On iOS/macOS, this shows the system permission dialog. If granted, automatically calls registerForRemoteNotifications().

Response JSON:

{ "granted": true }

{ "error": "Permission denied by user", "granted": false }

perry_push_get_token() -> Promise<string>

Returns the APNs device token. Call this after requestPermission has been granted. The function will poll for up to 5 seconds waiting for the token to arrive from the system.

Response JSON:

{ "token": "a1b2c3d4e5f6...", "platform": "apns" }

{ "error": "Device token not available. Ensure push permission was granted and the app has the Push Notifications entitlement." }

perry_push_set_badge(count: number) -> void

Sets the app icon badge number. Pass 0 to clear the badge. This is a synchronous call (returns 0.0).

Requirements

• Push Notifications entitlement: Your app must have the Push Notifications capability enabled in Xcode (or equivalent signing configuration).
• APNs certificate/key: Your server needs an APNs certificate or key to send push notifications to the device token.

Token Retrieval

The APNs device token is delivered asynchronously by the system via the app delegate's application(_:didRegisterForRemoteNotificationsWithDeviceToken:) callback. Since Perry does not expose the app delegate directly, this package uses a polling approach:

1. requestPermission() grants permission and calls registerForRemoteNotifications()
2. getToken() polls for up to 5 seconds waiting for the token to be cached

For production apps that need immediate token availability, the host app can call the swift_push_set_device_token C function from its AppDelegate to provide the token directly.

Android / FCM

The Android target currently uses a stub implementation that returns an error for all operations. FCM integration is planned for a future release.

License

MIT