update readme

2022-09-23 16:29:10 +08:00
parent 583016231c
commit c9b4383cec
2 changed files with 122 additions and 56 deletions
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 # 野火IM 推送服务
 作为野火IM的推送服务的演示，支持小米、华为、魅族、OPPO、Vivo、苹果apns和谷歌FCM。并且可以添加更多的推送厂商和自定义推送模式。

-#### 工作原理
+## 工作原理
 推送功能对于所有IM来说都是非常重要的功能，然而android系统又没有统一的推送服务，对接起来难度很大。另外一方面客户有不同对接需求，有的要求使用第三方，有的要求使用厂商推送，有的需要在海外添加谷歌推送，有的对推送的格式有不同的要求。

 为了满足各种各样的需求，提供足够好的灵活性，野火IM把推送子系统独立出来，客户只要理解了推送子系统运行的原理，就能做好各种自定义处理。
@@ -15,60 +15,10 @@
 4. 推送服务接收到IM服务的请求，把推送数据放到消费队列中并立即返回（IM服务不能被阻塞），然后逐步处理推送事件。每个推送事件中都包含了所有需要处理的数据，其中包括1步骤中的推送Token和类型，然后根据类型来调用对用推送厂商的服务，比如华为/小米/苹果/第三方厂商/谷歌/OPPO/Vivo等，调用他们的SDK进行推送。


-#### 申请推送服务
-客户需要自行去厂商申请推送服务并替换配置文件中的各项参数。我们提供的默认参数是服务工作的，需要替换。不排除推送厂商sdk接口有变化，需要自行调试，如果发现我们demo有问题，欢迎给我们提PR。
+## 接入推送
+接入推送并不是简单得将推送服务跑起来即可，请详细阅读[接入推送流程](./push.md)

-#### 编译
-```
-mvn package
-```
-
-#### 修改配置
-本演示服务有1个工程配置文件和7个推送配置文件在工程的```config```目录下，请配置服务的端口和各个推送服务相关配置。如果有无法支持的推送类型，请修改客户端去掉不支持的类型（注意这里的配置文件要保留）。
-请正确配置放到jar包所在的目录下的```config```目录下。
-
-#### 证书
-苹果和谷歌推送需要证书，请把对应证书分别放到apns和fcm目录下，然后修改配置文件中的证书路径。
-同样把apns和fcm目录放到jar包所在目录
-
-#### 运行
-在```target```目录找到```push-XXXX.jar```，把jar包和放置配置文件的```config```目录放到一起，然后执行下面命令：
-```
-java -jar push-XXXXX.jar
-```
-
-#### 修改IM服务配置
-修改IM服务的配置文件```wildfirechat.conf```，指向推送服务器的地址，修改完后需要重启
-```
-#*********************************************************************
-# Push server configuration
-#*********************************************************************
-##安卓推送服务器地址
-push.android.server.address http://localhost:8085/android/push
-##苹果推送服务器地址
-push.ios.server.address http://localhost:8085/ios/push
-```
-
-#### Android客户端的修改
-Android客户端Push SDK是处理推送注册及接收的地方。这里是客户端进行推送对接的地方，有几点需要注意修改：
-1. 选取您期望的推送，默认是加上了常见推送SDK，但实际上都会有各种原因只能选取部分，需要屏蔽掉您不需要的推送类型。
-2. 如果支持FCM，需要判断是选取FCM还是国内推送厂商的问题。我们处理比较简单，如果你们能够更精准的判断，需要加上你们自己的判断。
-
-#### 问题排查
-如果遇到问题请按照以下步骤排查：
-1. 确保程序是非启动状态，如果退回到桌面，应用还是激活的还会继续收消息，此时就不会走推送服务。应用在后台激活状态时应该走本地通知。
-2. 确认客户端推送SDK是否正确的获取到token，是否调用了setDeviceToken，token和type是多少？
-3. 确认消息是否是自定义消息，如果是自定义消息，push content是否带上有内容？自定义消息只有push content不为空才会推送。
-4. 确认目标客户端是否7日之内登录过，超过7天是不推送的。
-5. 确认目标客户是否设置了全局静音或会话静音。
-6. 如果有pc和web端登陆，确认是否设定了pc在线时手机静音。
-7. 确认推送服务是否收到了推送信息，如果收到，token和type是否和步骤1一致，推送内容是否和2一致？
-8. 如果推送内容正确到达推送服务，则后面的排查就跟IM服务完全无关了，是推送厂商推送服务的调试，需要客户自己按照推送厂商的官方文档进行调试。
-
-#### 其它注意事项
-Android推送服务有透传推送和通知栏推送两种推送方式，各个厂商的支持程度各异，一般情况下透传推送客户体验更好，但需要开通额外的权限比如自启动和后台等，需要用户进行设置；通知栏推送更简单，只弹出通知栏不拉起应用，但在音视频来电处理上赶不上透传，好处是不需要用户手动设置。我们提供的demo中使用的方式并不一定是最适合您的，还需要您根据实际情况来调整使用透传或通知栏。
-
-#### 添加其它推送服务
+## 添加其它推送服务
 由前面的介绍可以看出，推送子服务是独立于IM服务，而且客户端和服务器部分都是开源的，而且考虑到了扩展性，可以很容易地添加其它推送类型。具体步骤如下：
 1. 必须理解推送的工作原理，知道流程是：客户端注册推送-》客户端注册推送成功得到deviceToken-》客户端调用设置deviceToken和类型，这两个数据被存储到IM服务。当IM服务需要推送时，IM服务打包推送信息（包括deviceToken和类型）请求到推送服务-》推送服务根据类型选择服务商推送数据。
 2. 客户端扩展一个新的推送类型。
@@ -76,8 +26,8 @@ Android推送服务有透传推送和通知栏推送两种推送方式，各个
 4. 在注册成功后会得到deviceToken，调用IM SDK的setDeviceToken接口传人deviceToken和类型。
 5. 推送服务添加对这种类型的处理。

-#### 使用到的开源代码
+## 使用到的开源代码
 1. [TypeBuilder](https://github.com/ikidou/TypeBuilder) 一个用于生成泛型的简易Builder

-#### LICENSE
+## LICENSE
 UNDER MIT LICENSE. 详情见LICENSE文件
--- a/push.md
+++ b/push.md
@@ -0,0 +1,116 @@
+## 接入推送流程
+1. 申请厂商推送服务
+2. 移动端配置
+3. 配置和部署推送服务(push-server)
+4. IM-Server 配置
+5. 推送测试
+6. 问题排查
+7. 常见问题
+
+### 申请厂商推送服务
+目前支持小米、华为、vivo、oppo、魅族、苹果等推送，需要到各个厂商的开发者后台申请推送相关 key
+
+### 移动端配置
+#### Android 端配置
+Android端，推送相关的代码，都在```push module``` 下面，入口是```PushService```，配置之后，如果能调用```ChatManager#setDeviceToken```，则表示配置成，下面是具体的配置
+
+1. 修改```push/build.gradle```下推送相关配置信息，如下:
+    ```
+    // 默认配置的 appid 和 appkey 不可以直接使用
+    manifestPlaceholders = [
+
+            MI_APP_ID    : "2882303761517722456",
+            MI_APP_KEY   : "5731772292456",
+
+            HMS_APP_ID   : "100221325",
+
+            MEIZU_APP_ID : "113616",
+            MEIZU_APP_KEY: "fcd886f51c144b45b87a67a28e2934d1",
+
+            VIVO_APP_ID  : "12918",
+            VIVO_APP_KEY : "c42feb05-de6c-427d-af55-4f902d9e0a75",
+
+            OPPO_APP_KEY  : "16c6afe503b24259928e082ef01a6bf2",
+            OPPO_APP_SECRET : "16c6afe503b24259928e082ef01a6bf2"
+    ]
+    ```
+2. 华为推送需要```chat/agconnect-services.json```文件，该文件是华为推送后台生成的
+3. FCM推送需要替换```push/google-services.json```文件，该文件是 FCM 推送后台生成的
+4. 如果一切正常，启动 App 之后，会打印一行日志，**如果没有打印该日志，则说明配置错误，请查看日志，或者在```PushService```打断点调试**
+
+    ```Log.d(TAG, "setDeviceToken" + token + " " + pushType);// 这是打印日志的代码！！ ```
+5. 如果不需要某些推送类型，可以将其从```push module```删除，保留也不影响
+6. 如果需要使用个推，请看```getui```分支
+
+#### iOS 端配置
+
+### 配置和部署推送服务
+1. 修改配置
+
+   本推送服务有1个工程配置文件和7个推送配置文件，都在工程的```config```目录下，请根据实际情况配置服务的端口和各个推送服务配置，推送服务配置一定要和移动端对应上，别配置成不同的 app 去了。
+
+   如果有无法支持的推送类型，请修改客户端去掉不支持的类型（注意这里的配置文件要保留）。
+
+2. 配置证书
+
+    苹果和谷歌推送需要证书，请把对应证书分别放到```apns```和```fcm```目录下，然后修改配置文件中的证书路径。
+
+3. 编译
+    ```
+    mvn package
+    ```
+
+4. 运行
+    编译成功之后，在```target```目录找到```push-xxxx.jar```，然后把jar包、```config```目录、```apns```和```fcm```目录放到一起，然后执行下面命令：
+    ```
+    nohup java -jar push-xxxx.jar 2>&1 &
+    ```
+
+### IM-Server 配置
+修改IM服务的配置文件```wildfirechat.conf```，指向推送服务器的地址，修改完后需要重启
+```
+#*********************************************************************
+# Push server configuration
+#*********************************************************************
+##安卓推送服务器地址
+push.android.server.address http://localhost:8085/android/push
+##苹果推送服务器地址
+push.ios.server.address http://localhost:8085/ios/push
+```
+
+### 推送测试
+1. 确保双方都在线时，能互发消息
+2. Android端，为了保证用户能正常收到消息，需要进行一些相关设置，产品上线之后，也需要引导用户进行相关设置，不设置会收到不到推送，具体设置方式不同手机不一样，请参考具体的手机设置，也可以参考[这儿](https://docs.rongcloud.cn/im/push/android/message_notification/)：
+    1. 允许后台运行
+    2. 允许自启动
+    3. 允许后台弹出界面
+    4. 允许显示通知
+3. 将其中一方杀进程，另外一方向其发送文本消息
+4. 查看被杀进程一方，是否收到推送
+
+### 问题排查
+如果遇到问题请按照以下步骤排查：
+1. 请确保上面所有步骤都正确完成之后，再开始问题排查
+2. 确保程序是非启动状态，如果退回到桌面，应用还是激活的还会继续收消息，此时就不会走推送服务。应用在后台激活状态时应该走本地通知。
+3. 确认客户端推送SDK是否正确的获取到token，是否调用了setDeviceToken，token和type是多少？
+4. 确认消息是否是自定义消息，如果是自定义消息，push content是否带上有内容？自定义消息只有push content不为空才会推送。
+5. 确认目标客户端是否7日之内登录过，超过7天是不推送的。
+6. 确认目标客户是否设置了全局静音或会话静音。
+7. 如果有pc和web端登陆，确认是否设定了pc在线时手机静音。
+8. 查看```IM-Server```日志，看是否有推送相关日志输出
+    ```
+    LOG.info("Send push to {}, message from {}", deviceId, sender); // 这是打印日志的代码！！
+    ```
+9. 确认推送服务是否收到了推送信息，如果收到，token和type是否和步骤1一致，推送内容是否和2一致？
+    ```
+    // 对方是 Android
+    LOG.info("Android push {}", new Gson().toJson(pushMessage)); // 这是打印日志的代码
+    // 对方是 iOS
+    LOG.info("iOS push {}", new Gson().toJson(pushMessage)); // 这是打印日志的代码
+    ```
+10. 如果推送内容正确到达推送服务，则后面的排查就跟IM服务完全无关了，是推送厂商推送服务的调试，需要客户自己按照推送厂商的官方文档进行调试。
+
+### 常见问题
+TODO
+
+