iOS Push Notifications SDK

Set up APNs and the CometChat Push Notifications SDK 2.0 on iOS: automatic token registration, chat notifications with quick reply and delivery receipts, notification taps, badge count and call ringing.

Push Notifications SDK for iOS

Source, and example apps for a calls-only app and a chat-and-calls app.

​

What this guide covers

• APNs setup and the CometChat provider (dashboard, Xcode capabilities).
• Adding the SDK’s products and initialising it; the SDK registers and unregisters the push tokens itself.
• Chat pushes: foreground banners, quick reply, delivery receipts and taps, handled by the SDK.
• The Notification Service Extension for delivery receipts, avatars and campaign images.
• App icon badge count from the unreadMessageCount field.
• Call pushes: ringing through the SDK’s Calls product, covered on Push Ringing.

​

How APNs and CometChat fit together

• Why APNs? Apple issues the device tokens and delivers the pushes: a regular APNs token for chat notifications and, through PushKit, a VoIP token for calls.
• Why a CometChat provider? The provider holds your APNs key and tells CometChat how to send to your app. The SDK registers each token against its id when the user logs in.
• What the SDK does with a push. It presents chat notifications in the foreground, routes taps to your delegate, sends quick replies and campaign receipts, and (with its extension base class) marks messages delivered. VoIP pushes go to the Calls product, which rings the device through CallKit.

​

Requirements

iOS	15.1 or later
Xcode	16.4 or later
Chat SDK	CometChatSDK 4.1.10 or later, for the Chat product
Calls SDK	CometChatCallsSDK 5.1.0, for the Calls product
Device	A physical device. Push notifications, PushKit and CallKit do not work in the Simulator

​

1. Prepare Apple and CometChat

1. CometChat dashboard: go to Notifications → Settings, enable Push Notifications, click Add Credentials and add an APNs provider with your .p8 auth key (Key ID, Team ID, Bundle ID). Copy its Provider ID.

The SDK registers the APNs device token and the VoIP token under one provider id. Use a .p8 auth key: a .p12 certificate provider serves only one of the two tokens.

The provider’s Bundle ID must be your app’s bundle ID, and its APNs environment must match the build: Enable Production Mode off for builds run from Xcode, on for TestFlight and App Store builds. On a mismatch APNs rejects the pushes.

2. Xcode, in your app target’s Signing & Capabilities:

   • Push Notifications.
   • Background Modes → Remote notifications, so silent pushes (campaign receipts, badge updates) reach the app.
   • Background Modes → Voice over IP, if calls should ring; see Push Ringing for the rest of what calls need.
   • App Groups, if you add the Notification Service Extension.

3. App constants: note your CometChat App ID and Region, and the Provider ID. All three go into PNConfiguration.

​

2. Add the SDK

The SDK ships as three products, released together. Add Core always, and the others for what your app does:

Product	Add it when	Depends on
CometChatPushNotificationsSwift (Core)	Always	No CometChat SDK
CometChatPushNotificationsChat (Chat)	You show chat notifications: delivery receipts, quick reply, “open this chat” navigation, the Notification Service Extension	Core + CometChatSDK
CometChatPushNotificationsCalls (Calls)	Incoming calls should ring: PushKit and CallKit	Core + CometChatCallsSDK

A chat-only app adds Core and Chat; a calls-only app adds Core and Calls; most apps add all three.

The SDK is distributed with Swift Package Manager and needs iOS 15.1 or later. In Xcode, File → Add Package Dependencies, enter:

https://github.com/cometchat/push-notifications-sdk-ios

Choose Up to Next Major Version from 2.0.0 and add the products your app needs to the app target. Each product is its own module, and Chat and Calls bring the Chat SDK and Calls SDK they depend on.

The Core module is CometChatPushNotificationsSwift; CometChatPushNotifications is the class inside it. Import the Chat and Calls modules in the files that use their delegate protocols.

​

3. Initialise the SDK

Call initialize(config:) in application(_:didFinishLaunchingWithOptions:), on every launch, before the user logs in:

• Token registration on login and logout only runs in a launch where initialize ran.
• initialize sets the SDK as the UNUserNotificationCenter delegate. iOS requires that delegate before launch finishes, or the tap that launched the app is lost.
• With the Calls product, initialize also creates the PushKit registry, which iOS requires by the end of launch.
• It asks for notification permission, registers for remote notifications, installs every linked product and saves the configuration, so a launch started by a push still knows your app.
• It sets the notification categories to the SDK’s own MessageCategory (for quick reply). That replaces any categories your app set before; add yours back after initialize, including MessageCategory.

Set the delegate first. The SDK holds it weakly, so keep a strong reference to it.

Swift

AppDelegate.swift

import UIKit
import CometChatPushNotificationsSwift

@main
final class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    // The SDK holds its delegate weakly: the app keeps it alive.
    let pushDelegate = PushDelegate()

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        CometChatPushNotifications.shared.delegate = pushDelegate
        CometChatPushNotifications.shared.initialize(config: PNConfiguration(
            appId: "APP_ID",
            region: "REGION",
            providerId: "PROVIDER_ID",
            extensionGroupID: "group.com.yourcompany.yourapp"   // only with the service extension
        ))
        return true
    }
}

Objective-C

AppDelegate.m

@import CometChatPushNotificationsSwift;

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // self.pushDelegate is a strong property: the SDK holds its delegate weakly.
    CometChatPushNotifications.shared.delegate = self.pushDelegate;

    PNConfiguration *config = [[[[PNConfiguration builderWithAppId:@"APP_ID" region:@"REGION"]
        providerId:@"PROVIDER_ID"]
        extensionGroupID:@"group.com.yourcompany.yourapp"]
        build];
    [CometChatPushNotifications.shared initializeWithConfig:config];
    return YES;
}

In a SwiftUI app, put this in an AppDelegate attached with @UIApplicationDelegateAdaptor.

PNConfiguration(appId:region:…) takes every option as a defaulted parameter; from Objective-C, or to chain setters, use PNConfiguration.builder(appId:region:) and build(). With the Chat product, PNConfigurationBuilder.from(appId:settings:) starts a builder from the Chat SDK’s AppSettings.

Option	Default	What it does
appId, region	none; required	Your CometChat app. Must not be blank. The SDK registers tokens over its own connection, so it needs them even before any SDK is initialised
providerId	nil; required to register tokens	The dashboard provider the tokens are registered under. Without it registration fails with PNError.Code.providerRequired and no push arrives
extensionGroupID	nil	App Group shared with the Notification Service Extension, so the app and the extension do not both send a delivery receipt
enableBadgeCount	true	Set the app icon badge from the payload; see Badge count
showInAppNotifications	true	Show chat notifications while the app is in the foreground
requestNotificationPermission	true	Show the notification prompt and register for remote notifications in initialize. Set false to ask later yourself
autoRegisterTokens	true	Register the tokens on login and unregister them on logout, with no code of yours
tokenRegistrar	.auto	Whose session registers the tokens: .auto (the Chat SDK if logged in, then the Calls SDK), .chat or .calls
authToken	nil	A user auth token to register with when neither SDK is logged in. Not saved to disk
clientHost (builder: overrideClientHost(_:))	nil	Register tokens against this client host instead of the default one. Set it only if you give the Chat and Calls SDKs a client host override, and use the same value
callKit, requestCallPermissions, pushKitOwnership	CallKitBranding(), true, .sdk	Calls; see Push Ringing

​

4. Forward the APNs token

The APNs device token arrives in your AppDelegate; hand it to the SDK. The token is cached, so it does not matter whether it arrives before initialize or before login: the SDK registers it once someone is logged in.

Swift

AppDelegate.swift

func application(_ application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    CometChatPushNotifications.shared.registerDeviceToken(deviceToken)
}

// Recommended: surfaces entitlement and provisioning problems during development.
func application(_ application: UIApplication,
                 didFailToRegisterForRemoteNotificationsWithError error: Error) {
    CometChatPushNotifications.shared.handleRegistrationFailure(error)
}

// Silent pushes: campaign receipts and badge updates.
func application(_ application: UIApplication,
                 didReceiveRemoteNotification userInfo: [AnyHashable: Any],
                 fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    CometChatPushNotifications.shared.handleBackgroundNotification(userInfo: userInfo)
    completionHandler(.newData)
}

Objective-C

AppDelegate.m

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [CometChatPushNotifications.shared registerDeviceToken:deviceToken completion:nil];
}

- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
    [CometChatPushNotifications.shared handleRegistrationFailure:error];
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
    fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    [CometChatPushNotifications.shared handleBackgroundNotificationWithUserInfo:userInfo];
    completionHandler(UIBackgroundFetchResultNewData);
}

registerDeviceToken also takes an optional completion with a PNResult<String>. The VoIP token needs no code: the Calls product receives it from its own PushKit registry.

A calls-only app (Core and Calls, no Chat) registers only the VoIP token. It can skip this step and set requestNotificationPermission: false, since calls ring without notification permission.

If your app must keep its own UNUserNotificationCenter delegate, set it after initialize and forward to handleWillPresentNotification(_:completionHandler:) and handleNotificationResponse(_:completionHandler:), or the SDK no longer sees foreground notifications and taps.

​

5. Handle notification taps

One delegate object serves every product. Adopt CometChatPushNotificationsDelegate, plus CometChatPushNotificationsChatDelegate if you link the Chat product, and implement only what you need; every method is optional.

Swift

PushDelegate.swift

import UIKit
import CometChatSDK
import CometChatPushNotificationsSwift
import CometChatPushNotificationsChat

final class PushDelegate: NSObject, CometChatPushNotificationsChatDelegate {

    // Chat product: a tapped chat notification.
    func navigateToChat(for user: User) { /* open the 1:1 conversation */ }
    func navigateToChat(for group: Group) { /* open the group conversation */ }

    // A tapped campaign notification sent from the dashboard (already marked clicked).
    func navigateToNotificationsFeed() { /* open your notifications screen */ }

    // A tap no product recognised, or any tap in an app without the Chat product.
    func didTapNotification(_ info: CometChatNotificationInfo) { /* info.rawPayload has everything */ }

    // Fallback when the matching method above is not implemented.
    func navigateToDefaultScreen() { }

    // Token observability. Fires for automatic registrations too: the fastest way to catch a wrong provider id.
    func onPushTokenRegistered(platform: CometChatPushTokenPlatform) { }
    func onPushTokenRegistrationFailed(platform: CometChatPushTokenPlatform, error: PNError) {
        print("Push token \(platform.rawName) not registered: \(error.code.name) \(error.message)")
    }
}

Objective-C

PushDelegate.m

@import CometChatSDK;
@import CometChatPushNotificationsSwift;
@import CometChatPushNotificationsChat;

@interface PushDelegate : NSObject <CometChatPushNotificationsChatDelegate>
@end

@implementation PushDelegate
- (void)navigateToChatForUser:(User *)user { /* open the 1:1 conversation */ }
- (void)navigateToChatForGroup:(Group *)group { /* open the group conversation */ }
- (void)navigateToNotificationsFeed { /* open your notifications screen */ }
- (void)navigateToDefaultScreen { }
- (void)onPushTokenRegistrationFailedWithPlatform:(CometChatPushTokenPlatform)platform error:(PNError *)error {
    NSLog(@"Push token not registered: %@", error.message);
}
@end

A tap that launches the app reaches the delegate early, possibly before your UI is up. Keep the destination and navigate once your root screen exists.

SwiftUI: keep the delegate a plain NSObject. The SDK holds its delegate as an Objective-C weak reference. Do not make an ObservableObject with @Published properties the delegate; have a small NSObject delegate forward to it.

Type	Values
CometChatPushTokenPlatform	.apns, .fcm, .voip
PNError.Code	.notInitialised, .notLoggedIn, .providerRequired, .productNotInstalled, .serverError, .networkError

Suppress notifications for the open chat. While a conversation is on screen, its notifications are not shown in the foreground:

// In your messages screen
override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    CometChatPushNotifications.shared.setActiveConversation(userId: user.uid ?? "")   // or setActiveConversation(groupId:)
}

override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    CometChatPushNotifications.shared.clearActiveConversation()
}

​

6. Tokens, login and logout

You do not register push tokens. When the user logs in to the Chat or Calls SDK, the SDK registers the APNs device token and, with the Calls product, the VoIP token, under your providerId. It registers a rotated token again, and if someone is already logged in when initialize runs it registers the cached tokens then.

To log out, unregister first and wait for it: the request is authenticated with the user’s session, so it has to finish before that session ends.

CometChatPushNotifications.shared.unregisterTokens(completion: { _ in
    CometChat.logout(onSuccess: { _ in }, onError: { _ in })
    // With the Calls SDK, also log out of it: CometChatCalls.logout(...)
})

On logout the SDK also ends a call still ringing for the old user (and an answered call in progress, as .failed) and clears the app badge. The tokens stay cached on the device and are registered again for the next user who logs in.

registerTokens(completion:) registers the cached tokens on demand. autoRegisterTokens: false stops registration in initialize and on login, and unregistration on logout; a token delivered or rotated while a user is logged in is still registered.

​

7. Notification Service Extension

The extension gives chat notifications delivery receipts, the sender’s avatar, campaign images and plain text in place of markdown. Delivery receipts for chat messages come from the extension, so add it if your app shows read and delivered ticks.

1. Add the target

   File → New → Target → Notification Service Extension.

2. Link Core and Chat only

   Add CometChatPushNotificationsSwift and CometChatPushNotificationsChat to the extension target, and never the Calls product: an extension runs under a memory limit the Calls SDK does not fit in.

3. Share an App Group

   Add the same App Group (for example group.com.yourcompany.yourapp) to both the app target and the extension target, and pass it as extensionGroupID in PNConfiguration.

4. Subclass the base class

   Replace the generated class:

   NotificationService.swift

   import CometChatPushNotificationsChat
   
   class NotificationService: CometChatNotificationServiceExtension {}
   
5. Point the extension at the App Group

   Add a String entry CometChatExtensionGroupID set to your App Group id in the extension’s Info.plist, or override the extensionGroupID property.

Optional overrides: stripsMarkdown and attachesMedia (both true), and finalizeContent(_:) to change the content last, after receipts, media and markdown.

​

8. Badge count

CometChat’s push payload can carry an unreadMessageCount field: the total unread messages across all conversations for the logged-in user.

1. Go to CometChat Dashboard → Notifications → Settings → Preferences → Push Notification Preferences.
2. Scroll to the bottom and enable the Unread Badge Count toggle.

With enableBadgeCount on (the default), the SDK sets the app icon badge from unreadMessageCount when it is a number: on a chat notification shown in the foreground (with showInAppNotifications on), a silent push handed to handleBackgroundNotification, and a tap. clearBadgeCount() does nothing while enableBadgeCount is off. Clear it with CometChatPushNotifications.shared.clearBadgeCount(), for example when the app becomes active; logout clears it too.

To set the badge on every delivered notification, including in the background, and also when the payload carries the count as a string, set it in the extension:

NotificationService.swift

import UserNotifications
import CometChatPushNotificationsChat

class NotificationService: CometChatNotificationServiceExtension {
    override func finalizeContent(_ content: UNMutableNotificationContent) -> UNMutableNotificationContent {
        let raw = content.userInfo["unreadMessageCount"]
        if let count = (raw as? Int) ?? (raw as? String).flatMap({ Int($0) }), count >= 0 {
            content.badge = NSNumber(value: count)
        }
        return content
    }
}

​

9. Message pushes

Handled by the SDK, with nothing to build:

• Foreground: a banner, unless that conversation is open (setActiveConversation) or showInAppNotifications is false.
• Quick reply: the SDK registers the notification category MessageCategory with a Reply action. A reply typed there is sent as a text message into the conversation by the Chat product.
• Delivery receipts, avatars, markdown: from the Notification Service Extension.
• Taps: routed to navigateToChat(for:); see Handle notification taps.

Campaign (engagement) pushes sent from the dashboard are marked delivered (in the foreground, from handleBackgroundNotification and in the extension) and clicked (on tap) when the Chat product is linked; a tap calls navigateToNotificationsFeed().

CometChatPushNotifications.parseNotificationInfo(from:) reads the sender, receiver and body out of a raw payload, and isCampaignNotification(userInfo:) tells campaign pushes apart.

​

10. Call pushes

Handled by the Calls product: it owns the PushKit registry, rings through CallKit in every app state, connects to the call while it rings, and calls your presentCall(_:) when the user answers, where you join the call. It sends declines and timeouts, and CallKit records missed calls in Recents.

Setup, capabilities, joining and customising CallKit are on Push Ringing. Starting and ending calls is on Ringing.

​

Ring readiness and diagnostics

After sign-in, check what could silence a notification or a ring:

CometChatPushNotifications.shared.ensureRingReady { result in
    guard case .success(let readiness) = result, readiness != .ready else { return }
    // .notificationsOff, .providerMissing, and with the Calls product
    // .backgroundModeMissing, .voipEntitlementMissing, .microphoneDenied
    print("Push not ready: \(readiness.name)")
}

getDiagnostics() returns a redacted dictionary of everything that affects delivery (products, login state, cached tokens, background modes) for bug reports. verifyPushSetup(completion:) registers the tokens and reports the outcome.

​

FCM instead of APNs

APNs is the recommended mode on iOS, and FCM mode suits chat-only apps. If your app already routes APNs through Firebase and does not ring calls, configure Firebase as usual and forward the FCM token; the SDK links nothing from Firebase:

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
    if let token = fcmToken {
        CometChatPushNotifications.shared.registerFCMToken(token)
    }
}

The FCM token is registered under the same providerId as the other tokens; 2.0 takes a single provider id for every token. An FCM provider cannot deliver VoIP pushes, so an app that rings calls must use an APNs provider instead.

​

Upgrading from 1.x

2.0 is a breaking release:

1.x	2.0
One pod, CometChatPushNotifications	Three products: Core, Chat, Calls
CometChatPushNotificationsConfig(providerId:…)	PNConfiguration(appId:region:providerId:…); appId and region are required
navigateToChat(for:) on the core delegate	On CometChatPushNotificationsChatDelegate (Chat product)
presentCallScreen(for:sessionId:) with a Chat SDK Call	presentCall(_ call: IncomingCall) -> Bool on CometChatPushNotificationsCallsDelegate; join with the Calls SDK
onCallCleanupComplete, onCallMissed	callDidEnd(_:reason:)
notifyCallsSDKReady()	Removed: the SDK brings the Calls SDK up itself
foregroundCallPresentation, CometChatIncomingCallView, incomingCallStyle	Removed: calls always ring on CallKit
callkitIconName, callkitRingtoneName	CallKitBranding in callKit
onCallMuteStateChanged, activeCallSessionId	Removed
onPushTokenRegistrationFailed(platform:error: CometChatException)	error: PNError
notificationContentModifier	Still accepted, but has no effect in 2.0

Ringing itself moved from the Chat SDK’s call flow to the Calls SDK; see Migrating from legacy ringing.

​

Testing checklist

1. Install on a physical device and allow notifications.
2. Log in, and check onPushTokenRegistered fires (or getDiagnostics()).
3. Send a message from another user:
   • Foreground: a banner appears unless that chat is open.
   • Background or killed: tapping it opens the right conversation.
4. Reply from the notification: the message arrives in the conversation.
5. With the extension: the sender sees the message delivered, and the avatar shows.
6. With the Calls product, call from another user with the app in the foreground, in the background, killed, and with the phone locked; see Push Ringing.
7. Log out and confirm no further pushes arrive; log in as another user and confirm theirs do.

​

Troubleshooting

Symptom	Quick checks
No notifications	Physical device; Push Notifications capability; Push Notifications enabled in the dashboard and the Provider ID correct; the user logged in (tokens register on login). onPushTokenRegistrationFailed says why
providerRequired	providerId missing from PNConfiguration
Tap does nothing	Delegate not set, released (it is held weakly), or not adopting CometChatPushNotificationsChatDelegate; another object took over UNUserNotificationCenter’s delegate
Tap that launches the app does nothing	initialize not called in didFinishLaunching
No delivery receipts or avatars	Notification Service Extension missing, or its App Group or CometChatExtensionGroupID does not match extensionGroupID
Banners in the foreground for the open chat	setActiveConversation not called for that screen
Badge not showing	Unread Badge Count enabled in the dashboard; enableBadgeCount on; set it in the extension if the count arrives as a string
Still receiving pushes after logout	unregisterTokens not awaited before logout
Calls do not ring	See Push Ringing → Troubleshooting

​

Related

Push Notifications Overview

Dashboard setup, providers and templates.

Push Ringing

Incoming calls through PushKit and CallKit with the same SDK.

Manual APNs integration

The hand-wired alternative, with the UI Kit and legacy ringing.