================================================================================ 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开放平台的推送统计，确认消息发送状态 ================================================================================ 祝您测试顺利！ ================================================================================