---
title: william-weng/wwapplifecyclemanager
framework: Swift Package Catalog
role: article
path: packages/william-weng/wwapplifecyclemanager
---

# william-weng/wwapplifecyclemanager

[English](./README.en.md) | [正體中文](./README.md)

## ✨ 主要功能

- 讀取目前的遠端通知授權狀態。 - 判斷 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...`

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

```swift 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 回調 |

## 🧪 使用範例

```swift 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