概述
本文旨在帮助使用 unipush 1.0 的用户解决集成或使用过程中常遇见的问题，让用户更顺畅地使用unipush，如按照本文介绍的内容排查问题之后仍有异常情况，可登录个推官网进行技术咨询。若您使用的是 uni-push 2.0 请查看： uni-push2.0 常见问题
uni-push1.0 常见问题
使用uniPush是否还需要重新注册个推开发者账号？
- 开发者无需重新注册个推账号，unipush与个推进行了直接打通，包括个推服务端api调用也只需要使用unipush应用内的参数。
云打包/离线打包集成问题
- 云打包教程请参考5+App开发入门指南【发行打包】部分。
- 由于离线打包涉及到Dcloud侧部分原生封装问题，请加DCloud原生开发者QQ交流群： 814228233 咨询解决。
厂商推送设置-->保存参数时提示：验证错误
- 原因是填写了错误的厂商参数，需要去对应的 厂商平台 核实参数是否一致，且注意填写时不能包含空格。
- 如果确认参数完全一致，可以更换浏览器后再进行填写保存，推荐使用 Google 浏览器。
如何获取CID和任务ID
- 在应用安装后第一次运行时应该调用5+ API的plus.push.getClientInfo方法获取客户端标识，如果获取的cid为空，说明客户端向推送服务器注册还未完成，可以使用setTimeout延时重试。
document.addEventListener('plusready', function(){ // 页面加载时触发 plus.push.getClientInfoAsync((info) => { let cid = info["clientid"]; }); }, false ); - 服务端推送的，请求成功后会返回result，result中【taskid】的值就是任务ID；平台上推送的，在【推送记录】中点击详情，页面上显示的【task ID】的值。
推送频次默认相关限制
- to single单推接口，推送没有限制。
- to list列表推接口，一天限制200万次，一次上限200个CID，相同消息体可复用taskid，只算一次次数。
- to app群推接口，一天限制100次，一分钟不能超过5次，10分钟内不能推重复消息体。
服务端推送返回报target user is invalid、appiderror
- 每个APP应用都有各自的一套Appid、Appkey、 AppSecret参数，个推的CID是与各个应用的Appid有对应绑定关系，以此来区分定位到各个手机上的app的。
- Unipush推送出现AppidError或者target user is invalid，一般都是您使用的CID是自定义基座包获取的，不属于您自己应用，属于Dcloud官方的测试app应用。您需要使用自有证书提交云打包后，下载安装再去获取正确的CID进行推送测试。Dcloud侧官方Appid ： pPyZWvH3Fa6PXba10aJ009
Unipush平台上故障排查输入cid查询出现 cid不存在或应用错误
- 每个APP应用都有各自的一套Appid、Appkey、 AppSecret参数，个推的CID是与各个应用的Appid有对应绑定关系，以此来区分定位到各个手机上的app的。
- 检查cid输入是否错误，是否有空格。
- 使用自有证书提交云打包后，下载安装再去获取正确的CID进行推送测试。
别名、标签推送收不到问题
- 个推推送都是通过clientid进行定点推送，clientid是个推业务层中的对外用户标识，用于标识客户端身份，是个推SDK的唯一识别号，简称CID。
- 推送别名、标签前，需要将客户端CID与自定义的别名、标签进行绑定动作，绑定成功后，推送别名和标签才能将消息推送给别名、标签下对应绑定的CID。
- 客户端绑定别名、标签，请在CID回调后，也就是客户端getClientInfo后，去调用绑定别名、标签接口，否则会出现绑定失败的问题。
- 在【Uni Push】-【配置管理】-【别名管理】/【应用标签】可输入别名、CID/标签名，进行查询CID是否与别名和标签绑定成功；若应页面数据延迟问题查无结果，可提供别名、CID/标签名给到个推技术支持进行确认。
- 别名相关限制
- 别名名称：长度40字节，支持中、英文（区分大小写）、数字以及下划线
- 一个CID一天绑定别名和解绑别名次数各有50次机会
- 一个别名下最多绑定10个CID，若超出10个，则绑定后者，剔除第一个已绑定的CID，以此类推；一个CID只能绑定一个别名，若超出则以最后一次绑定的别名为准。
- 标签相关限制
- 标签名称：长度32字节，中文、英文字母（大小写）、数字、除英文逗号以外的其他特殊符号
- 一个CID一天默认绑定只有一次标签绑定次数。
- 一个CID默认可支持100个标签，标签的绑定是全量覆盖的，后面一次的覆盖前面一次的 。
安卓厂商离线推送是否要求上架应用商店？
- 目前华为、荣耀、魅族、oppo（测试环境）不要求上架应用商店；vivo 、小米、oppo（正式环境）必须上架应用商店后才可使用离线厂商推送。
找不到OPPO的mastersecret参数
- OPPO平台的mastersecret参数需要在应用通过推送审核后，使用主账号在oppo推送平台-配置管理-应用配置 页面查看。
离线通知没有声音、震动
- 检查手机通知权限中的响铃和震动状态是否打开，包括通知权限的各个通知渠道里的相关权限，例如华为的【营销通知】默认是没有声音、震动的；
- Ios离线的通知除检查手机系统通知设置样式外，还需检查服务端push_channel里aps中的sound参数是否设置值为default；若设置成com.gexin.ios.silence，则苹果离线不会有声音。
iOS在线推送消息时，app 闪退
一般是客户端抛异常了，需要在客户端的receive回调中判断msg.type是否为空。
华为离线推送消息自动归到【营销通知】
- 这是华为侧的消息控制：华为推送对推送消息分类进行管理，根据消息内容，华为推送将通知分类为服务与通讯、资讯营销两大类别。对应不同消息级别，会有不同的消息呈现样式。具体说明请参考 华为官方消息分类文档
- 个推侧服务端代码设置示例
"options": { "HW": { "/message/android/notification/importance": "NORMAL", } }注意：该设置项不能直接决定消息分类，华为侧还是会通过消息体判断去划分，最终是以华为侧的划分为准。请尽量不要推送测试性消息，同样消息体也不要频繁重复推送
点击消息如何实现页面跳转
在线消息：
如果客户端发的是透传消息，消息到达客户端后会触发 receive 回调。客户端需要调用 createMessage 方法自己创建通知栏消息展示。点击通知栏消息会触发客户端的 click 回调，在回调中自行处理页面的跳转。
离线消息：
android:
- 服务端push_channel.android必须内必须设置安卓跳转页面的参数intent，参数为固定格式：intent://io.dcloud.unipush/?#Intent;scheme=unipush;launchFlags=0x4000000;component=请填您的包名/io.dcloud.PandoraEntry;S.UP-OL-SU=true;S.title=测试标题;S.content=测试内容;S.payload=test;end
- 由于Dcloud封装，使用固定的intent，消息点击默认只支持跳转到应用首页，不支持intent中直接给定Dcloud的插件页面路径。当用户点击通知后，会携带intent的值触发客户端click回调方法， 客户端可根据接收的参数再调用客户端跳转方法实现自定义页面跳转。
ios:
- 服务端push_channel.ios内必须设置ios的自定义参数payload，参数为任意值。
- 当用户点击通知后，会携带payload的值触发客户端receive回调方法， 客户端可根据接收的参数再调用客户端跳转方法实现自定义页面跳转。
客户端跳转app内指定页面的方法：
uni.navigateTo({
//页面路径示例值：/pages/pushinfo/pushinfo
url:'指定页面路径'
}) 点击（click）事件不触发、（receive）事件不触发/监听不到。
- 离线点击不触发click事件，intent中要有dcloud要求的参数格式要求S.UP-OL-SU=true;S.title=测试标题;S.content=测试内容;S.payload=test;否则dcloud识别不到，无法进入对应回调
- 在线透传不触发receive事件，主要是安卓透传内容给了{title:"标题",content:"内容",payload:"自定义数据"}dcloud要求格式的透传内容，dcloud会默认处理展示通知栏通知，并且不会进入receive回调。
平台【预览】返回clientid离线
- 推送时的【预览】功能只支持测试个推在线通道，也就是CID在线的状态下，您输入clientid会进行预览推送测试；若是想测试离线，不需要输入clientid，直接点击【确定】进行推送即可。
【故障排查】-【推送测试】返回error，code:80502
- 【推送测试】功能目前是停止维护的状态，后期会去除该模块，因此目前建议您不要使用该功能，若需要推送测试，可直接在【创建推送】中直接建立推送进行测试。
Dcloud平台厂商参数保存后消失
- 这是正常现象，确保保存成功即可；但参数保存后需要通过提交云打包才能使新保存参数生效到应用中，因此厂商参数保存后，请一定要提交云打包。
自定义铃声是否支持
- 在线推送都支持自定义铃声，离线推送仅 华为、小米、ios 支持 。自定义推送铃声：https://ext.dcloud.net.cn/plugin?id=7482
角标怎么设置
- 调用 5+ API plus.runtime.setBadgeNumber
安卓厂商离线角标支持情况
- oppo/魅族，部分手机系统上能设置角标圆点，没有数字角标的功能。
- 小米系统自带离线通知数字角标展示功能，默认+1处理，打开清零。
- vivo高版本系统自带离线通知数字角标展示功能，默认+1处理，打开清零，低版本没有角标功能。
- 华为角标需服务端api进行字段设置，客户端需要手动设置角标数为0
- add方式支持版本： EMUI版本8.0.0且推送服务应用版本 8.0.0及以上
- 服务端rest-v2设置示例，注意：Unipush用户的class的值请固定使用'io.dcloud.PandoraEntry'
"options": { "HW": { "/message/android/notification/badge/class": "io.dcloud.PandoraEntry", "/message/android/notification/badge/add_num": 1, } }
安卓厂商离线机型版本支持情况
- 华为机型要求：需华为rom且华为rom版本大于等于emui4.1, 华为移动服务(可在应用列表或华为应用市
场中查看)版本大于等于2.5.2 - 小米机型要求：需小米rom且小米服务框架（包名：com.xiaomi.xmsf）版本号⼤于等于105
- 魅族机型要求：需魅族rom版本大于等于5.x
- oppo机型要求：需oppo colorOS rom且版本号大于等于3.1
- vivo机型要求：请参考vivo官网说明
CID什么情况下会变化
- 安卓用户超过三个月未启过 app， iOS用户超过一年未启过 app，之后再启动会重新生成一个CID；
- 如果应用没有获取sd卡权限，卸载重装/清除缓存，CID会变（CID信息会写入sd卡）。
- 个推Appid参数、应用的包名、苹果Bundleid的修改。
- 苹果手机进行了越狱或系统还原。
如何更换App图标
- 在HX编译器中可以设置。
Android常见问题
安卓消息推送流程说明
-
默认情况下：
- 当CID在线(即app在前台打开运行)时，消息通过个推通道下发到客户端，具体到服务端Rest-V2代码中，即push_message中的 notification 或 transmission 内容传递给客户端
- 当CID离线(即app在后台、锁屏、进程关闭)时，有开启对应厂商离线功能的，消息将通过个推侧请求对应厂商侧的服务端，具体到服务端Rest-V2代码中，即push_channel中的android中的 notification 内容传递给厂商，实际的消息是经由厂商服务器下发至客户端；对于没有开启对应厂商功能的，消息将存在个推的离线库中，等待CID在线，再通过个推通道下发到客户端
-
注意：安卓的消息推送，走了厂商通道的消息就不会再通过个推通道推送至客户端，反之亦是如此，即消息只会推送一次
-
服务端有 strategy 字段，可以控制消息走个推通道还是走厂商通道，设置示例参考个推侧说明。
- 1: 表示该消息在用户在线时推送个推通道，用户离线时推送厂商通道;
2: 表示该消息只通过厂商通道策略下发，不考虑用户是否在线;
3: 表示该消息只通过个推通道下发，不考虑用户是否在线；
4: 表示该消息优先从厂商通道下发，若消息内容在厂商通道代发失败后会从个推通道下发。 - 注意：2和4的前提是CID必须要正常绑定着安卓厂商token，Ios则是devicetoken，否则设置该策略会报错
- 1: 表示该消息在用户在线时推送个推通道，用户离线时推送厂商通道;
安卓在线收不到通知
- 手机通知权限是否正常打开，部分安卓8以上的手机通知权限中需要打开【Default】渠道的通知权限。
- 若服务端推送模板用的【Transmission】透传模板或平台上推送用的透传消息，且数据格式是自定义的json格式，需要客户端开发者在客户端【Receive】回调中接收该透传消息自己创建通知。
- 确认推送的CID与测试手机关系是否匹配；测试方式：在Dcloud后台【UniPush】-【配置管理】-【故障排查】-【 检测CID的状态及信息】中输入cid，然后多次关闭和打开app，检测每次app状态变化时，cid状态是否也会变化；若发现不对应，重新获取下客户端cid，以新的cid去进行推送测试。
安卓离线收不到通知
步骤一：确认CID是否绑定厂商token
在【Uni Push】-【配置管理】-【故障排查】-【 检测CID的状态及信息:】中输入CID查询，看是否会返回厂商token（device token）。
若返回了具体厂商token，请按以下中各厂商部分说明排查。若查询CID未返回token，请看下方步骤二
目前各厂商对离线消息有额度限制，例如华为单设备单应用每天只能收到 2 条营销类消息，超过后则当天收不到离线。详见 厂商通道限额&QPS说明 ，如果要提升额度，可以参考限额说明文档，向厂商申请系统、私信消息。
-
华为
- 标题长度限制40个字，内容长度限制1024个字。
- emui10的华为手机，检查手机通知权限设置，将【营销通知】的权限也打开，不要默认静默，静默的话是需要下拉通知栏才能看到。
- 手机通知栏消息是否有存满，清除已存的通知栏消息看下新的消息是否能展示。
- 华为【 资讯营销】，一个设备一天只能收到2条离线消息。
-
荣耀
- 荣耀【 资讯营销】，一个设备一天只能收到2条离线消息。
-
VIVO
- 标题长度限制20个字，内容长度限制50个字。
- 检查通知权限，vivo机型默认关闭
- 1个自然日内相同文案的运营消息给同个设备发，vivo会在客户端做去重处理，导致消息不展示
- vivo要求：通知文案中不能带 “包含测试、test字符”、“纯数字”、“纯表情”、“符号”或者“符号+数
字”、“表情+数字”、“表情＋符号” - vivo需要上架至应用市场才能使用离线厂商推送。
- vivo【 公信消息】，一个设备一天只能收到2条离线消息。
-
小米
- 标题长度限制50个字，内容长度限制128个字。
- 检查手机通知权限设置，小米有不重要通知功能，部分消息可能会存在通知栏不重要通知里
- 服务端推送时，推送代码要加上离线时间设置，不能为空。
- 小米需要上架至应用市场才能使用离线厂商推送。
- 小米【 公信消息】，一个设备一天只能收到5条离线消息。
-
OPPO
- 标题长度限制32个字，内容长度限制200个字。
- 检查手机通知权限是否打开，oppo是默认关闭的，将通知权限下的【Default】通道权限也打开。
- 手机系统时间是否正常
- oppo【 公信消息】，一个设备一天只能收到2条离线消息。
-
魅族
- 标题长度限制32个字，内容长度限制100个字。
- 检查消息是否存入了魅族手机右上角【魅族消息盒子】中。
- 清除缓存：手机【系统设置】-【应用管理】-【所有应用】点击右上角【显示系统服务应用】找到【推送服务】和【您自己的 App】，如下图，分别进行“清除数据”，然后重启手机。
步骤二：查询CID未返回token，调试查询厂商code码
- 对应厂商平台上的推送服务状态是否是开启状态。
-
在Dcloud后台【Uni Push】-【厂商推送设置】中保存好厂商参数，并用自有证书提交云打包，且需要打正式包，再获取cid去查询是否有返回。
厂商错误码调试方法如下：
- 需要先安装调试环境，参考安装教程
- 手机连接电脑，手机需开启开发者调试模式，此时不用打开app
- Windows执行示例：如下图，回车执行后打开app
- Mac执行示例：如下图，回车执行后打开app
- 此时注意查看返回的厂商Code码，如上图中HW的错误码为907135702，点击下方链接搜索查询官方描述。
- 若未返回任何带有厂商标识的日志，说明厂商推送服务还未置于您app应用内，请重新检查厂商服务开通、配置、云打包相关步骤。
华为（包含荣耀）机型需要额外检查：
- 需要在华为开发者后台配置正确的 sha256 指纹证书
- 云打包用自有证书打正式签名包
- 华为开发者后台包名跟客户端包名需要保持一致
- 厂商推送设置-华为厂商，必须上传agconnect-services.json
- 在华为平台是否开通了华为推送服务
- 保存完参数，需要重新提交云端打包
步骤三：服务端推送代码问题
- push_message是个推在线时推送起作用的消息体；push_channel是个推离线时走厂商通道起作用的消息体 安卓厂商要用通知消息notification，ios厂商要用aps 。具体代码设置请参考文章末尾的厂商推送示例。
如何给华为、vivo厂商发送测试消息
华为单应用单设备单日可接收消息数量上限：新闻阅读（新闻，需具备《互联网新闻信息服务许可证》）： 5 条。其它营销类消息：2 条。
其它安卓厂商也有额度限制，详见：厂商通道限额&QPS说明
-
若调用服务端 api 推送，增加options参数：
"options": { "HW": { // 值为int 类型。1 表示华为测试消息，华为每个应用每日可发送该测试消息500条，此target_user_type 参数请勿发布至线上。 "/message/android/target_user_type":1 } , "HO": { //值为int 类型。1 表示测试推送，不填默认为0。荣耀每个应用每日可发送该测试消息1000条。此测试参数请勿发布至线上。 "/android/targetUserType": 1 }, "VV": { //值为int 类型。0 表示正式推送；1 表示测试推送，不填默认为0。线上请勿使用测试推送 "/pushMode":1 } }vivo测试推送，额外需要先在 vivo 开放平台 录入测试用户。华为不需要录入。
-
若从后台页面推送，填写红框附加参数：
”华为“ 、”/message/android/target_user_type”、”数字“ 、”1“（注意 1 是数字不是字符串）
”荣耀“ 、”/android/targetUserType”、”数字“ 、”1“（注意 1 是数字不是字符串）
”vivo“ 、”/pushMode”、”数字“ 、”1“（注意 1 是数字不是字符串）
iOS常见问题
iOS消息推送流程说明
- 当CID在线(即app在前台打开运行)时，消息通过个推通道下发到客户端，具体到服务端Rest-V2代码中，即push_message中的 transmission 透传内容传递给客户端。透传消息需要开发者在客户端receive透传回调中，接收透传消息并根据自身业务场景进行消息的展示方式处理，默认不处理的话是没有任何展示的，透传消息个推只负责传递。
- 当CID离线(即app在后台、锁屏)时，消息将通过个推侧请求对应厂商侧的服务端，具体到服务端Rest-V2代码中，即push_channel中的ios中的内容请求给苹果的服务端，由苹果进行推送。
- 注意：与安卓消息流程不同的是，Ios走了厂商离线通道，在消息有效期内，app打开在前台时，push_message中的 transmission 内容还将通过个推通道传递给客户端； 此时可在客户端透传回调中的参数PushMessage对象中获取aps属性值来判断是否是APNs下发的消息 ，参考推送开发指南
iOS在线收不到消息
- iOS推送，需要使用透传消息（服务端中push_message中使用的 transmission消息）
- 透传消息需要开发者在客户端receive透传回调中，接收透传消息并根据自身业务场景进行消息的展示方式处理，默认不处理的话是没有任何展示的，透传消息个推只负责传递。
- 确认推送的cid与测试手机关系是否匹配；测试方式：在Dcloud后台【UniPush】-【配置管理】-【故障排查】-【 检测CID的状态及信息】中输入cid，然后多次关闭和打开app，检测每次app状态变化时，cid状态是否也会变化；若发现不对应，重新获取下客户端cid，以新的cid去进行推送测试。
iOS离线收不到消息
步骤一：确认CID是否绑定苹果devicetoken
在【Uni Push】-【配置管理】-【故障排查】-【 检测CID的状态及信息:】中输入CID查询，看是否会返回苹果devicetoken。
若返回了具体苹果devicetoken，请按以下说明排查，若还未解决，提供CID和任务ID给个推技术支持
- 返回的devicetoken后面是否带着【developement】字样；若带着，则说明客户端环境是属于苹果的开发环境，苹果推送对开发环境的支持不稳定，建议使用正式环境去进行推送测试。
步骤二：查询CID未返回devicetoken
- 切换手机连接网络，卸载重装试下。
- 使用其他手机安装测试。
- 重新进行云打包。
步骤三：检测平台上传证书
- 在【配置管理】-【应用配置】-【测试一下】输入上述步骤查询出来的苹果devicetoken进行推送测试，看是否手机是否能收到，若报错则需重新导入苹果推送证书。
步骤四：服务端推送代码问题
- push_message是个推在线时推送起作用的消息体；push_channel是个推离线时走厂商通道起作用的消息体 安卓厂商要用通知消息notification，ios厂商要用aps 。具体代码设置请参考文章末尾的厂商推送示例。
证书测试一下返回无效、连接报错
- 证书环境问题：通用证书支持开发与正式环境推送；开发证书只支持开发环境推送。
- iOS证书的生成，请参考证书生成文档。
苹果证书上传后，选开发环境不对，选生产环境也不对；
- 导证书不要把钥匙串也导进来，解决按着证书生成文档重新导出次，单独选择证书；
Ios应用如何让角标badge自动加1
- 服务端推送时push_channeli中ios部分设置角标参数： "auto_badge":"+1"。
-
客户端需要做角标清零动作，原生示例代码如下，Dcloud可去论坛查询，接口方式与原生类似。
//重置角标 [GeTuiSdk resetBadge]; //如果需要角标清空需要调用系统方法设置 [[UIApplication sharedApplication] setApplicationIconBadgeNumber:0];
