简体中文
简体中文
# uni-push
uni-push是DCloud与合作伙伴个推共同推出的统一推送服务。用于从服务器端推送消息到客户端。
它包括在线推送、离线推送，聚合了Apple、华为、小米、OPPO、VIVO、魅族、荣耀(3.99+)、Google等多个手机厂商的推送通道。
若不使用服务器推送，仅想创建手机通知栏本地消息，也需要使用本模块的API。
它是一个云端一体的业务，涉及多份文档：
- 业务介绍：对于未使用过uni-push的新用户，本文必读：uni-push业务介绍
- 客户端API，即本文
- 服务器API，另见
# uni.getPushClientId(options)
获取客户端唯一的推送标识
# 参数
| 名称 | 类型 | 必填 | 默认值 | 描述 | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| options | GetPushClientIdOptions | 是 | - | |||||||||||||||||||||
| ||||||||||||||||||||||||
# GetPushClientIdSuccess 的属性值
| 名称 | 类型 | 必备 | 默认值 | 描述 |
|---|---|---|---|---|
| cid | string | 是 | - | 个推客户端推送id，对应uni-id-device表的push_clientid |
| errMsg | string | 是 | - | 错误描述 |
# getPushClientId 兼容性
| Android | iOS | web |
|---|---|---|
| 3.98 | x | - |
# 参见
# uni.onPushMessage(callback)
启动监听推送消息事件
# 参数
| 名称 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| callback | (result: OnPushMessageCallbackResult) => void | 是 | - |
# OnPushMessageCallbackResult 的属性值
| 名称 | 类型 | 必备 | 默认值 | 描述 |
|---|---|---|---|---|
| type | "click" | "receive" | 是 | - | 事件类型 - click 从系统推送服务点击消息启动应用事件 - receive 应用从推送服务器接收到推送消息事件 |
| data | UTSJSONObject | 是 | - | 消息内容 |
# onPushMessage 兼容性
| Android | iOS | web |
|---|---|---|
| 3.98 | x | - |
# 参见
# 注意事项
- 如果多次监听
onPushMessage，那么事件也会多次触发，所以当不需要监听的时候需要offPushMessage。
# uni.offPushMessage(callback)
关闭推送消息监听事件
# 参数
| 名称 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| callback | (result: OnPushMessageCallbackResult) => void | 是 | - |
# OnPushMessageCallbackResult 的属性值
| 名称 | 类型 | 必备 | 默认值 | 描述 |
|---|---|---|---|---|
| type | "click" | "receive" | 是 | - | 事件类型 - click 从系统推送服务点击消息启动应用事件 - receive 应用从推送服务器接收到推送消息事件 |
| data | UTSJSONObject | 是 | - | 消息内容 |
# offPushMessage 兼容性
| Android | iOS | web |
|---|---|---|
| 3.98 | x | - |
# 参见
# uni.getChannelManager()
获取通知渠道管理器，Android 8系统以上才可以设置通知渠道，Android 8系统以下返回null。
# 返回值
| 类型 |
|---|
| ChannelManager |
# ChannelManager 的方法
# setPushChannel(options)
设置推送渠道
# 参数
| 名称 | 类型 | 必填 | 默认值 | 描述 | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| options | SetPushChannelOptions | 是 | - | - | ||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||
# setPushChannel 兼容性
| Android | iOS | web |
|---|---|---|
| 3.98 | x | - |
# getAllChannels()
获取当前应用注册的所有的通知渠道。
# 返回值
| 类型 |
|---|
| Array<string> |
# getAllChannels 兼容性
| Android | iOS | web |
|---|---|---|
| 3.98 | x | - |
# getChannelManager 兼容性
| Android | iOS | web |
|---|---|---|
| 3.98 | x | - |
# 参见
# 注意事项
由于各大厂商限制推送频次，当使用厂商离线推送的时，需要在不同品牌手机后台开通自分类权益，限制数量说明
开通自分类权益后，需要客户端创建channel，因此客户端提供了
setPushChannel来进行channel的创建，通过此Api来创建渠道进行推送。 客户端创建渠道成功后，即可通过云函数进行推送，uni-push2服务端文档。由于Android通知渠道的机制问题，一旦通知渠道建立，便不能修改此渠道的配置，即使删除渠道后再次创建同channelId名称的渠道，也不会改变原先渠道的配置（除非删除应用），最明显的现象就是铃声动态修改失败，比如调用
setPushChannel时，第一次的设置参数是{"channelId":"test","soundName":"pushsound"}, 这时你想切换铃音，你的channelId就不能再叫test了，而应该为{"channelId":"test2","soundName":"ring"}，此时会新建一个渠道。
# uni.createPushMessage(options)
创建本地通知栏消息
# 参数
| 名称 | 类型 | 必填 | 默认值 | 描述 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| options | CreatePushMessageOptions | 是 | - | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
# CreatePushMessageOptions 兼容性
| Android | iOS | web | |
|---|---|---|---|
| channelId | 3.98 | x | - |
| category | 3.98 | x | - |
# createPushMessage 兼容性
| Android | iOS | web |
|---|---|---|
| 3.98 | x | - |
# 参见
# 通用类型
# GeneralCallbackResult
| 名称 | 类型 | 必备 | 默认值 | 描述 |
|---|---|---|---|---|
| errMsg | string | 是 | - | 错误信息 |
# 示例代码
hello uni-push是可跑通、同时包含客户端和服务器完整流程的代码。https://gitcode.net/dcloud/hello-uni-push
在业务开通、配置正确的情况下，执行项目下的云函数，即可给客户端发送消息。
# 高级场景用途
在nativeResources目录可以配置图片和声音的二进制文件资源。
# 通知栏显示图标自定义
关于图标的配置，需要创建nativeResources目录， 放置对应分辨率的图片资源即可（打包后生效），目录配置如下
├── nativeResources
│ └── android
│ └── res
│ ├── drawable-ldpi
│ │ ├── push.png // 分辨率要求48x48
│ │ └── push_small.png // 分辨率要求18x18
│ ├── drawable-mdpi
│ │ ├── push.png // 分辨率要求64x64
│ │ └── push_small.png // 分辨率要求24x24
│ ├── drawable-hdpi
│ │ ├── push.png // 分辨率要求96x96
│ │ └── push_small.png // 分辨率要求36x36
│ ├── drawable-xhdpi
│ │ ├── push.png // 分辨率要求128x128
│ │ └── push_small.png // 分辨率要求48x48
│ ├── drawable-xxhdpi
│ │ ├── push.png // 分辨率要求192x192
│ │ └── push_small.png // 分辨率要求72x72
│ ├── drawable-xxxhdpi
│ │ └── push_small.png // 分辨率要求96x96
│ └── raw
│ └── pushsound.mp3 // 声音文件， 自定义推送铃音时使用
# 通知声音自定义
有些场景，如到账提醒，需要自定义通知声音。
setPushChannel设置新建渠道时，soundName字段的值为目录nativeResources->android->res->raw中存放的音频文件名称，（打包后生效）
注意不要带文件的后缀，比如pushsound.mp3文件，例：
const channelManager = getChannelManager()
channelManager.setPushChannel({
channelId: "test1",
channelDesc: "test1 desc",
soundName: "pushsound"
})
# 在通知栏显示App下载进度
很多Android应用升级下载apk时会在通知栏显示下载进度。
该功能已经内置到uni升级中心中，此开源模板可直接使用。
# 在通知栏显示音乐播放条
需要使用uts插件，见插件市场
# 注意事项
- 关于隐私安全问题，由于在调用
getPushClientId或者onPushMessage时，才会初始化个推SDK，所以开发者要确保弹出隐私框之前不调用此两项API。 - 获取手机端app是否拥有push权限，请使用API uni.getAppAuthorizeSetting
- uni-app x 的push模块仅支持uni-push2，不再支持uni-push1。但不要误会这不是强绑uniCloud的付费行为。而是DCloud的所有云服务都将统一纳入到uniCloud体系管理，开发者在开通uni-push2后，也可以拿到mastersecret，然后在自己的服务器去直接连接个推服务器。另外uniCloud的免费版也足够很多开发者使用。
- uni-push是一个独立的模块，在标准基座中并不包含。开发push需要首先编写push相关代码，然后打包自定义基座，根据摇树规则，打出的自定义基座才会包含push模块。详见摇树
- 创建本地通知栏，理论上可以和个推的服务无关。但目前也都包含在push模块里了。如果您不需要服务器推送，只需要本地创建通知栏，也需要打包push模块才行。
- 部分手机创建本地通知时，App如果在后台状态，点击通知消息并不会拉起App，原因是厂商增加了后台弹窗权限，需要用户手动打开此权限。
