richard/plates-server

Fork 0

Files

richarjiang 305a969912 feat: 支持 push

2025-10-11 17:38:04 +08:00

11 KiB

Raw Blame History

iOS推送功能使用指南

概述

本文档详细介绍了如何使用iOS远程推送功能，包括API接口使用、配置说明和代码示例。

环境配置

1. 环境变量配置

在.env文件中添加以下配置：

# APNs配置
APNS_KEY_ID=your_key_id
APNS_TEAM_ID=your_team_id
APNS_KEY_PATH=path/to/APNsAuthKey_XXXXXXXXXX.p8
APNS_BUNDLE_ID=com.yourcompany.yourapp
APNS_ENVIRONMENT=production # or sandbox

# 推送服务配置
APNS_CLIENT_COUNT=2
APNS_CONNECTION_RETRY_LIMIT=3
APNS_HEARTBEAT=60000
APNS_REQUEST_TIMEOUT=5000

2. APNs认证文件

登录 Apple Developer Portal
导航到 "Certificates, Identifiers & Profiles"
选择 "Keys"
创建新的密钥，并启用 "Apple Push Notifications service"
下载.p8格式的私钥文件
将私钥文件安全地存储在服务器上

3. 数据库迁移

执行以下SQL脚本创建推送相关的数据表：

mysql -u username -p database_name < sql-scripts/push-notifications-tables-create.sql

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"
}

响应示例：

{
  "code": 0,
  "message": "设备令牌注册成功",
  "data": {
    "success": true,
    "tokenId": "uuid-token-id"
  }
}

更新设备令牌

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"
}

注销设备令牌

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

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

2. 推送消息发送

发送单个推送通知

POST /api/push-notifications/send
Content-Type: application/json

{
  "userIds": ["user_123", "user_456"],
  "title": "训练提醒",
  "body": "您今天的普拉提训练还未完成，快来打卡吧！",
  "payload": {
    "type": "training_reminder",
    "trainingId": "training_123"
  },
  "pushType": "ALERT",
  "priority": 10,
  "sound": "default",
  "badge": 1
}

响应示例：

{
  "code": 0,
  "message": "推送发送成功",
  "data": {
    "success": true,
    "sentCount": 2,
    "failedCount": 0,
    "results": [
      {
        "userId": "user_123",
        "deviceToken": "device-token-1",
        "success": true
      },
      {
        "userId": "user_456",
        "deviceToken": "device-token-2",
        "success": true
      }
    ]
  }
}

使用模板发送推送

POST /api/push-notifications/send-by-template
Content-Type: application/json

{
  "userIds": ["user_123"],
  "templateKey": "training_reminder",
  "data": {
    "userName": "张三",
    "trainingName": "核心力量训练"
  },
  "payload": {
    "type": "training_reminder",
    "trainingId": "training_123"
  }
}

批量发送推送

POST /api/push-notifications/send-batch
Content-Type: application/json

{
  "userIds": ["user_123", "user_456", "user_789"],
  "title": "系统通知",
  "body": "系统将于今晚22:00进行维护，请提前保存您的工作。",
  "payload": {
    "type": "system_maintenance",
    "maintenanceTime": "22:00"
  }
}

发送静默推送

POST /api/push-notifications/send-silent
Content-Type: application/json

{
  "userId": "user_123",
  "payload": {
    "type": "data_sync",
    "syncData": true
  }
}

3. 推送模板管理

获取所有模板

GET /api/push-notifications/templates
Authorization: Bearer <access_token>

创建推送模板

POST /api/push-notifications/templates
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "templateKey": "custom_reminder",
  "title": "自定义提醒",
  "body": "您好{{userName}}，{{reminderContent}}",
  "payloadTemplate": {
    "type": "custom_reminder",
    "reminderId": "{{reminderId}}"
  },
  "pushType": "ALERT",
  "priority": 8
}

更新推送模板

PUT /api/push-notifications/templates/:id
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "title": "更新后的标题",
  "body": "更新后的内容：{{userName}}，{{reminderContent}}",
  "isActive": true
}

删除推送模板

DELETE /api/push-notifications/templates/:id
Authorization: Bearer <access_token>

代码示例

1. 在业务服务中使用推送功能

import { Injectable } from '@nestjs/common';
import { PushNotificationsService } from '../push-notifications/push-notifications.service';

@Injectable()
export class TrainingService {
  constructor(
    private readonly pushNotificationsService: PushNotificationsService,
  ) {}

  async sendTrainingReminder(userId: string, trainingName: string): Promise<void> {
    // 使用模板发送推送
    await this.pushNotificationsService.sendNotificationByTemplate({
      userIds: [userId],
      templateKey: 'training_reminder',
      data: {
        userName: '用户', // 可以从用户服务获取
        trainingName,
      },
      payload: {
        type: 'training_reminder',
        trainingId: 'training_123',
      },
    });
  }

  async sendWorkoutCompletionNotification(userId: string, workoutName: string, calories: number): Promise<void> {
    // 直接发送推送
    await this.pushNotificationsService.sendNotification({
      userIds: [userId],
      title: '训练完成',
      body: `太棒了！您已完成${workoutName}训练，消耗了${calories}卡路里。`,
      payload: {
        type: 'workout_completed',
        workoutId: 'workout_123',
        calories,
      },
      sound: 'celebration.caf',
      badge: 1,
    });
  }
}

2. 在控制器中处理设备令牌注册

import { Controller, Post, Body, UseGuards } from '@nestjs/common';
import { ApiTags, ApiOperation } from '@nestjs/swagger';
import { PushNotificationsService } from '../push-notifications/push-notifications.service';
import { RegisterDeviceTokenDto } from '../push-notifications/dto/register-device-token.dto';
import { CurrentUser } from '../common/decorators/current-user.decorator';
import { AccessTokenPayload } from '../users/services/apple-auth.service';
import { JwtAuthGuard } from '../common/guards/jwt-auth.guard';

@ApiTags('用户设备')
@Controller('user/device')
@UseGuards(JwtAuthGuard)
export class UserDeviceController {
  constructor(
    private readonly pushNotificationsService: PushNotificationsService,
  ) {}

  @Post('register-token')
  @ApiOperation({ summary: '注册设备推送令牌' })
  async registerDeviceToken(
    @CurrentUser() user: AccessTokenPayload,
    @Body() registerTokenDto: RegisterDeviceTokenDto,
  ) {
    return this.pushNotificationsService.registerToken(user.sub, registerTokenDto);
  }
}

预定义推送模板

系统已预置以下推送模板：

1. 训练提醒 (training_reminder)

用途: 提醒用户完成训练
变量: {{userName}}, {{trainingName}}
示例: "您好张三，您今天的核心力量训练还未完成，快来打卡吧！"

2. 饮食记录提醒 (diet_record_reminder)

用途: 提醒用户记录饮食
变量: {{userName}}
示例: "您好张三，您还没有记录今天的饮食，记得及时记录哦！"

3. 挑战进度 (challenge_progress)

用途: 通知用户挑战进度
变量: {{challengeName}}, {{progress}}
示例: "恭喜您！您已完成30天挑战的50%，继续加油！"

4. 会员到期提醒 (membership_expiring)

用途: 提醒用户会员即将到期
变量: {{userName}}, {{days}}
示例: "您好张三，您的会员将在7天后到期，请及时续费以免影响使用。"

5. 会员已到期 (membership_expired)

用途: 通知用户会员已到期
变量: {{userName}}
示例: "您好张三，您的会员已到期，请续费以继续享受会员服务。"

6. 成就解锁 (achievement_unlocked)

用途: 庆祝用户解锁成就
变量: {{achievementName}}
示例: "恭喜您解锁了"连续训练7天"成就！"

7. 训练完成 (workout_completed)

用途: 确认用户完成训练
变量: {{workoutName}}, {{calories}}
示例: "太棒了！您已完成核心力量训练，消耗了150卡路里。"

错误处理

常见错误码

错误码	描述	解决方案
400	请求参数错误	检查请求参数格式和必填字段
401	未授权访问	确保提供了有效的访问令牌
404	资源不存在	检查用户ID或模板键是否正确
429	请求频率过高	降低请求频率，实现退避重试
500	服务器内部错误	检查服务器日志，联系技术支持

APNs错误处理

系统会自动处理以下APNs错误：

Unregistered: 自动停用无效的设备令牌
BadDeviceToken: 记录错误并停用令牌
DeviceTokenNotForTopic: 记录错误日志
TooManyRequests: 实现退避重试机制
InternalServerError: 自动重试

监控和日志

1. 推送状态监控

可以通过以下方式监控推送状态：

// 获取推送统计
const stats = await this.pushMessageService.getMessageStats();
console.log(`推送成功率: ${stats.successRate}%`);
console.log(`错误分布:`, stats.errorBreakdown);

2. 日志查看

推送相关日志包含以下信息：

推送请求和响应
APNs连接状态
错误详情和堆栈跟踪
性能指标

最佳实践

1. 推送时机

避免在深夜或凌晨发送推送
根据用户时区调整推送时间
尊重用户的推送偏好设置

2. 推送内容

保持推送内容简洁明了
使用个性化内容提高用户参与度
避免发送过于频繁的推送

3. 性能优化

使用批量推送减少网络请求
实现推送优先级管理
定期清理无效的设备令牌

4. 安全考虑

保护用户隐私数据
实现推送内容审核机制
使用HTTPS进行API通信

故障排除

1. 推送不生效

检查APNs配置是否正确
验证设备令牌是否有效
确认Bundle ID是否匹配

2. 推送延迟

检查网络连接状态
验证APNs服务器状态
调整推送优先级设置

3. 设备令牌失效

实现令牌自动更新机制
定期清理无效令牌
监控令牌失效率

扩展功能

1. 推送统计分析

实现推送打开率统计
分析用户行为数据
优化推送策略

2. A/B测试

实现推送内容A/B测试
比较不同推送策略效果
优化推送转化率

3. 多平台支持

扩展Android推送功能
统一推送接口设计
实现平台特定功能

总结

iOS推送功能已完全集成到系统中，提供了完整的推送令牌管理、消息发送和模板系统。通过遵循本指南，您可以轻松地在应用中实现各种推送场景，提升用户体验和参与度。

如有任何问题或需要进一步的技术支持，请参考相关文档或联系开发团队。

11 KiB Raw Blame History Unescape Escape