feat(push): 新增iOS APNs推送通知功能
- 添加推送通知管理器和设备令牌管理 - 实现推送通知权限请求和令牌注册 - 新增推送通知设置页面 - 集成推送通知初始化到应用启动流程 - 添加推送通知API服务和本地存储管理 - 更新个人页面添加推送通知设置入口
This commit is contained in:
richarjiang
267
docs/push-notification-implementation.md
Normal file
267
docs/push-notification-implementation.md
Normal file
@@ -0,0 +1,267 @@
|
||||
# iOS APNs 推送通知集成文档
|
||||
|
||||
## 概述
|
||||
|
||||
本文档描述了如何在数字普拉提应用中集成iOS APNs (Apple Push Notification Service) 推送通知功能。该功能包括设备令牌管理、权限请求和与后端API的交互。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- ✅ 设备令牌自动获取和注册
|
||||
- ✅ 设备令牌更新和注销
|
||||
- ✅ 推送通知权限管理
|
||||
- ✅ 本地通知和远程推送支持
|
||||
- ✅ 用户友好的设置界面
|
||||
- ✅ 错误处理和状态管理
|
||||
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
services/
|
||||
├── pushNotifications.ts # 推送通知API服务
|
||||
├── pushNotificationManager.ts # 推送通知管理器
|
||||
└── notifications.ts # 本地通知服务（已更新）
|
||||
|
||||
hooks/
|
||||
└── usePushNotifications.ts # 推送通知Hook
|
||||
|
||||
app/
|
||||
├── index.tsx # 应用入口（已更新）
|
||||
├── push-notification-settings.tsx # 推送通知设置页面
|
||||
└── (tabs)/personal.tsx # 个人页面（已更新）
|
||||
```
|
||||
|
||||
## API接口
|
||||
|
||||
### 1. 注册设备令牌
|
||||
|
||||
```typescript
|
||||
POST /api/push-notifications/register-token
|
||||
Authorization: Bearer <access_token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"deviceToken": "a9d0ed10e9cfd022a61cb08753f49c5a0b0dfb383697bf9f9d750a1003da19c7",
|
||||
"deviceType": "IOS",
|
||||
"appVersion": "1.0.0",
|
||||
"osVersion": "iOS 15.0",
|
||||
"deviceName": "iPhone 13"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 更新设备令牌
|
||||
|
||||
```typescript
|
||||
PUT /api/push-notifications/update-token
|
||||
Authorization: Bearer <access_token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"currentDeviceToken": "old-device-token",
|
||||
"newDeviceToken": "new-device-token",
|
||||
"appVersion": "1.0.1",
|
||||
"osVersion": "iOS 15.1"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 注销设备令牌
|
||||
|
||||
```typescript
|
||||
DELETE /api/push-notifications/unregister-token
|
||||
Authorization: Bearer <access_token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"deviceToken": "device-token-to-unregister"
|
||||
}
|
||||
```
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 1. 自动初始化
|
||||
|
||||
推送通知功能会在应用启动时自动初始化，无需手动调用。初始化过程包括：
|
||||
|
||||
1. 请求推送通知权限
|
||||
2. 获取设备令牌
|
||||
3. 注册设备令牌到后端
|
||||
4. 设置监听器
|
||||
|
||||
### 2. 使用Hook
|
||||
|
||||
```typescript
|
||||
import { usePushNotifications } from '@/hooks/usePushNotifications';
|
||||
|
||||
function MyComponent() {
|
||||
const {
|
||||
isInitialized,
|
||||
tokenStatus,
|
||||
isLoading,
|
||||
registerToken,
|
||||
getCurrentToken,
|
||||
updateTokenStatus,
|
||||
clearAllData,
|
||||
} = usePushNotifications();
|
||||
|
||||
// 使用状态和方法
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 手动管理令牌
|
||||
|
||||
```typescript
|
||||
import { pushNotificationManager } from '@/services/pushNotificationManager';
|
||||
|
||||
// 注册设备令牌
|
||||
await pushNotificationManager.registerDeviceToken();
|
||||
|
||||
// 更新设备令牌
|
||||
await pushNotificationManager.updateDeviceToken(newToken);
|
||||
|
||||
// 注销设备令牌
|
||||
await pushNotificationManager.unregisterDeviceToken();
|
||||
|
||||
// 获取当前令牌
|
||||
const token = pushNotificationManager.getCurrentToken();
|
||||
```
|
||||
|
||||
### 4. 发送本地通知
|
||||
|
||||
```typescript
|
||||
import { notificationService } from '@/services/notifications';
|
||||
|
||||
// 发送立即通知
|
||||
await notificationService.sendImmediateNotification({
|
||||
title: '标题',
|
||||
body: '内容',
|
||||
data: { type: 'custom' },
|
||||
sound: true,
|
||||
priority: 'high',
|
||||
});
|
||||
|
||||
// 发送定时通知
|
||||
await notificationService.scheduleNotificationAtDate(
|
||||
{
|
||||
title: '定时通知',
|
||||
body: '这是一个定时通知',
|
||||
data: { type: 'scheduled' },
|
||||
},
|
||||
new Date(Date.now() + 60000) // 1分钟后
|
||||
);
|
||||
```
|
||||
|
||||
## 用户界面
|
||||
|
||||
### 推送通知设置页面
|
||||
|
||||
用户可以通过以下路径访问推送通知设置：
|
||||
|
||||
`个人页面 → 通知 → 推送通知设置`
|
||||
|
||||
设置页面包含：
|
||||
|
||||
- 初始化状态显示
|
||||
- 令牌状态信息
|
||||
- 设备令牌显示（部分隐藏）
|
||||
- 手动注册按钮
|
||||
- 状态刷新按钮
|
||||
- 数据清除按钮
|
||||
|
||||
### 个人页面集成
|
||||
|
||||
在个人页面的通知部分添加了"推送通知设置"入口，用户可以：
|
||||
|
||||
- 开启/关闭消息推送
|
||||
- 访问详细的推送通知设置
|
||||
- 查看和管理设备令牌
|
||||
|
||||
## 状态管理
|
||||
|
||||
### 令牌状态
|
||||
|
||||
```typescript
|
||||
enum TokenStatus {
|
||||
UNKNOWN = 'unknown', // 状态未知
|
||||
GRANTED = 'granted', // 权限已授予，但未注册
|
||||
DENIED = 'denied', // 权限被拒绝
|
||||
REGISTERED = 'registered', // 设备令牌已注册
|
||||
FAILED = 'failed', // 初始化失败
|
||||
}
|
||||
```
|
||||
|
||||
### 本地存储
|
||||
|
||||
- `@device_token`: 存储当前设备令牌
|
||||
- `@token_registered`: 标记令牌是否已注册
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 常见错误及解决方案
|
||||
|
||||
1. **权限被拒绝**
|
||||
- 引导用户到系统设置中开启通知权限
|
||||
- 提供友好的错误提示
|
||||
|
||||
2. **设备令牌获取失败**
|
||||
- 检查设备是否支持推送通知
|
||||
- 确保在真实设备上测试（模拟器不支持）
|
||||
|
||||
3. **网络请求失败**
|
||||
- 提供重试机制
|
||||
- 显示网络错误提示
|
||||
|
||||
4. **API调用失败**
|
||||
- 记录详细错误日志
|
||||
- 提供用户友好的错误信息
|
||||
|
||||
## 开发注意事项
|
||||
|
||||
1. **真机测试**
|
||||
- 推送通知功能必须在真实iOS设备上测试
|
||||
- 模拟器无法获取设备令牌
|
||||
|
||||
2. **证书配置**
|
||||
- 确保APNs证书正确配置
|
||||
- Bundle Identifier与证书匹配
|
||||
|
||||
3. **后台模式**
|
||||
- 在`app.json`中启用了`remote-notification`后台模式
|
||||
- 支持后台接收推送通知
|
||||
|
||||
4. **调试技巧**
|
||||
- 使用Xcode控制台查看推送相关日志
|
||||
- 检查设备令牌是否正确获取
|
||||
- 验证API请求和响应
|
||||
|
||||
## 测试建议
|
||||
|
||||
1. **功能测试**
|
||||
- 测试权限请求流程
|
||||
- 验证设备令牌注册
|
||||
- 测试本地通知功能
|
||||
|
||||
2. **边界情况**
|
||||
- 权限被拒绝时的处理
|
||||
- 网络不可用时的行为
|
||||
- 应用被杀死时的推送接收
|
||||
|
||||
3. **性能测试**
|
||||
- 初始化时间测试
|
||||
- 内存使用情况
|
||||
- 电池消耗评估
|
||||
|
||||
## 后续优化
|
||||
|
||||
1. **功能增强**
|
||||
- 添加推送通知统计
|
||||
- 支持通知分类管理
|
||||
- 实现推送消息历史
|
||||
|
||||
2. **用户体验**
|
||||
- 优化设置页面UI
|
||||
- 添加推送通知预览
|
||||
- 提供更详细的状态说明
|
||||
|
||||
3. **技术改进**
|
||||
- 实现令牌自动刷新
|
||||
- 添加推送送达统计
|
||||
- 优化错误恢复机制
|
||||
Reference in New Issue
Block a user