Contents

william-weng/wwapplifecyclemanager

English | 正體中文

✨ 主要功能

  • 讀取目前的遠端通知授權狀態。
  • 判斷 App 是否已獲得通知授權。
  • 向 Apple Push Notification service（APNs）註冊並取得 Device Token。
  • 清除所有本機通知。
  • 處理 App 冷啟動時由通知觸發的連線資訊。
  • 監聽通知收到、通知點擊，以及通知啟動 App 等事件。
  • 監聽 Scene 的完整生命週期。
  • 處理 URL Scheme 與 Universal Link。
  • 處理 Handoff、Siri Shortcut 與其他 NSUserActivity。
  • 使用 @discardableResult 支援鏈式設定 API。

📦 安裝方式

使用 Swift Package Manager

在 Xcode 中選擇：

File → Add Package Dependencies...

接著輸入套件 repository URL，選擇要使用的版本，並將套件加入 App target。

如果這是本地套件，也可以在 Xcode 中使用：

File → Add Package Dependencies... → Add Local...

安裝完成後，將該套件匯入目標後，就可以使用了：

import WWAppLifeCycleManager

🧱 API 總覽

| API | 說明 | | --- | --- | | status | 非同步取得 UNAuthorizationStatus | | isAuthorized | 非同步判斷通知狀態是否為 .authorized | | notificationResponse | 冷啟動通知的 UNNotificationResponse，用於初始化路由 | | deviceToken | APNs 註冊成功後取得的 Data 型別 deviceToken | | register() | 註冊 APNs 遠端通知 | | cancel() | 清除本機通知 | | onRegisterNotifications(perform:) | 設定 APNs 註冊結果回調 | | onNotification(:perform:) | 設定通知啟動、收到、點擊回調 | | onSceneWillConnect(perform:) | 設定 Scene 連線回調 | | onScene(:perform:) | 設定 Scene 生命週期回調 | | onOpenURL(perform:) | 設定 URL 回調 | | onContinueUserActivity(perform:) | 設定 User Activity 回調 |

🧪 使用範例

import SwiftUI
import WWAppLifeCycleManager

@main
struct ExampleApp: App {
    
    @UIApplicationDelegateAdaptor(WWAppDelegate.self) private var appDelegate
    @State private var notificationState = NotificationState.shared
    
    var body: some Scene {
        
        WindowGroup {
            ContentView()
                .task { await notificationManagerSetting() }
                .environment(notificationState)
        }
    }
}

private extension ExampleApp {
    
    func notificationManagerSetting() async {
        
        WWAppLifeCycleManager.shared
            .onRegisterNotifications { result in
                switch result {
                case .success(let token): notificationState.localNotification(body: "token: \(token.hexString)")
                case .failure(let error): notificationState.localNotification(body: "error: \(error.localizedDescription)")
                }
            }
            .onNotification(.received) { userInfo in
                print("📬 [App 運行中] 收到通知：\(userInfo)")
            }
            .onNotification(.tapped) { userInfo in
                print("👆 [用戶點擊] 通知點擊：\(userInfo)")
                notificationState.handleNotification(userInfo)
            }
        
        await WWAppLifeCycleManager.shared.register()
        
        let granted = await WWAppLifeCycleManager.shared.isAuthorized
        print("🔐 通知權限狀態: \(granted ? "已授予" : "未授予")")
    }
}

⚠️ 注意事項

  • 在 Apple Developer 帳號啟用 Push Notifications capability。
  • 在 Xcode Target 的 Signing & Capabilities 加入 Push Notifications。
  • register() 必須使用 await 呼叫，因為它是非同步 API。
  • 回調註冊依賴已注入的 appDelegate 或 sceneDelegate；若尚未完成注入，guard 會直接返回 self，回調不會被設定。
  • 建議在生命週期代理完成初始化後，再註冊需要依賴 Delegate 的回調。
  • 每個事件目前看起來只保存一個 handler；重複設定時，後一次設定會覆蓋前一次設定。
  • notificationResponse 是公開可變屬性，若多個模組同時讀寫，請自行管理資料一致性。
  • 建議測試冷啟動、背景收到通知、前景收到通知、通知點擊、URL 啟動及 Scene 重連等情境。
  • onOpenURL 與 onContinueUserActivity 的文件提到 action 參數，但目前函式簽名沒有此參數；使用時應以現有函式簽名為準。

Package Metadata

Repository: william-weng/wwapplifecyclemanager

Default branch: main

README: README.md