190 lines
4.7 KiB
Markdown
190 lines
4.7 KiB
Markdown
# App Store 服务器通知接收接口
|
||
|
||
## 概述
|
||
|
||
本接口用于接收来自苹果App Store的服务器通知（App Store Server Notifications V2），处理用户订阅状态的变化，包括订阅、续订、过期、退款等事件。
|
||
|
||
## 接口地址
|
||
|
||
```
|
||
POST /api/users/app-store-notifications
|
||
```
|
||
|
||
## 配置要求
|
||
|
||
### 1. 在App Store Connect中配置
|
||
|
||
1. 登录 [App Store Connect](https://appstoreconnect.apple.com)
|
||
2. 选择你的应用
|
||
3. 在左侧菜单中选择 "App信息"
|
||
4. 滚动到 "App Store服务器通知" 部分
|
||
5. 设置生产环境URL：`https://your-domain.com/api/users/app-store-notifications`
|
||
6. 设置沙盒环境URL：`https://your-domain.com/api/users/app-store-notifications`
|
||
7. 选择 "Version 2" 通知格式
|
||
8. 保存设置
|
||
|
||
### 2. 环境变量配置
|
||
|
||
确保以下环境变量已正确设置：
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
### 请求体
|
||
```json
|
||
{
|
||
"signedPayload": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjEyMzQ1Njc4OTAiLCJ0eXAiOiJKV1QifQ..."
|
||
}
|
||
```
|
||
|
||
## 响应格式
|
||
|
||
### 成功响应
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "通知处理成功",
|
||
"data": {
|
||
"processed": true,
|
||
"notificationType": "SUBSCRIBED",
|
||
"notificationUUID": "12345678-1234-1234-1234-123456789012",
|
||
"userId": "user_12345",
|
||
"transactionId": "1000000123456789"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
```json
|
||
{
|
||
"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测试
|
||
1. 在App Store Connect中请求测试通知
|
||
2. 检查服务器日志确认收到通知
|
||
3. 验证通知处理逻辑是否正确
|
||
|
||
### 2. 沙盒环境测试
|
||
1. 使用沙盒环境进行购买测试
|
||
2. 观察通知是否正确触发
|
||
3. 验证用户状态是否正确更新
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **收不到通知**
|
||
- 检查App Store Connect中的URL配置
|
||
- 确保服务器可以从外网访问
|
||
- 检查防火墙设置
|
||
|
||
2. **通知解码失败**
|
||
- 验证私钥文件路径和格式
|
||
- 检查环境变量配置
|
||
- 确认bundleId匹配
|
||
|
||
3. **用户状态未更新**
|
||
- 检查appAccountToken是否正确设置
|
||
- 验证用户ID映射逻辑
|
||
- 查看数据库更新日志
|
||
|
||
### 日志查看
|
||
```bash
|
||
# 查看相关日志
|
||
grep "App Store" /path/to/your/logs/app.log
|
||
grep "processAppStoreNotification" /path/to/your/logs/app.log
|
||
```
|
||
|
||
## 扩展功能
|
||
|
||
可以根据业务需求扩展以下功能：
|
||
|
||
1. **邮件通知**: 在特定事件发生时发送邮件
|
||
2. **数据分析**: 收集订阅数据用于分析
|
||
3. **第三方集成**: 将事件发送到其他系统
|
||
4. **自定义业务逻辑**: 根据不同的通知类型执行特定操作
|
||
|
||
## 相关文档
|
||
|
||
- [App Store Server Notifications](https://developer.apple.com/documentation/appstoreservernotifications)
|
||
- [App Store Server API](https://developer.apple.com/documentation/appstoreserverapi)
|
||
- [StoreKit 2](https://developer.apple.com/documentation/storekit) |