Files

richarjiang 6cdd2fdf9c feat(push): 新增iOS APNs推送通知功能

- 添加推送通知管理器和设备令牌管理
- 实现推送通知权限请求和令牌注册
- 新增推送通知设置页面
- 集成推送通知初始化到应用启动流程
- 添加推送通知API服务和本地存储管理
- 更新个人页面添加推送通知设置入口

2025-10-14 19:25:35 +08:00

5.9 KiB

Raw Blame History

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. 注册设备令牌

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. 更新设备令牌

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. 注销设备令牌

DELETE /api/push-notifications/unregister-token
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "deviceToken": "device-token-to-unregister"
}

使用方法

1. 自动初始化

推送通知功能会在应用启动时自动初始化，无需手动调用。初始化过程包括：

请求推送通知权限
获取设备令牌
注册设备令牌到后端
设置监听器

2. 使用Hook

import { usePushNotifications } from '@/hooks/usePushNotifications';

function MyComponent() {
  const {
    isInitialized,
    tokenStatus,
    isLoading,
    registerToken,
    getCurrentToken,
    updateTokenStatus,
    clearAllData,
  } = usePushNotifications();

  // 使用状态和方法
}

3. 手动管理令牌

import { pushNotificationManager } from '@/services/pushNotificationManager';

// 注册设备令牌
await pushNotificationManager.registerDeviceToken();

// 更新设备令牌
await pushNotificationManager.updateDeviceToken(newToken);

// 注销设备令牌
await pushNotificationManager.unregisterDeviceToken();

// 获取当前令牌
const token = pushNotificationManager.getCurrentToken();

4. 发送本地通知

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分钟后
);

用户界面

推送通知设置页面

用户可以通过以下路径访问推送通知设置：

个人页面 → 通知 → 推送通知设置

设置页面包含：

初始化状态显示
令牌状态信息
设备令牌显示（部分隐藏）
手动注册按钮
状态刷新按钮
数据清除按钮

个人页面集成

在个人页面的通知部分添加了"推送通知设置"入口，用户可以：

开启/关闭消息推送
访问详细的推送通知设置
查看和管理设备令牌

状态管理

令牌状态

enum TokenStatus {
  UNKNOWN = 'unknown',      // 状态未知
  GRANTED = 'granted',      // 权限已授予，但未注册
  DENIED = 'denied',        // 权限被拒绝
  REGISTERED = 'registered', // 设备令牌已注册
  FAILED = 'failed',        // 初始化失败
}

本地存储

@device_token: 存储当前设备令牌
@token_registered: 标记令牌是否已注册

错误处理

常见错误及解决方案

权限被拒绝
- 引导用户到系统设置中开启通知权限
- 提供友好的错误提示
设备令牌获取失败
- 检查设备是否支持推送通知
- 确保在真实设备上测试（模拟器不支持）
网络请求失败
- 提供重试机制
- 显示网络错误提示
API调用失败
- 记录详细错误日志
- 提供用户友好的错误信息

开发注意事项

真机测试
- 推送通知功能必须在真实iOS设备上测试
- 模拟器无法获取设备令牌
证书配置
- 确保APNs证书正确配置
- Bundle Identifier与证书匹配
后台模式
- 在app.json中启用了remote-notification后台模式
- 支持后台接收推送通知
调试技巧
- 使用Xcode控制台查看推送相关日志
- 检查设备令牌是否正确获取
- 验证API请求和响应

测试建议

功能测试
- 测试权限请求流程
- 验证设备令牌注册
- 测试本地通知功能
边界情况
- 权限被拒绝时的处理
- 网络不可用时的行为
- 应用被杀死时的推送接收
性能测试
- 初始化时间测试
- 内存使用情况
- 电池消耗评估

后续优化

功能增强
- 添加推送通知统计
- 支持通知分类管理
- 实现推送消息历史
用户体验
- 优化设置页面UI
- 添加推送通知预览
- 提供更详细的状态说明
技术改进
- 实现令牌自动刷新
- 添加推送送达统计
- 优化错误恢复机制

5.9 KiB Raw Blame History