iOS push notifications (Swift): add the SDK step by step

In the dashboard, open Applications your app SDK Integration and pick iOS (Swift) ①. Click Download PusherHub.swift ②. It goes in a PusherHub folder inside your app's own folder ③.

See this picture larger

Every step below is on this tab too, with your own keys already filled in — copy the code from there.

PusherHub sends to iPhones through Firebase Cloud Messaging, so your app needs Firebase's two packages. In Xcode:

1. Choose File Add Package Dependencies… .
2. Paste https://github.com/firebase/firebase-ios-sdk in the search box, and keep Up to Next Major Version from 12.0.0.
3. Click Add Package, then add FirebaseCore and FirebaseMessaging to your app target.

Firebase then shows under Package Dependencies in the file list (③ in the next picture).

1. GoogleService-Info.plist ① — drag it into your app's folder in Xcode and tick your app target.
2. PusherHub.swift ② — make a PusherHub folder inside your app's folder and put the file in it. Xcode 16 and later picks it up by itself; in an older project, add it to your app target.
3. Firebase ③ is there from step 2. NotificationService ④ comes in step 7.

See this picture larger

Select your app target and open Signing & Capabilities ①. Choose your paid Apple Developer Team, click + Capability ② and add Push Notifications ④. (The picture's target is called Runner — yours has your app's name.) Background Modes ③ isn't needed for the Swift SDK.

See this picture larger

A SwiftUI app doesn't have an app delegate yet: add a new Swift file called AppDelegate.swift with the code from step 4 on your SDK Integration tab. A UIKit app already has one — add these lines to it.

1. PusherHub.initialize(…) ① with your App key, Public key and server. (In the picture they're placeholders.)
2. PusherHub.registerDevice { … } ② asks the user to allow notifications, gets the push token and adds the phone to PusherHub. collectDeviceMetadata() inside it is optional: it adds the phone's model, language and country.
3. didRegisterForRemoteNotificationsWithDeviceToken ③ hands Apple's push token to PusherHub.
4. didFailToRegisterForRemoteNotificationsWithError ④ reports it when Apple refuses one.

See this picture larger

Open your app's main file (the one with @main, here MyApp.swift):

1. @UIApplicationDelegateAdaptor ① connects the AppDelegate from step 5.
2. .pusherHubMessageHost() ② — optional: shows your in-app messages when the app opens and every time it comes back. Leave it out if you only send notifications.

See this picture larger

In a UIKit app, skip the adaptor and call PusherHub.checkForInAppMessages() from your SceneDelegate's sceneDidBecomeActive(_:) instead.

An iPhone doesn't download a notification's image by itself — without this step it shows only the title and text.

1. File New Target… , pick Notification Service Extension, name it NotificationService, click Finish, then Don't Activate.
2. On the NotificationService target's General tab, set Minimum Deployments to the same iOS version as your app. Xcode picks the newest one, and an iPhone on anything older silently skips the extension.
3. Replace everything in NotificationService/NotificationService.swift with the file on your SDK Integration tab.

It needs no Firebase package, App Group or keys. The simulator can't draw notification pictures, so check this on a real iPhone.

PusherHub already estimates each phone's state from its internet address. For GPS instead, add this to your target's Info tab (or Info.plist), then call PusherHub.collectDeviceMetadata(resolveLocation: true) in step 5. The app asks for location once; if the user says no, only state and city are skipped.

<key>NSLocationWhenInUseUsageDescription</key>
<string>Used to resolve your approximate state/region so notifications can be targeted correctly.</string>

If your app has its own sign-in, tell PusherHub who's using the phone. Then you can send to one person by your own user ID. It's remembered, even after the app restarts, until logout().

// When someone signs in:
PusherHub.login(externalId: currentUserId)

// When they sign out:
PusherHub.logout()

Put your own data in Custom Data when you create a notification — say {"campaign_id": "232"} — and your app gets it back whenever someone taps that notification, whether it was open, in the background or closed. Add onNotificationOpened to the PusherHub.initialize(…) in AppDelegate.swift from step 5, and set something your views watch:

@MainActor final class NotificationRouter: ObservableObject {
    static let shared = NotificationRouter()
    @Published var campaignId: String?
}

PusherHub.initialize(
    appKey: "YOUR_APP_KEY",
    publicKey: "YOUR_PUBLIC_KEY",
    baseUrl: "YOUR_SERVER",
    onNotificationOpened: { data in
        NotificationRouter.shared.campaignId = data["campaign_id"]
    }
)

Then open the campaign from your views when campaignId changes — a tap that opened a closed app can arrive before your first view is up. Every value arrives as text ("232"). This needs PusherHub.swift from 24 October 2026 or later — download it again if yours is older.

Choose a real iPhone at the top of Xcode — the simulator can't get push notifications — and click Run ▶. Tap Allow when it asks about notifications. Within a few seconds the phone shows up in PusherHub under Devices.

Then send it a test notification.