# uni-push

uni-push是DCloud与合作伙伴个推共同推出的统一推送服务。用于从服务器端推送消息到客户端。

它包括在线推送、离线推送，聚合了Apple、华为、小米、OPPO、VIVO、魅族、荣耀(3.99+)、Google等多个手机厂商的推送通道。

若不使用服务器推送，仅想创建手机通知栏本地消息，也需要使用本模块的API。

它是一个云端一体的业务，涉及多份文档：

业务介绍：对于未使用过uni-push的新用户，本文必读：uni-push业务介绍
客户端API，即本文
服务器API，另见

# uni.getPushClientId(options)

获取客户端唯一的推送标识

# # Parameters

name	type	required	default	description
options	GetPushClientIdOptions	YES	-	-

# # GetPushClientIdOptions Values

name	type	optinal	default	description
success	(result: GetPushClientIdSuccess) => void	NO	null	接口调用成功的回调函数
fail	(result: UniError) => void	NO	null	接口调用失败的回调函数
complete	(result: any) => void	NO	null	接口调用结束的回调函数（调用成功、失败都会执行）

# # GetPushClientIdSuccess Values

name	type	optinal	default	description
cid	string	YES	-	个推客户端推送id，对应uni-id-device表的push_clientid
errMsg	string	YES	-	错误描述

# # getPushClientId Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4	√	3.98	9.0	x	x

# # See also

getPushClientId

Related Bug

# uni.onPushMessage(callback)

启动监听推送消息事件

# # Parameters

name	type	required	default	description
callback	(result: OnPushMessageCallbackResult) => void	YES	-	-

# # OnPushMessageCallbackResult Values

name	type	optinal	default	description
data	UTSJSONObject	YES	-	-

# # onPushMessage Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4	√	3.98	9.0	x	x

# # See also

onPushMessage

Related Bug

# 注意事项

如果多次监听onPushMessage，那么事件也会多次触发，所以当不需要监听的时候需要offPushMessage。

# uni.offPushMessage(callback)

关闭推送消息监听事件

# # Parameters

name	type	required	default	description
callback	(result: OnPushMessageCallbackResult) => void	YES	-	-

# # OnPushMessageCallbackResult Values

name	type	optinal	default	description
data	UTSJSONObject	YES	-	-

# # offPushMessage Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4	√	3.98	9.0	x	x

# # See also

offPushMessage

Related Bug

# uni.getChannelManager()

获取通知渠道管理器，Android 8系统以上才可以设置通知渠道，Android 8系统以下返回null。

# # Return value

Type
ChannelManager

# # ChannelManager Values

name	type	optinal	default	description
setPushChannel	(options: SetPushChannelOptions) => void	YES	-	设置推送渠道
getAllChannels	() => Array<string>	YES	-	获取当前应用注册的所有的通知渠道。

# # SetPushChannelOptions Values

name	type	optinal	default	description
soundName	string	NO	null	添加的声音文件，注意raw目录下必须要有，不传此字段将使用默认铃音。
channelId	string	YES	-	通知渠道id
channelDesc	string	YES	-	通知渠道描述
enableLights	boolean	NO	false	呼吸灯闪烁
enableVibration	boolean	NO	false	震动
importance	number	NO	3	通知的重要性级别，可选范围IMPORTANCE_LOW：2、IMPORTANCE_DEFAULT：3、IMPORTANCE_HIGH：4 。
lockscreenVisibility	number	NO	-1000	锁屏可见性，可选范围VISIBILITY_PRIVATE：0、VISIBILITY_PUBLIC：1、VISIBILITY_SECRET：-1、VISIBILITY_NO_OVERRIDE：-1000。

# # ChannelManager Compatibility

	Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
setPushChannel	4.4	√	3.98	9.0	x	x
getAllChannels	4.4	√	3.98	9.0	x	x

# # getChannelManager Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4	3.98	3.98	9.0	x	x

# # See also

Related Bug

# 注意事项

由于各大厂商限制推送频次，当使用厂商离线推送的时，需要在不同品牌手机后台开通自分类权益，限制数量说明
- 华为
- oppo
- vivo
开通自分类权益后，需要客户端创建channel，因此客户端提供了setPushChannel来进行channel的创建，通过此Api来创建渠道进行推送。客户端创建渠道成功后，即可通过云函数进行推送，uni-push2服务端文档。
由于Android通知渠道的机制问题，一旦通知渠道建立，便不能修改此渠道的配置，即使删除渠道后再次创建同channelId名称的渠道，也不会改变原先渠道的配置（除非删除应用），最明显的现象就是铃声动态修改失败，比如调用setPushChannel时，第一次的设置参数是{"channelId":"test","soundName":"pushsound"} , 这时你想切换铃音，你的channelId就不能再叫test了，而应该为{"channelId":"test2","soundName":"ring"} ，此时会新建一个渠道。

# uni.createPushMessage(options)

创建本地通知栏消息

# # Parameters

name	type	required	default	description
options	CreatePushMessageOptions	YES	-	-

# # CreatePushMessageOptions Values

name	type	optinal	default	description
cover	boolean	NO	false	是否覆盖上一次提示的消息
delay	number	NO	0	提示消息延迟显示的时间,单位为s
icon	string	NO	null	推送消息的图标
sound	string	NO	"system"	推送消息的提示音 - system: 使用系统通知提示音（默认值） - none: 不使用提示音
title	string	NO	""	推送消息的标题
content	string	YES	-	消息显示的内容，在系统通知中心中显示的文本内容
payload	any	NO	null	消息承载的数据，可根据业务逻辑自定义数据格式
when	number	NO	当前时间	消息上显示的提示时间
channelId	string	NO	"DcloudChannelID"	渠道id
category	string	NO	null	通知类别
success	(result: CreatePushMessageSuccess) => void	NO	null	接口调用成功的回调函数
fail	(result: UniError) => void	NO	null	接口调用失败的回调函数
complete	(result: any) => void	NO	null	接口调用结束的回调函数（调用成功、失败都会执行）

# # CreatePushMessageOptions Compatibility

	Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
channelId	4.4	√	3.98	9.0	x	x
category	4.4	√	3.98	9.0	x	x

# # createPushMessage Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4	√	3.98	9.0	x	x

# # See also

createPushMessage

Related Bug

# # General type

# # GeneralCallbackResult

name	type	optinal	default	description
errMsg	string	YES	-	错误信息

# 示例代码

hello uni-push是可跑通、同时包含客户端和服务器完整流程的代码。https://gitcode.net/dcloud/hello-uni-push

在业务开通、配置正确的情况下，执行项目下的云函数，即可给客户端发送消息。

# 注意事项

关于隐私安全问题，由于在调用getPushClientId或者onPushMessage时，才会初始化个推SDK，所以开发者要确保弹出隐私框之前不调用此两项API。

关于图标的配置，需要创建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"
  })
```
uni-app x 的push模块仅支持uni-push2，不再支持uni-push1。但这不意味着强绑uniCloud的付费行为。而是DCloud的所有云服务都将统一纳入到uniCloud体系管理，开发者在开通uni-push2后，也可以拿到mastersecret，然后在自己的服务器去直接连接个推服务器。
uni-push是一个独立的模块，在标准基座中并不包含。开发push需要首先编写push相关代码，然后打包自定义基座，根据摇树规则，打出的自定义基座才会包含push模块。详见摇树
创建本地通知栏，理论上可以和个推的服务无关。但目前也都包含在push模块里了。如果您不需要服务器推送，只需要本地创建通知栏，也需要打包push模块才行。
部分手机创建本地通知时，App如果在后台状态，点击通知消息并不会拉起App，原因是厂商增加了后台弹窗权限，需要用户手动打开此权限。
获取手机端app是否拥有push权限，请使用API uni.getAppAuthorizeSetting

products

HBuilderX uni-app uniCloud uniMPsdk 5+Runtime uni-id uni-search uniPay uniPush uni-verify sms uni-starter uni-admin uni-upgrade-center uni-im uni-ai uni-cms

Operating services

uni-AD uni-stat uni-portal Safety topic

Developer Services

forum dashboard

Docs

uni-app uniCloud native-support HBuilderX

Ecosystem

Marketplace OAuth

About： DCloud Jobs Terms of service Privacy policy acceptable use policy

# uni-push

# uni.getPushClientId(options)

# # Parameters

# # GetPushClientIdOptions Values

# # GetPushClientIdSuccess Values

# # getPushClientId Compatibility

# # See also

# uni.onPushMessage(callback)

# # Parameters

# # OnPushMessageCallbackResult Values

# # onPushMessage Compatibility

# # See also

# 注意事项

# uni.offPushMessage(callback)

# # Parameters

# # OnPushMessageCallbackResult Values

# # offPushMessage Compatibility

# # See also

# uni.getChannelManager()

# # Return value

# # ChannelManager Values

# # SetPushChannelOptions Values

# # ChannelManager Compatibility

# # getChannelManager Compatibility

# # See also

# 注意事项

# uni.createPushMessage(options)

# # Parameters

# # CreatePushMessageOptions Values

# # CreatePushMessageOptions Compatibility

# # createPushMessage Compatibility

# # See also

# # General type

# # GeneralCallbackResult

# 示例代码

# 注意事项

On This Page