richard/plates-server

Fork 0

Files

richarjiang 4f9d648a50 feat: 初始化项目

2025-08-13 15:17:33 +08:00

4.7 KiB

Raw Blame History

App Store 服务器通知接收接口

概述

本接口用于接收来自苹果App Store的服务器通知（App Store Server Notifications V2），处理用户订阅状态的变化，包括订阅、续订、过期、退款等事件。

接口地址

POST /api/users/app-store-notifications

配置要求

1. 在App Store Connect中配置

登录 App Store Connect
选择你的应用
在左侧菜单中选择 "App信息"
滚动到 "App Store服务器通知" 部分
设置生产环境URL：https://your-domain.com/api/users/app-store-notifications
设置沙盒环境URL：https://your-domain.com/api/users/app-store-notifications
选择 "Version 2" 通知格式
保存设置

2. 环境变量配置

确保以下环境变量已正确设置：

# Apple相关配置
APPLE_BUNDLE_ID=com.yourcompany.yourapp
APPLE_KEY_ID=your_key_id
APPLE_ISSUER_ID=your_issuer_id
APPLE_PRIVATE_KEY_PATH=path/to/your/private/key.p8
APPLE_APP_SHARED_SECRET=your_shared_secret

请求格式

请求头

Content-Type: application/json

请求体

{
  "signedPayload": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjEyMzQ1Njc4OTAiLCJ0eXAiOiJKV1QifQ..."
}

响应格式

成功响应

{
  "code": 200,
  "message": "通知处理成功",
  "data": {
    "processed": true,
    "notificationType": "SUBSCRIBED",
    "notificationUUID": "12345678-1234-1234-1234-123456789012",
    "userId": "user_12345",
    "transactionId": "1000000123456789"
  }
}

错误响应

{
  "code": 500,
  "message": "处理通知失败: 无法解码通知负载",
  "data": {
    "processed": false
  }
}

支持的通知类型

1. SUBSCRIBED（订阅）

描述: 用户首次订阅或重新订阅
处理: 更新用户的订阅状态和到期时间

2. DID_RENEW（续订）

描述: 订阅成功续订
处理: 延长用户的订阅到期时间

3. EXPIRED（过期）

描述: 订阅已过期
处理: 可以发送邮件通知或降级用户权限

4. DID_FAIL_TO_RENEW（续订失败）

描述: 订阅续订失败（通常是支付问题）
处理: 发送付款提醒或进入宽限期

5. REFUND（退款）

描述: 用户获得退款
处理: 立即撤销用户的订阅权限

6. REVOKE（撤销）

描述: 通过家庭共享获得的权限被撤销
处理: 撤销用户的订阅权限

7. DID_CHANGE_RENEWAL_STATUS（续订状态变更）

描述: 用户更改了自动续订设置
处理: 记录用户的续订偏好

8. TEST（测试）

描述: 测试通知
处理: 仅记录日志，无特殊处理

安全考虑

1. 签名验证

接口会验证通知的JWS签名
确保通知来自苹果官方服务器
验证bundleId匹配

2. 重复处理

建议实现幂等性处理
根据notificationUUID去重
避免重复处理相同通知

3. 错误处理

对于无法处理的通知，返回适当的HTTP状态码
苹果会根据响应状态码决定是否重试

日志记录

接口会记录以下信息：

收到的通知类型和UUID
解码后的交易信息
处理结果和任何错误
用户ID和交易ID（如果可用）

测试

1. 使用App Store Connect测试

在App Store Connect中请求测试通知
检查服务器日志确认收到通知
验证通知处理逻辑是否正确

2. 沙盒环境测试

使用沙盒环境进行购买测试
观察通知是否正确触发
验证用户状态是否正确更新

故障排除

常见问题

收不到通知
- 检查App Store Connect中的URL配置
- 确保服务器可以从外网访问
- 检查防火墙设置
通知解码失败
- 验证私钥文件路径和格式
- 检查环境变量配置
- 确认bundleId匹配
用户状态未更新
- 检查appAccountToken是否正确设置
- 验证用户ID映射逻辑
- 查看数据库更新日志

日志查看

# 查看相关日志
grep "App Store" /path/to/your/logs/app.log
grep "processAppStoreNotification" /path/to/your/logs/app.log

扩展功能

可以根据业务需求扩展以下功能：

邮件通知: 在特定事件发生时发送邮件
数据分析: 收集订阅数据用于分析
第三方集成: 将事件发送到其他系统
自定义业务逻辑: 根据不同的通知类型执行特定操作

4.7 KiB Raw Blame History Unescape Escape