@cometchat/skills 3.0.0 → 4.0.0

package/skills/cometchat-ios-push/SKILL.md

@@ -0,0 +1,582 @@
+---
+name: cometchat-ios-push
+description: "Set up push notifications for CometChat iOS apps — APNs configuration, token registration, and notification handling."
+license: "MIT"
+compatibility: "CometChatUIKitSwift ^5; iOS 13+"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "chat cometchat ios push notifications apns"
+---
+
+## Purpose
+
+This skill teaches how to set up push notifications for CometChat iOS apps, including APNs configuration, token registration, and handling incoming notifications.
+
+---
+
+## 1. Prerequisites
+
+Before setting up push notifications:
+
+1. **Apple Developer Account** — Required for APNs certificates
+2. **CometChat Dashboard Access** — To configure push notification settings
+3. **Physical iOS Device** — Push notifications don't work on simulators
+
+---
+
+## 2. APNs Certificate Setup
+
+### Step 1: Create APNs Key (Recommended)
+
+1. Go to [Apple Developer Portal](https://developer.apple.com/account)
+2. Navigate to **Certificates, Identifiers & Profiles** → **Keys**
+3. Click **+** to create a new key
+4. Enter a name (e.g., "CometChat Push Key")
+5. Enable **Apple Push Notifications service (APNs)**
+6. Click **Continue** → **Register**
+7. Download the `.p8` file (you can only download it once!)
+8. Note the **Key ID** and your **Team ID**
+
+### Step 2: Configure CometChat Dashboard
+
+1. Go to [CometChat Dashboard](https://app.cometchat.com)
+2. Select your app
+3. Navigate to **Notifications** → **Push Notifications**
+4. Select **iOS** tab
+5. Upload your `.p8` file
+6. Enter your **Key ID** and **Team ID**
+7. Select the environment (Development/Production)
+8. Save the configuration
+
+---
+
+## 3. Xcode Project Configuration
+
+### Enable Push Notifications Capability
+
+1. Open your project in Xcode
+2. Select your target
+3. Go to **Signing & Capabilities**
+4. Click **+ Capability**
+5. Add **Push Notifications**
+6. Add **Background Modes** and enable:
+   - Remote notifications
+   - Voice over IP (if using calls)
+
+### Update Info.plist
+
+Add the following to your `Info.plist`:
+
+```xml
+<key>UIBackgroundModes</key>
+<array>
+    <string>remote-notification</string>
+    <string>voip</string>
+</array>
+```
+
+---
+
+## 4. Code Implementation
+
+### AppDelegate Setup
+
+```swift
+import UIKit
+import UserNotifications
+import CometChatUIKitSwift
+import CometChatSDK
+
+@main
+class AppDelegate: UIResponder, UIApplicationDelegate {
+    
+    func application(
+        _ application: UIApplication,
+        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+    ) -> Bool {
+        
+        // Initialize CometChat
+        initializeCometChat()
+        
+        // Request notification permissions
+        requestNotificationPermission()
+        
+        // Register for remote notifications
+        application.registerForRemoteNotifications()
+        
+        return true
+    }
+    
+    private func initializeCometChat() {
+        let uiKitSettings = UIKitSettings()
+            .set(appID: "YOUR_APP_ID")
+            .set(authKey: "YOUR_AUTH_KEY")
+            .set(region: "us")
+            .subscribePresenceForAllUsers()
+            .build()
+        
+        CometChatUIKit(uiKitSettings: uiKitSettings) { result in
+            switch result {
+            case .success:
+                print("CometChat initialized")
+            case .failure(let error):
+                print("CometChat init failed: \(error)")
+            }
+        }
+    }
+    
+    private func requestNotificationPermission() {
+        let center = UNUserNotificationCenter.current()
+        center.delegate = self
+        
+        center.requestAuthorization(options: [.alert, .sound, .badge]) { granted, error in
+            if granted {
+                print("Notification permission granted")
+            } else if let error = error {
+                print("Notification permission error: \(error)")
+            }
+        }
+    }
+    
+    // MARK: - Remote Notification Registration
+    
+    func application(
+        _ application: UIApplication,
+        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
+    ) {
+        let token = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()
+        print("APNs Device Token: \(token)")
+        
+        // Register token with CometChat
+        registerPushToken(token)
+    }
+    
+    func application(
+        _ application: UIApplication,
+        didFailToRegisterForRemoteNotificationsWithError error: Error
+    ) {
+        print("Failed to register for remote notifications: \(error)")
+    }
+    
+    private func registerPushToken(_ token: String) {
+        CometChat.registerTokenForPushNotification(
+            token: token,
+            settings: ["voip": false]
+        ) { success in
+            print("Push token registered: \(success)")
+        } onError: { error in
+            print("Push token registration failed: \(error?.errorDescription ?? "")")
+        }
+    }
+    
+    // MARK: - Handle Incoming Notifications
+    
+    func application(
+        _ application: UIApplication,
+        didReceiveRemoteNotification userInfo: [AnyHashable: Any],
+        fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
+    ) {
+        print("Received remote notification: \(userInfo)")
+        
+        // Handle CometChat notification
+        if let messageData = userInfo["message"] as? [String: Any] {
+            handleCometChatNotification(messageData)
+        }
+        
+        completionHandler(.newData)
+    }
+    
+    private func handleCometChatNotification(_ data: [String: Any]) {
+        // Parse notification data
+        guard let type = data["type"] as? String else { return }
+        
+        switch type {
+        case "chat":
+            handleChatNotification(data)
+        case "call":
+            handleCallNotification(data)
+        default:
+            print("Unknown notification type: \(type)")
+        }
+    }
+    
+    private func handleChatNotification(_ data: [String: Any]) {
+        // Extract sender info
+        guard let senderUID = data["sender"] as? String else { return }
+        
+        // Navigate to conversation
+        DispatchQueue.main.async {
+            NotificationCenter.default.post(
+                name: .openConversation,
+                object: nil,
+                userInfo: ["uid": senderUID]
+            )
+        }
+    }
+    
+    private func handleCallNotification(_ data: [String: Any]) {
+        // Handle incoming call notification
+        print("Incoming call notification")
+    }
+}
+
+// MARK: - UNUserNotificationCenterDelegate
+
+extension AppDelegate: UNUserNotificationCenterDelegate {
+    
+    // Handle notification when app is in foreground
+    func userNotificationCenter(
+        _ center: UNUserNotificationCenter,
+        willPresent notification: UNNotification,
+        withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
+    ) {
+        // Show notification even when app is in foreground
+        completionHandler([.banner, .sound, .badge])
+    }
+    
+    // Handle notification tap
+    func userNotificationCenter(
+        _ center: UNUserNotificationCenter,
+        didReceive response: UNNotificationResponse,
+        withCompletionHandler completionHandler: @escaping () -> Void
+    ) {
+        let userInfo = response.notification.request.content.userInfo
+        
+        if let messageData = userInfo["message"] as? [String: Any] {
+            handleCometChatNotification(messageData)
+        }
+        
+        completionHandler()
+    }
+}
+
+// MARK: - Notification Names
+
+extension Notification.Name {
+    static let openConversation = Notification.Name("openConversation")
+}
+```
+
+### Handle Notification Navigation
+
+```swift
+class MainViewController: UIViewController {
+    
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        
+        // Listen for notification navigation
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(handleOpenConversation(_:)),
+            name: .openConversation,
+            object: nil
+        )
+    }
+    
+    @objc private func handleOpenConversation(_ notification: Notification) {
+        guard let uid = notification.userInfo?["uid"] as? String else { return }
+        
+        // Fetch user and open conversation
+        CometChat.getUser(UID: uid) { [weak self] user in
+            guard let user = user else { return }
+            
+            DispatchQueue.main.async {
+                let messagesVC = MessagesVC()  // your own VC composing CometChatMessageHeader + List + Composer
+                messagesVC.set(user: user)
+                self?.navigationController?.pushViewController(messagesVC, animated: true)
+            }
+        } onError: { error in
+            print("Error fetching user: \(error?.errorDescription ?? "")")
+        }
+    }
+    
+    deinit {
+        NotificationCenter.default.removeObserver(self)
+    }
+}
+```
+
+---
+
+## 5. VoIP Push Notifications (for Calls)
+
+### Import PushKit
+
+```swift
+import PushKit
+```
+
+### Register for VoIP
+
+```swift
+class AppDelegate: UIResponder, UIApplicationDelegate {
+    
+    var voipRegistry: PKPushRegistry?
+    
+    func application(
+        _ application: UIApplication,
+        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+    ) -> Bool {
+        
+        // ... other setup ...
+        
+        // Register for VoIP push
+        registerForVoIPPush()
+        
+        return true
+    }
+    
+    private func registerForVoIPPush() {
+        voipRegistry = PKPushRegistry(queue: .main)
+        voipRegistry?.delegate = self
+        voipRegistry?.desiredPushTypes = [.voIP]
+    }
+}
+
+// MARK: - PKPushRegistryDelegate
+
+extension AppDelegate: PKPushRegistryDelegate {
+    
+    func pushRegistry(
+        _ registry: PKPushRegistry,
+        didUpdate pushCredentials: PKPushCredentials,
+        for type: PKPushType
+    ) {
+        let token = pushCredentials.token.map { String(format: "%02.2hhx", $0) }.joined()
+        print("VoIP Token: \(token)")
+        
+        // Register VoIP token with CometChat
+        CometChat.registerTokenForPushNotification(
+            token: token,
+            settings: ["voip": true]
+        ) { success in
+            print("VoIP token registered: \(success)")
+        } onError: { error in
+            print("VoIP token registration failed: \(error?.errorDescription ?? "")")
+        }
+    }
+    
+    func pushRegistry(
+        _ registry: PKPushRegistry,
+        didReceiveIncomingPushWith payload: PKPushPayload,
+        for type: PKPushType,
+        completion: @escaping () -> Void
+    ) {
+        print("Received VoIP push: \(payload.dictionaryPayload)")
+        
+        // Handle incoming call
+        if let callData = payload.dictionaryPayload["call"] as? [String: Any] {
+            handleIncomingCall(callData)
+        }
+        
+        completion()
+    }
+    
+    private func handleIncomingCall(_ data: [String: Any]) {
+        // Show incoming call UI
+        // This should use CallKit for proper iOS call handling
+    }
+}
+```
+
+---
+
+## 6. UIKitSettings with Push Tokens
+
+You can also pass tokens during initialization:
+
+```swift
+let uiKitSettings = UIKitSettings()
+    .set(appID: "YOUR_APP_ID")
+    .set(authKey: "YOUR_AUTH_KEY")
+    .set(region: "us")
+    .set(deviceToken: apnsToken)      // APNs token
+    .set(voipToken: voipToken)        // VoIP token
+    .subscribePresenceForAllUsers()
+    .build()
+
+CometChatUIKit(uiKitSettings: uiKitSettings) { result in
+    // ...
+}
+```
+
+---
+
+## 7. Notification Service Extension
+
+For rich notifications with images and custom content:
+
+### Create Extension
+
+1. In Xcode, go to **File** → **New** → **Target**
+2. Select **Notification Service Extension**
+3. Name it (e.g., "NotificationService")
+
+### Implement Extension
+
+```swift
+// NotificationService.swift
+import UserNotifications
+
+class NotificationService: UNNotificationServiceExtension {
+    
+    var contentHandler: ((UNNotificationContent) -> Void)?
+    var bestAttemptContent: UNMutableNotificationContent?
+    
+    override func didReceive(
+        _ request: UNNotificationRequest,
+        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
+    ) {
+        self.contentHandler = contentHandler
+        bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
+        
+        guard let bestAttemptContent = bestAttemptContent else {
+            contentHandler(request.content)
+            return
+        }
+        
+        // Customize notification content
+        if let messageData = request.content.userInfo["message"] as? [String: Any] {
+            customizeNotification(bestAttemptContent, with: messageData)
+        }
+        
+        contentHandler(bestAttemptContent)
+    }
+    
+    private func customizeNotification(
+        _ content: UNMutableNotificationContent,
+        with data: [String: Any]
+    ) {
+        // Set title from sender name
+        if let senderName = data["senderName"] as? String {
+            content.title = senderName
+        }
+        
+        // Set body from message
+        if let messageText = data["text"] as? String {
+            content.body = messageText
+        }
+        
+        // Add image attachment if available
+        if let imageURL = data["imageURL"] as? String,
+           let url = URL(string: imageURL) {
+            downloadAndAttachImage(url, to: content)
+        }
+    }
+    
+    private func downloadAndAttachImage(_ url: URL, to content: UNMutableNotificationContent) {
+        let task = URLSession.shared.downloadTask(with: url) { localURL, _, error in
+            guard let localURL = localURL, error == nil else { return }
+            
+            let tempDir = FileManager.default.temporaryDirectory
+            let tempFile = tempDir.appendingPathComponent(UUID().uuidString + ".jpg")
+            
+            try? FileManager.default.moveItem(at: localURL, to: tempFile)
+            
+            if let attachment = try? UNNotificationAttachment(identifier: "image", url: tempFile) {
+                content.attachments = [attachment]
+            }
+            
+            self.contentHandler?(content)
+        }
+        task.resume()
+    }
+    
+    override func serviceExtensionTimeWillExpire() {
+        if let contentHandler = contentHandler, let bestAttemptContent = bestAttemptContent {
+            contentHandler(bestAttemptContent)
+        }
+    }
+}
+```
+
+---
+
+## 8. Badge Count Management
+
+### Update Badge Count
+
+```swift
+// Set badge count
+UIApplication.shared.applicationIconBadgeNumber = unreadCount
+
+// Clear badge count
+UIApplication.shared.applicationIconBadgeNumber = 0
+```
+
+### Sync with CometChat Unread Count
+
+```swift
+func updateBadgeCount() {
+    CometChat.getUnreadMessageCount { userUnread, groupUnread in
+        var totalUnread = 0
+        
+        for (_, count) in userUnread {
+            totalUnread += count as? Int ?? 0
+        }
+        
+        for (_, count) in groupUnread {
+            totalUnread += count as? Int ?? 0
+        }
+        
+        DispatchQueue.main.async {
+            UIApplication.shared.applicationIconBadgeNumber = totalUnread
+        }
+    } onError: { error in
+        print("Error getting unread count: \(error?.errorDescription ?? "")")
+    }
+}
+```
+
+---
+
+## 9. Testing Push Notifications
+
+### Using Terminal
+
+```bash
+# Test APNs push (requires authentication)
+curl -v \
+  --header "apns-topic: com.yourapp.bundleid" \
+  --header "apns-push-type: alert" \
+  --header "authorization: bearer $JWT_TOKEN" \
+  --data '{"aps":{"alert":"Test message"}}' \
+  --http2 \
+  https://api.push.apple.com/3/device/$DEVICE_TOKEN
+```
+
+### Using CometChat Dashboard
+
+1. Go to CometChat Dashboard
+2. Navigate to **Users**
+3. Select a user
+4. Click **Send Push Notification**
+5. Enter a test message
+6. Send
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|---|---|
+| Token not registering | Ensure device is physical, not simulator |
+| Notifications not received | Check APNs certificate in dashboard |
+| Badge not updating | Check notification permissions |
+| VoIP not working | Ensure VoIP capability is enabled |
+| Notifications delayed | Check APNs environment (dev vs prod) |
+
+---
+
+## Best Practices
+
+1. **Always request permission** before registering for notifications
+2. **Handle token refresh** — tokens can change
+3. **Test on real devices** — simulators don't support push
+4. **Use Notification Service Extension** for rich notifications
+5. **Implement proper deep linking** for notification taps
+6. **Clear badge count** when user opens the app
+7. **Handle both foreground and background** notifications