389 lines
12 KiB
Plaintext
389 lines
12 KiB
Plaintext
================================================================================
|
||
OPPO推送服务 - 调测使用说明
|
||
================================================================================
|
||
|
||
一、环境准备
|
||
================================================================================
|
||
|
||
1. 系统要求
|
||
- JDK 1.8 或更高版本
|
||
- Maven 3.6 或更高版本
|
||
- Windows/Linux/Mac 操作系统
|
||
|
||
2. 验证环境
|
||
- 打开命令行，执行：java -version
|
||
- 打开命令行，执行：mvn -version
|
||
- 确保两个命令都能正常显示版本信息
|
||
|
||
3. 项目文件检查
|
||
确保以下文件存在：
|
||
- pom.xml（Maven配置文件）
|
||
- opush-server-sdk-1.1.0.jar（OPPO推送SDK）
|
||
- src/main/resources/application.properties（配置文件）
|
||
- src/main/java/com/oppo/push/（源代码目录）
|
||
|
||
|
||
二、配置说明
|
||
================================================================================
|
||
|
||
1. 配置文件位置
|
||
src/main/resources/application.properties
|
||
|
||
2. 已配置的参数
|
||
- AppKey: bb0819c889ae40cd8bde5a8ad4e670fe
|
||
- AppSecret: 9b5a0e6d560e406dbb70fbb4e0e38098
|
||
- MasterSecret: 9b5a0e6d560e406dbb70fbb4e0e38098（默认与AppSecret相同）
|
||
- 频道ID: previte_message
|
||
- 频道名称: 消息推送
|
||
- 服务端口: 8080
|
||
|
||
3. 配置修改（如需要）
|
||
如果您的MasterSecret与AppSecret不同，请修改配置文件中的：
|
||
oppo.push.masterSecret=您的实际MasterSecret值
|
||
|
||
|
||
三、启动服务
|
||
================================================================================
|
||
|
||
方式一：使用Maven直接运行（推荐）
|
||
----------------------------------------
|
||
1. 打开命令行（CMD或PowerShell）
|
||
2. 进入项目目录：cd d:\oppo_push_server
|
||
3. 执行启动命令：mvn spring-boot:run
|
||
4. 等待启动完成，看到以下信息表示启动成功：
|
||
========================================
|
||
OPPO推送服务已启动
|
||
API地址: http://localhost:8080/api/push
|
||
健康检查: http://localhost:8080/api/push/health
|
||
========================================
|
||
|
||
方式二：打包后运行
|
||
----------------------------------------
|
||
1. 打包项目：mvn clean package
|
||
2. 运行jar包：java -jar target/oppo-push-server-1.0.0.jar
|
||
3. 启动成功后同上
|
||
|
||
|
||
四、API接口说明
|
||
================================================================================
|
||
|
||
1. 健康检查接口
|
||
- 请求方式：GET
|
||
- 请求地址：http://localhost:8080/api/push/health
|
||
- 功能说明：检查服务是否正常运行
|
||
- 返回示例：
|
||
{
|
||
"status": "ok",
|
||
"service": "OPPO Push Server"
|
||
}
|
||
|
||
2. 获取Access Token接口
|
||
- 请求方式：GET
|
||
- 请求地址：http://localhost:8080/api/push/token
|
||
- 功能说明：获取OPPO推送服务的访问令牌
|
||
- 返回示例（成功）：
|
||
{
|
||
"success": true,
|
||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||
}
|
||
- 返回示例（失败）：
|
||
{
|
||
"success": false,
|
||
"message": "获取Access Token失败: 错误信息"
|
||
}
|
||
|
||
3. 发送通讯与服务（原私信）类消息接口
|
||
- 请求方式：POST
|
||
- 请求地址：http://localhost:8080/api/push/send
|
||
- 请求头：Content-Type: application/json
|
||
- 请求体（JSON格式）：
|
||
{
|
||
"targetValue": "设备的registration_id或alias",
|
||
"title": "消息标题",
|
||
"content": "消息内容",
|
||
"messageType": "1"
|
||
}
|
||
- 参数说明：
|
||
* targetValue（必填）：目标设备的标识
|
||
- 可以是registration_id（设备注册ID）
|
||
- 可以是alias（别名）
|
||
- 可以是tag（标签）
|
||
* title（必填）：消息标题
|
||
* content（必填）：消息内容
|
||
* messageType（可选）：消息类型
|
||
- "1"：通知栏消息（默认）
|
||
- "2"：透传消息
|
||
- 返回示例（成功）：
|
||
{
|
||
"success": true,
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"messageId": "xxx",
|
||
"taskId": "xxx"
|
||
}
|
||
}
|
||
- 返回示例（失败）：
|
||
{
|
||
"success": false,
|
||
"code": 1001,
|
||
"message": "错误信息",
|
||
"data": null
|
||
}
|
||
|
||
|
||
五、测试步骤
|
||
================================================================================
|
||
|
||
步骤1：启动服务
|
||
----------------------------------------
|
||
执行：mvn spring-boot:run
|
||
等待服务启动完成
|
||
|
||
步骤2：健康检查
|
||
----------------------------------------
|
||
打开浏览器访问：http://localhost:8080/api/push/health
|
||
或使用curl命令：
|
||
curl http://localhost:8080/api/push/health
|
||
|
||
预期结果：返回 {"status":"ok","service":"OPPO Push Server"}
|
||
|
||
步骤3：获取Token（测试认证）
|
||
----------------------------------------
|
||
使用curl命令：
|
||
curl http://localhost:8080/api/push/token
|
||
|
||
或使用浏览器访问：http://localhost:8080/api/push/token
|
||
|
||
预期结果：返回包含token的JSON，success为true
|
||
|
||
步骤4：准备测试数据
|
||
----------------------------------------
|
||
1. 获取目标设备的registration_id
|
||
- 在您的移动应用中集成OPPO推送SDK
|
||
- 应用启动后，SDK会返回registration_id
|
||
- 记录下这个registration_id用于测试
|
||
|
||
2. 修改test-request.json文件
|
||
将文件中的 "your_registration_id_here" 替换为实际的registration_id
|
||
|
||
步骤5：发送测试消息
|
||
----------------------------------------
|
||
使用curl命令（Windows PowerShell）：
|
||
curl -X POST http://localhost:8080/api/push/send `
|
||
-H "Content-Type: application/json" `
|
||
-d @test-request.json
|
||
|
||
使用curl命令（Linux/Mac）：
|
||
curl -X POST http://localhost:8080/api/push/send \
|
||
-H "Content-Type: application/json" \
|
||
-d @test-request.json
|
||
|
||
或使用Postman：
|
||
1. 创建POST请求
|
||
2. URL: http://localhost:8080/api/push/send
|
||
3. Headers: Content-Type = application/json
|
||
4. Body选择raw，格式选择JSON
|
||
5. 输入以下内容：
|
||
{
|
||
"targetValue": "您的registration_id",
|
||
"title": "测试私信消息",
|
||
"content": "这是一条通讯与服务（原私信）类消息的测试内容",
|
||
"messageType": "1"
|
||
}
|
||
6. 点击Send发送
|
||
|
||
预期结果：
|
||
- 返回success为true
|
||
- 移动设备收到推送通知
|
||
- 通知显示在"消息推送"频道中
|
||
|
||
|
||
六、使用Postman测试（推荐）
|
||
================================================================================
|
||
|
||
1. 导入请求集合
|
||
- 打开Postman
|
||
- 创建新的Collection：OPPO推送测试
|
||
- 添加以下三个请求：
|
||
|
||
2. 健康检查请求
|
||
- 方法：GET
|
||
- URL：http://localhost:8080/api/push/health
|
||
- 点击Send，应该返回成功状态
|
||
|
||
3. 获取Token请求
|
||
- 方法：GET
|
||
- URL：http://localhost:8080/api/push/token
|
||
- 点击Send，应该返回token
|
||
|
||
4. 发送消息请求
|
||
- 方法：POST
|
||
- URL：http://localhost:8080/api/push/send
|
||
- Headers：
|
||
Key: Content-Type
|
||
Value: application/json
|
||
- Body（选择raw，格式JSON）：
|
||
{
|
||
"targetValue": "替换为实际的registration_id",
|
||
"title": "测试标题",
|
||
"content": "测试内容",
|
||
"messageType": "1"
|
||
}
|
||
- 点击Send发送
|
||
|
||
|
||
七、常见问题排查
|
||
================================================================================
|
||
|
||
问题1：服务启动失败
|
||
----------------------------------------
|
||
可能原因：
|
||
- 端口8080被占用
|
||
- JDK版本不兼容
|
||
- Maven依赖下载失败
|
||
|
||
解决方法：
|
||
1. 检查端口占用：netstat -ano | findstr :8080
|
||
2. 修改端口：在application.properties中修改server.port=8081
|
||
3. 检查JDK版本：java -version（需要1.8+）
|
||
4. 清理Maven缓存：mvn clean
|
||
|
||
问题2：获取Token失败
|
||
----------------------------------------
|
||
可能原因：
|
||
- AppKey或MasterSecret配置错误
|
||
- 网络连接问题
|
||
- OPPO服务端异常
|
||
|
||
解决方法：
|
||
1. 检查配置文件中的AppKey和MasterSecret是否正确
|
||
2. 检查网络连接是否正常
|
||
3. 查看控制台日志，确认具体错误信息
|
||
4. 确认在OPPO开放平台已开通推送服务
|
||
|
||
问题3：发送消息失败
|
||
----------------------------------------
|
||
可能原因：
|
||
- Token过期或无效
|
||
- targetValue（registration_id）无效
|
||
- 消息格式错误
|
||
- 设备未在线
|
||
|
||
解决方法：
|
||
1. 重新获取Token：访问 /api/push/token 接口
|
||
2. 确认registration_id是否正确
|
||
3. 检查请求体JSON格式是否正确
|
||
4. 确认目标设备已连接网络且应用在运行
|
||
5. 查看控制台日志获取详细错误信息
|
||
|
||
问题4：设备收不到推送
|
||
----------------------------------------
|
||
可能原因：
|
||
- 设备未正确集成OPPO推送SDK
|
||
- 应用未获得通知权限
|
||
- 设备网络问题
|
||
- 频道配置不正确
|
||
|
||
解决方法：
|
||
1. 确认移动应用已正确集成OPPO推送SDK
|
||
2. 检查应用的通知权限是否开启
|
||
3. 确认设备网络连接正常
|
||
4. 检查频道ID配置是否为"previte_message"
|
||
5. 在OPPO开放平台查看推送统计，确认消息是否已发送
|
||
|
||
问题5：编译错误
|
||
----------------------------------------
|
||
可能原因：
|
||
- 缺少依赖
|
||
- 代码语法错误
|
||
|
||
解决方法：
|
||
1. 执行：mvn clean install
|
||
2. 检查IDE是否显示错误
|
||
3. 确认opush-server-sdk-1.1.0.jar文件存在
|
||
|
||
|
||
八、日志查看
|
||
================================================================================
|
||
|
||
1. 控制台日志
|
||
服务启动后，所有日志会输出到控制台，包括：
|
||
- 服务启动信息
|
||
- Token获取日志
|
||
- 消息发送日志
|
||
- 错误信息
|
||
|
||
2. 关键日志信息
|
||
- "获取Access Token成功"：表示认证成功
|
||
- "发送消息结果"：显示消息发送的详细结果
|
||
- "获取Access Token失败"：表示认证失败，需要检查配置
|
||
- "发送消息异常"：表示发送失败，查看具体错误信息
|
||
|
||
|
||
九、调试技巧
|
||
================================================================================
|
||
|
||
1. 使用健康检查接口确认服务正常运行
|
||
|
||
2. 先测试获取Token，确认认证配置正确
|
||
|
||
3. 使用Postman等工具可以更方便地测试和查看响应
|
||
|
||
4. 查看控制台日志，了解详细的执行过程
|
||
|
||
5. 如果发送失败，先检查：
|
||
- Token是否有效
|
||
- registration_id是否正确
|
||
- 请求格式是否正确
|
||
|
||
6. 建议测试流程：
|
||
健康检查 → 获取Token → 发送消息
|
||
|
||
|
||
十、注意事项
|
||
================================================================================
|
||
|
||
1. Token会自动缓存，有效期约24小时，无需频繁获取
|
||
|
||
2. 确保在OPPO开放平台已正确配置应用信息
|
||
|
||
3. registration_id需要从移动应用端获取，不能随意填写
|
||
|
||
4. 通讯与服务类消息会自动使用配置的频道ID（previte_message）
|
||
|
||
5. 测试时建议使用真实的设备registration_id
|
||
|
||
6. 如果MasterSecret与AppSecret不同，务必更新配置文件
|
||
|
||
7. 生产环境建议将敏感信息（AppKey、Secret等）配置为环境变量
|
||
|
||
8. 通讯与服务类消息说明：
|
||
- 根据OPPO官方文档（https://open.oppomobile.com/documentation/page/info?id=13189）
|
||
- 必须设置 channel_id 为 "previte_message"
|
||
- 必须设置 channel_name 为 "消息推送"
|
||
- 这些参数已在代码中自动配置，无需手动设置
|
||
- 消息会显示在OPPO手机的"消息推送"频道中
|
||
|
||
|
||
十一、技术支持
|
||
================================================================================
|
||
|
||
1. OPPO推送服务文档
|
||
- 通讯与服务类消息文档：https://open.oppomobile.com/documentation/page/info?id=13189
|
||
- 推送服务总文档：https://open.oppomobile.com/documentation/page/info?id=11233
|
||
|
||
2. 查看项目文档
|
||
- README.md：项目总体说明
|
||
- 通讯与服务类消息说明.md：通讯与服务类消息详细说明
|
||
|
||
3. 查看控制台日志获取详细错误信息
|
||
|
||
4. 检查OPPO开放平台的推送统计，确认消息发送状态
|
||
|
||
|
||
================================================================================
|
||
祝您测试顺利！
|
||
================================================================================
|
||
|