Add macOS push notifications

Push notifications tell customers about support and feedback replies while the app is inactive. They are optional for messaging and require BTXClientKit 3.5.0 or later. Campaign push delivery remains iOS-only.

• Register the app's explicit bundle ID in Apple Developer and enable Push Notifications.
• Enable Push Notifications for the host target in Xcode.
• Sign the app with a provisioning profile for the same App ID and push environment.
• Keep the host app's APNs registration-failure callback for diagnostics.

See Apple’s app capability guide for App ID setup.

Creating an App Store Connect record alone does not enable device registration. The signed app must contain com.apple.developer.aps-environment. The SDK reads that entitlement to select its environment; the build configuration name does not select APNs.

Normal reply delivery and Test push use production registrations. A development registration can be recorded for diagnostics but is not eligible for these sends.

In the BTX desktop app, open Settings → Project settings → Client SDKs and create or select a macOS client. Enter the host app's exact Bundle ID.

Select Set up macOS push notifications, choose the APNs .p8 authentication key, and confirm its Apple Team ID and Key ID. Use Save setup to save the complete credential set. Existing credentials can be replaced through Manage.

Use credentials from the same Apple team as the host app. Keep the private key in BTX; never embed it in the Mac app. Configured confirms saved credentials, not successful notification delivery.

Configure BTX before the app finishes launching. Add the token callback to your existing NSApplicationDelegate:

import AppKit
import BTXClientKit

@MainActor
final class AppDelegate: NSObject, NSApplicationDelegate {
    func application(
        _ application: NSApplication,
        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
    ) {
        BTX.messenger.setDeviceToken(deviceToken)
    }
}

For SwiftUI apps, connect that delegate inside the App type:

@NSApplicationDelegateAdaptor(AppDelegate.self)
private var appDelegate

Forward every successful token callback. Also register the host window so notification clicks can open a conversation.

By default, the first support or feedback presentation requests notification permission and registers with APNs. If the host owns this timing, pass the following value as BTXMessengerOptions.push:

BTXPushConfiguration(
    automaticallyRequestsAuthorization: false
)

In that mode, the host requests authorization through UNUserNotificationCenter, calls NSApplication.shared.registerForRemoteNotifications(), and forwards the token callback. If permission was denied, the customer can allow notifications for the app in System Settings → Notifications.

BTX preserves the host's notification-center delegate and forwards unrelated notifications. BTX replies use native banners and sound in the foreground.

Clicking a reply waits for an identified customer and a registered host window, then activates that window and opens the matching conversation. Passive delivery and dismissal do not open it. If the host routes notification responses manually, BTX.handleNotificationResponse(_:) returns whether BTX recognized the response.

Before sign-out or an account switch, follow the push unregister sequence.

1. 01

   Register a production installation

   Open the correctly signed Mac app, identify a customer, and allow notifications. Present support or feedback and confirm that the host forwards the APNs token.

2. 02

   Select the registered device

   Return to the macOS client in BTX, select Test push, and choose the intended installation using its customer, app version, and last-seen time.

3. 03

   Send and inspect the notification

   Select Send test and confirm that the Mac displays the notification. Provider acceptance alone does not prove display. Then send a support or feedback reply to a test customer and verify that clicking its notification opens the correct conversation.

If no eligible device appears, check the bundle ID, signed entitlement, customer identity, notification permission, and forwarded token. APNs credentials must match the Apple team and registered app.