6cdd2fdf9c
- 添加推送通知管理器和设备令牌管理 - 实现推送通知权限请求和令牌注册 - 新增推送通知设置页面 - 集成推送通知初始化到应用启动流程 - 添加推送通知API服务和本地存储管理 - 更新个人页面添加推送通知设置入口
267 lines
5.9 KiB
Markdown
267 lines
5.9 KiB
Markdown
# 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. **技术改进**
|
|
- 实现令牌自动刷新
|
|
- 添加推送送达统计
|
|
- 优化错误恢复机制 |