---
id: REQ-ios-notification-image
group_id: ai-magic-editor
type: Requirement
feature: ios-notification-image
---
<!-- info-section -->
> status: Reviewed
> update_date: 2025-09-30
> summary_context: 讓 iOS App 在背景或關閉時收到推播通知可以顯示圖片
<!-- id: sec-root -->
# 需求文件 (Requirement): iOS Push Notification 圖片顯示
<!-- id: sec-goal-context -->
### 1. 核心目標與背景 (Goal & Context)
<!-- id: blk-goal, type: list -->
**目標 (Goal)**
- 讓 iOS App 的 Push Notification 支援圖片顯示功能，提升通知的視覺效果與資訊傳達能力。
<!-- id: blk-user-story, type: list -->
**使用者故事 (User Story)**
- 身為一個 App 使用者，我想要在收到推播通知時看到圖片，以便更清楚了解通知內容。
<!-- id: blk-context-desc, type: list -->
**背景說明**
- 後端 `REQ-push-notification-api` 已支援發送包含 Image URL 的 FCM payload
- iOS App 目前已整合 Firebase Messaging，但尚未實作圖片顯示功能
- iOS 系統需要透過 Notification Service Extension 來下載並附加圖片到通知內容
<!-- id: sec-functional-scope -->
### 2. 功能與邊界定義 (Functional Scope)
<!-- id: blk-func-req-list, type: list -->
**功能規格 (Functional Requirements)**
- 當後端 FCM payload 包含 `image` URL 且 App 處於背景或關閉狀態時，通知必須顯示該圖片
- 支援常見圖片格式：PNG, JPG, GIF
- 圖片顯示在通知內容中（使用 iOS 系統預設的 Rich Notification 樣式）
- 圖片下載失敗或超時時，退回顯示純文字通知（不阻斷通知發送）
- 實作 Notification Service Extension 來處理圖片下載與附加
<!-- id: blk-out-of-scope-list, type: list -->
**範圍外 (Out of Scope)**
- App 在前景時的圖片通知支援（保持現有行為，未來需求確認後再開發）
- 自訂 Notification UI（Notification Content Extension）
- 通知互動按鈕（Action buttons）
- 影片或其他多媒體格式支援
- 本地圖片支援（只處理遠端 URL）
- 通知歷史記錄功能
- 圖片快取機制（每次重新下載）
<!-- id: sec-non-functional -->
### 3. 非功能規格與限制 (Non-Functional Requirements & Constraints)
<!-- id: blk-non-func-req-list, type: list -->
**非功能規格 (Non-Functional Requirements)**
- **效能**: 圖片下載超時限制為 5 秒，超時後退回純文字通知
- **相容性**: 支援 iOS 14.0 以上版本（與 App 最低支援版本一致）
- **可靠性**: 圖片處理失敗不影響通知本身的正常顯示
- **安全性**: 只接受 HTTPS 圖片 URL
<!-- id: blk-tech-constraints-list, type: list -->
**技術限制**
- 圖片大小遵循 iOS 系統限制（< 10MB）
- Notification Service Extension 有 30 秒執行時間限制
- Service Extension 只在 App 非前景狀態時被系統調用
- 需要設定 FCM payload 的 `mutable-content: 1` 才能觸發 Service Extension
<!-- id: sec-use-cases -->
### 4. 使用場景與驗收標準 (Use Cases & Acceptance)
<!-- id: blk-use-cases-list, type: list -->
**使用場景 (Use Cases)**
- 用戶將 App 切換到背景，後端發送帶有產品圖片的促銷通知，用戶在通知中心看到圖文並茂的通知
- App 完全關閉時，用戶收到包含活動海報的推播，下拉通知後看到完整圖片
- 圖片 URL 失效或網路不佳時，用戶仍能收到純文字通知，不會遺漏重要資訊
- 用戶正在使用 App（前景），收到推播時顯示純文字 banner（現有行為不變）
<!-- id: blk-acceptance-list, type: list -->
**驗收標準 (Acceptance Criteria)**
- App 在背景或關閉狀態時，收到包含有效 `image` URL 的推播，通知必須顯示圖片
- 圖片下載成功後，通知樣式為 Rich Notification（可展開查看完整圖片）
- 圖片下載失敗或超過 5 秒超時，通知退回顯示純文字（標題 + 訊息）
- 只接受 HTTPS 圖片 URL，HTTP URL 視為無效並退回純文字通知
- App 在前景時，通知行為與現有實作一致（不顯示圖片）
- 測試圖片格式：PNG, JPG, GIF 皆可正常顯示
- 後端無需更改 API，沿用現有 FCM payload 格式（需確認 `mutable-content: 1` 設定）