Requires HBuilderX 3.5.1 and above to support

为了更好的服务欢迎： 加入uni-push2.0 交流群

uni-push has a server API and a client API.

Client API Details reference

Server API

The following is the api documentation of the uni-cloud-push extension library; a detailed introduction to the uni-cloud-push extension library, and how to manually configure the uni-cloud-push extension library in the cloud functions that need to operate uni-push [For details, refer to ](https://uniapp.dcloud.io/unipush-v2.html#%E7%AC%AC%E5%9B%9B%E6%AD%A5-%E6%9C%8D%E5%8A%A1% E7%AB%AF%E6%8E%A8%E9%80%81%E6%B6%88%E6%81%AF)

Push message

Push target selection

Sending a push can select the target device based on the following dimensions:

• not specified, all devices that have launched the app
• user_id, the specified user id, based on the uni-id account system
• user_tag, specifies the user tag, based on the uni-id account system
• device_id, the specified device id, the device device based on the opendb table (applications without uni statistics can be used after logging in based on uni-id-co)
• push_clientid, a push client id (also stored in the opendb table).
• getui_alias, a push custom client alias.
• getui_custom_tag，由用户自定义的个推客户端标签。该功能需要申请相关套餐，请点击右侧“技术咨询”了解详情
• getui_big_data_tag，个推大数据标签。

Note: user_id, user_tag, device_id, push_clientid, getui_custom_tag, getui_big_data_tag, getui_alias cannot be selected more than one. All empty means push to all devices that have launched the app.

If the user is not logged in, you can push messages to the user based on device_id, but the bottom layer of the push server only recognizes push_clientid, you need to check the database to get push_clientid. The mapping relationship between device_id and push_clientid is not provided by uni-push, but by the built-in function of the uni statistics module . If you don't use uni statistics, you need to call getPushClientId to get push_clientid when the app is started, after successful acquisition (the app will fail if uni-push2.0 is not enabled in the manifest) Call a method of the cloud object on the server side (parameter: push_clientid) to write or update the opendb-device table (if it exists): [device information](https://uniapp.dcloud.io/uniCloud/ cloud-obj.html#get-client-info) and push_clientid.

同理基于user_id向用户推送消息，需要user_id与push_clientid的映射关系，可以直接使用uni-id-pages插件内置的功能实现。如果你不使用uni-id-pages需要在App.vue调用uniCloud.onRefreshToken 监听token发生变化（即：用户登录和token续期时），调用服务端云对象的某个方法（参数：push_clientid）操作uni-id-device表，记录device_id 与 user_id（防客户端伪造，需校验token）的映射关系；完整字段包含user_id、device_id、token_expired、push_clientid、appid。同时再向opendb-device表写入或更新（存在时）：设备信息和push_clientid。

Note: In theory, the information reported by the client may be tampered with. Pushing messages to users based on device_id has the risk of being eavesdropped (marketing messages don’t need to be too concerned about this). For example: Zhang San uses Li Si's device_id + Zhang San's push_clientid. Report data; the server will think that Li Si's push_clientid has been updated, so that the mapping relationship between Li Si's device_id and push_clientid points to Zhang San's push_clientid; Zhang San then eavesdropped on it, and others sent it to Li Four news. The push message based on user_id or user_tag is based on the uni-id-device table. When adding/updating operations: the user_id of the current user will be verified and will not be tampered by other users, that is, no Risk of being eavesdropped on by others.

Interface form

You can push messages to the set (single, group, all) devices instantly or periodically. Support settings: notification bar message content, control ringtone, vibration, floating, flashing light; corner icon in the upper right corner of the mobile desktop application, etc.

await uniPush.sendMessage(OBJECT)

Input parameters

Name	Type	Required	Default	Description	Platform Features
user_id	String, Array	No	None	Uni-id-based _id, specifying the user id to receive the message. Supports multiple user IDs specified in the form of an array, such as ["user_id-1","user_id-2"], the length of the array is not more than 500
user_tag	String, Array	No	None	Specifies the user tag for receiving messages, based on the uni-id account system. Multiple tags are supported in the form of arrays, such as ["user_tag-1","user_tag-2"], the length of the array is not more than 500
device_id	String, Array	No	None	Specify the device id that receives the message, the device device based on the opendb table (the application developed based on uni statistics or based on uni-id-pages must be logged in based on uni-id-co) available)
push_clientid	String, Array	No	None	Based on the client push ID obtained by uni.getPushClientId, specify the device that receives the message. Multiple devices are supported in the form of arrays, such as ["cid-1","cid-2"], the length of the array is not greater than 1000
getui_custom_tag	String	No	None	Based on individual push getui_custom_tag, specify the device to receive messages; Note: This function needs to apply for relevant packages, please click "Technical Consultation" on the right for details.
getui_big_data_tag	Object Array	No	None	A group push message will be sent to the devices that meet the filtering conditions of the specified application. Support timing, fixed speed function. See below getui-big-data-tag description
getui_alias	String, Array	No	None	A push custom client alias, specifying the message recipient. Multiple devices are supported in the form of an array, such as ["getui_alias-1","getui_alias-2"], the length of the array is not more than 1000
platform	String, Array	No	"ALL"	Specifies the platform to receive the message, "ALL" means all platforms. Enumerate supported platforms with an array, such as: ["web","app-ios","app-android","mp-weixin"], see the following [platform description](#platform- %E8%AF%B4%E6%98%8E) Only valid when the recipient of the message is specified by user_id, user_tag
check_token	Boolean	No	true	Check whether the client login status is valid (including token expiration) It is only valid when the message recipient is specified by user_id, user_tag
title	String	Yes	None	Title of notification bar, length less than 20	APP
content	String	Yes	None	Notification bar content, the length is less than 50	APP
payload	String, Object	Yes	None	Push transparently transmitted data, the data accepted by the app program, the length is less than 800 characters; Note: In order to ensure the offline manufacturer channel, the value of the payload can be obtained, please use the Object format such as :{"text":"xxx"}
force_notification	Boolean	No	false	Whether offline push or online push, self-create notification bar message. Client support for HBuilderX 3.5.2 and above	App
badge	Number, String	No	+1	Set the number in the upper right corner of the application to remind the user of the number of unread messages, and support + and - operations on the original number; For example: badge=+1, which means Current badge +1; badge=-1, (only supported by iOS) means current badge -1 (bad>=0); badge=1, (only iOS and Huawei EMUI version 10.0 .0+ support) means that the current angle is set to 1.	ios, android-Huawei
channel	Object	No	None	Message channel settings, to avoid limited push, silent push (mute and need to pull down the system notification bar to see the notification content), you need to send an email to each company to apply, the details below [channel description](# channel) This function depends on the uni native plugin click here to open to take effect after packaging.	android
request_id	String	No	None	The request unique identification number, between 10 and 32 digits; if the request_id is repeated, the message will be lost
group_name	String	No	None	Task group name. Multiple message tasks can use the same task group name, and then you can query the push status according to the task group name (the length is limited to 100 characters, and cannot contain special symbols); Only specify the message recipient based on user_id, push_clientid, and getui_custom_tag, Or effective when group push messages are sent to all users of the app.
sound	String	No	None	Message reminder ringtone setting, the common offline voice broadcast function is realized by it. Android needs to set the channel to take effect. For details, see below Notes on ringtone settings If the ringtone file is not found, the ringtone will be the system default ringtone. The ringtone file needs to be packaged with the uni native plugin click here to open. It is recommended to use consistent file names for iOS and Android ringtones. Fill in the file name directly without extension; for example: pushsound.caf or pushsound.mp3, just fill in pushsound directly.
content_available	Number	No	0	0 means normal notification message (default is 0); 1 means silent push (no notification bar message), no other parameters need to be filled in silent push. Apple officially recommends pushing up to 3 silent messages per hour	ios
open_url	string	No	None	Fill in this value will: force the push type to be "Notification bar message", the system browser will open this link after clicking. A valid and accessible link starting with http(s)://, Huawei channel must use https. length less than 300	android
settings	Object	No	None	Push condition settings, please refer to the settings description below for a detailed explanation
options	Object	No	None	Other configuration, more about options

Frequency Limiting Instructions:

• Multiple clients receive message push API, the frequency is limited to 2 million times/day, please click "Technical Consultation" on the right for details.
• Through getui_big_data_tag (to filter device pushes according to conditions), specify the push API for message recipients. The frequency is limited to 100 times per day, and cannot exceed 5 times per minute (the push limit and the interface execution group push sharing limit). The regular push function needs to be activated after application. Please click "Technical Consultation" on the right for details.
• Group push message API to all users of the specified application, the frequency is limited to 100 times per day, and cannot exceed 5 times per minute (the push limit and the interface filter the user push sharing limit according to the conditions)

Notice:

• Call sendMessage once, the maximum number of push devices is 500, and it will be ignored directly. In the application scenario where more than 500 devices receive messages, the cloud built-in uni-push-admin plugin should be called The object uni-push-co, the calling parameters are consistent with this api
• push_clientid will be invalid if it has not been logged in for 3 months, so the expiration time of the uni-id token cannot exceed 3 months, otherwise the push module will have unexpected failures.

getui_big_data_tag Description

Name	Type	Required	Default	Description
key	String	Yes	None	Query conditions (phone_type mobile phone type; region province and city; custom_tag client label; portrait, personal push user portrait use code, [click to download the file portrait.data](https://docs.getui .com/files/portrait.data).
values	String Array	Yes	none	a list of query criteria values, where Mobile phone model uses the following parameters android and ios; Province and city use number, click to download the file region_code.data;
opt_type	String	Yes	none

• The intersection between different keys, the same key is operated according to opt_type
• eg. It needs to be sent to the city in A, B, C, the tagtest tag is not set, and the mobile phone model is android. && phonetype(android)

platform description

value	explanation
app-ios	iOS App
app-android	Android App
web	Webpage
mp-weixin	WeChat Mini Program
mp-alipay	Alipay Mini Program
mp-baidu	百度小程序
mp-toutiao	抖音小程序
mp-lark	Feishu Mini Program
mp-qq	QQ Mini Program
mp-kuaishou	Kaishou Mini Program
mp-jd	JD Mini Program
mp-360	360 applet
quickapp-webview	Quick App Universal (including Alliance, Huawei)
quickapp-webview-union	Quick App Union
quickapp-webview-huawei	Quick App Huawei

settings description

Name	Type	Required	Default	Description
ttl	Number	否	1小时	消息离线时间设置，单位毫秒，-1表示不设离线，-1 ～ 3 * 24 * 3600 * 1000(3天)之间
strategy	Object	否	{"default":1}	厂商通道策略，详细内容见strategy
speed	Number	否	0	定速推送，例如100，个推控制下发速度在100条/秒左右，0表示不限速
schedule_time	Number	否	无	设置定时推送时间（仅向所有启动过应用的设备群发时有效），必须是7天内的时间，格式：毫秒时间戳，此功能需要单独申请开通，如需开通请点击右侧“技术咨询”了解详情

strategy 厂商下发策略选择

注意此功能需要单独申请开通，若有需要，请点击右侧“技术咨询”了解详情

Name	Type	Required	Default	Description
default	Number	No	1	Default policy selection for all channels 1-4 1: Indicates that the message is pushed to a push channel when the device is online, and the manufacturer channel is pushed when the device is offline; 2: Indicates that the message is only sent through the vendor channel policy, regardless of whether the device is online or not; 3: Indicates that the message is only sent through a push channel, regardless of whether the device is online or not; 4: Indicates that the message is preferentially sent from the manufacturer channel. If the message content fails to be sent on behalf of the manufacturer channel, it will be sent from a push channel. The names can be filled in: ios, st, hw, xm, vv, mz, op. If you have any questions, please click "Technical Consultation" on the right for details.
ios	Number	No	None	ios channel policy 1-4, the meaning is the same as above, to push the ios channel, you need to upload the ios certificate in the individual push developer center, it is recommended to fill in 2 or 4, otherwise there may be messages that will not be displayed Question
st	Number	No	None	Channel policy 1-4, the meaning is the same as above, it is necessary to enable the st manufacturer to use this channel to push messages
...	Number	No	None	Channel strategy 1-4, meaning the same as above

channel description

Note: This function depends on the uni native plugin click here to open to take effect after packaging.

Name	Type	Required	Default	Description
HW	string	No	None	When the value is "LOW", it indicates that the message is information marketing; when the value is "NORMAL", it indicates that the message is service and communication. You need to send an email to Huawei to apply for permission, see Huawei Message Classification Application.
XM	string	No	None	The message channels of Xiaomi Push are divided into two categories: "Normal Message" (default) and "Important Message", and common messages are delivered by default. The number of ordinary messages that can be pushed in a single day is limited, and there is no limit to important messages. For details of important news application, please refer to: Xiaomi push news classification new rules
OP	string	No	None	Need to contact customer service to activate; all channels on the OPush platform are divided into two categories: "public letter" (default) and "private letter", and public letter messages are issued by default. There is a limit to the number of official messages that can be pushed in a single day, and there is no limit to private messages (only for a single user). For private message application, please refer to (OPPO official document) Push private message channel application.
VV	Number	No	No	0 stands for operation news, 1 stands for system news; vivo message classification function divides push message types into operation news and system news, and delivers operation news by default. The maximum number of operational messages received by a single user and single application in a single day is 5, and there is no limit to system messages. There is no need to apply for the system message function, and it can be used directly. If you need to increase the level of system message in special cases, please refer to (vivo official document) [Description of push message classification function](https://dev.vivo.com.cn/documentCenter/ doc/359).

例如：

"channel":{
	"XM":"xxx",
	"HW":"NORMAL",
	"OP":"xxx",
	"VV":1
}

Ringtone Settings Note

1. Huawei channel must apply for self-classification rights
2. Xiaomi channel needs: apply for important level message Channel - apply for other personalized important level message channel, and set custom ringtone front-end path format: android.resource://your APP application package name/raw/ringtone file name, for example: android.resource://io.dcloud.UniPush2/raw/pushsound (the path does not need to have an audio suffix) as shown in the figure

Response body description

Example of multiple alias push return values:

{
    "errMsg":"success",
    "errCode":0,
    "data":{
        "$taskid":{
            "$alias1":{
                "$cid1":"$status",
                "$cid2":"$status"
            },
            "$alias2":{
                "$cid3":"$status",
                "$cid4":"$status"
            }
        }
    }
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

Name	Type	Description
$taskid	Object	task number
$alias	String	Device alias
$cid	String	A push client id
$status	Object	Push results successful_offline: Offline delivery (including vendor channel delivery), successful_online: delivered online, successed_ignore: Inactive devices in the last 90 days will not be delivered

Example of group return value:

{
	"errCode": 0,
	"errMsg": "",
	"data": {
		"$taskid": "RASA_123_12469008ac33dd02815014631c00000f"
	}
}

Examples of other push return values:

{
	"errCode": 0,
	"errMsg": "",
	"data": {
		"$taskid": {
			"$cid":"$status"
		}
	}
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

Name	Type	Description
$taskid	Object	task number
$cid	String	A push client id
$status	Object	Push results successful_offline: Offline delivery (including vendor channel delivery), successful_online: delivered online, successed_ignore: Inactive devices in the last 90 days will not be delivered

Message task

stop task

Stop sending messages that are being pushed or not received (only batch push and group push tasks are supported)

Interface form

await uniPush.stopTaskByTaskid(taskId)

Input parameters

name	type	required	default value	description
taskId	String	yes	none	task id (format RASL-MMdd_XXXXXX or RASA-MMdd_XXXXXX)

Response body description

 {
    "errCode":0, 
    "errMsg":"success"
}

For the description of the return structure, please refer to Public Return Structure

Query scheduled tasks

This interface supports checking the status of the scheduled task after the scheduled task is pushed, and whether the scheduled task is sent successfully.

Interface form

await uniPush.getTaskScheduleByTaskid(taskId)

Input parameters

name	type	required	default value	description
taskId	String	yes	none	task id

Response body description

• return value example

 {
    "errCode":0,
    "errMsg":"success",
    "data": {
        "$taskid": {
            "create_time":"",
            "status":"success",
            "transmission_content":"",
            "push_time":""
        }
    }
}

• Return parameter data description

Name	Type	Description
$taskid	Object	key: task number, value: task data
create_time	String	Time to create a scheduled task, timestamp in milliseconds
status	String	Scheduled task status: success/failed
transmission_content	String	Transmission content
push_time	String	Scheduled task push time, timestamp in milliseconds

Delete scheduled tasks

It is used to delete tasks that have not yet been issued. After deletion, the scheduled task will no longer be triggered.

Interface form

await uniPush.deleteTaskScheduleByTaskid(taskId)

Input parameters

name	type	required	default value	description
taskId	String	yes	none	task id

Response body description

• return value example

 {
    "errCode":0,
    "errMsg":"success"
}

For the description of the return structure, please refer to Public Return Structure

Query message details

Call this interface to query the specific real-time push path of a cid under a task

You need to apply for permission to use this interface. If necessary, please click "Technical Consultation" on the right for details

Interface form

await uniPush.getTaskDetail(OBJECT)

Input parameters

Name	Type	Required	Default	Description
taskId	string	true	none	taskid
cid	string	true	none	cid

Response body description

• return value example

{
    "errCode":0,
    "errMsg":"success",
    "data":{
        "deatil":[
            {
                "time":"yyyy-MM-dd HH:mm:ss",
                "event":"消息请求成功"
            },
            {
                "time":"yyyy-MM-dd HH:mm:ss",
                "event":"到达客户端"
            }
        ]
    }
}

• Return parameter data description

Name	Type	Description
detail	array	Request returns detailed data
time	String	Time, format: yyyy-MM-dd HH:mm:ss
event	String	Event

device alias

Developers can set aliases and labels for the device, and push directly according to the aliases and labels when pushing, which is convenient for device management. An alias is an identifier set by developers for each device according to their own needs. It is recommended to set different aliases for different devices to ensure that a specific device can be uniquely identified through the alias.

Example: You can set the user's mailbox, nickname, mobile phone number, etc. as an alias, and you can specify the target device to send pushes through the mailbox, nickname, and mobile phone number.

A cid can only be bound to one alias. If a cid that has been bound to an alias is bound to a new alias again, the previous alias will be automatically unbound and a new alias will be bound.

bind alias

A cid can only be bound to one alias. If a cid that has been bound to an alias is bound to a new alias again, the previous alias will be automatically unbound and the new alias will be bound.

Interface form

await uniPush.cidBindAlias(OBJECT)

Input parameters

• parameter example

[
	{
		"cid":"",
		"alias":""
	},
	{
		"cid":"",
		"alias":""
	}
]

• Request parameter description Data list, the length of the array is not more than 1000

name	type	required	default value	description
cid	String	Yes	None	cid, DeviceID
alias	String	Yes	no	alias, valid aliases consist of: Letters (case sensitive), numbers, underscores, Chinese characters; length<40; An alias is allowed to bind up to 10 cids.

Response body description

• return value example

{
    "errCode": 0,
    "errMsg": "success"
}

For the description of the return structure, please refer to Public Return Structure

Query aliases based on cid

Query the corresponding alias information through the incoming cid

Interface form

await uniPush.getAliasByCid(cid)

Input parameters

name	type	required	default value	description
cid	String	Yes	None	Unique Device ID

Response body description

• return value example

{
    "errCode": 0,
    "errMsg": "success",
    "data": {
        "alias": "xxx"
    }
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

Name	Type	Description
alias	String	alias

Query cid by alias

Query the corresponding cid information through the incoming alias

Interface form

await uniPush.getCidByAlias(alias)

Input parameters

name	type	required	default value	description
alias	String	yes	none	alias

Response body description

{
    "errCode": 0,
    "errMsg": "success",
    "data": {
        "cid": ["xxx","xxx"]
    }
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

Name	Type	Description
cid	String	Client ID

Batch unbind aliases

Batch release the relationship between aliases and cid

Interface form

await uniPush.unboundAlias(Array)

Input parameters

• parameter example

	[
        {
            "cid":"",
            "alias":""
        },
        {
            "cid":"",
            "alias":""
        }
    ]

• Request parameter description

name	type	required	default value	description
cid	String	Yes	None	Client ID
alias	String	Yes	None	Alias

Response body description

• return value example

{
    "errCode": 0,
    "errMsg": "success"
}

For the description of the return structure, please refer to Public Return Structure

Unbind all aliases

Unbind all cids bound to the alias

Interface form

await uniPush.unboundAllAlias(alias)

Input parameters

name	type	required	default value	description
alias	String	yes	none	device alias

Response body description

• return value example

{
    "errCode": 0,
    "errMsg": "success"
}

For the description of the return structure, please refer to Public Return Structure

Client Tags

Developers can set aliases and labels for the device, and push directly according to the aliases and labels when pushing, which is convenient for device management. The label is an attribute of the device, and each device (identified by CID) can be marked with 100 labels. Example: "Love football", "Love anime"

One device binds a batch of tags

A device is bound to a batch of tags. This operation is an overwrite operation, which will delete the historically bound tags;

This interface has a frequency control limit for a single cid, which can only be modified once a day, and a maximum of 100 labels can be set; the maximum length of a single label is 32 characters, and the maximum total length of the label is 512 characters. To apply for modification, please click "Technical Consultation" on the right Learn more.

Interface form

await uniPush.cidBindCustomTags(OBJECT)

Input parameters

• parameter example

{
	"cid":"xxx",
    "custom_tag": [
        "tag1",
        "tag2"
    ]
}

• Request parameter description

name	type	required	default value	description
cid	String	Yes	None	Device ID
custom_tag	String Array	Yes	None	List of tags, tags cannot contain spaces

Response body description

• return value example

{
    "errCode": 0,
    "errMsg": "success"
}

For the description of the return structure, please refer to Public Return Structure

A batch of devices is bound to a tag

A batch of devices is bound to a label, this interface is incremental

This interface has frequency control (up to 100 times per minute, up to 10,000 times per day). To apply for modification, please click "Technical Consultation" on the right for details

Interface form

await uniPush.cidsBindCustomTag(OBJECT)

Input parameters

name	type	required	default value	description
cids	String Array	Yes	None	List of cids to modify tag attributes, the length of the array is not more than 1000
custom_tag	String	Yes	No	Client tag, the tag cannot contain spaces, the maximum length of a single tag is 32 characters, if it contains Chinese characters, it needs to be encoded (UrlEncode)

• parameter example

{
	"cids": [
	    "xxx"
	],
    "custom_tag": "xxx"
}

Response body description

• return value example

{
    "errCode": 0,
    "errMsg": "success"
}

For the description of the return structure, please refer to Public Return Structure

A batch of devices unbind a tag

Unbind a label attribute of the device, without affecting other labels

This interface has frequency control (up to 100 times per minute and 10,000 times per day). To apply for modification, please click "Technical Consultation" on the right for details

Interface form

await uniPush.cidsUnboundCustomTag(OBJECT)

Input parameters

name	type	required	default value	description
cids	String Array	Yes	None	List of cids to modify tag attributes, the length of the array is not more than 1000
custom_tag	String	Yes	No	Client tag, the tag cannot contain spaces, the maximum length of a single tag is 32 characters, if it contains Chinese characters, it needs to be encoded (UrlEncode)

• parameter example

{
    "cids": [
        "xxx"
    ],
	"custom_tag":"xxx"
}

Response body description

{
    "errCode": 0,
    "errMsg": "success",
    "data": {
        "$cid": "true"
    }
}

For the description of the return structure, please refer to Public Return Structure

Query client tags

Query client tag list based on cid

This interface has frequency control (up to 100 times per minute and 10,000 times per day). To apply for modification, please click "Technical Consultation" on the right for details

Interface form

await uniPush.searchCustomTagByCid(cid)

Input parameters

name	type	required	default value	description
cid	Array	Yes	None	Device ID

Response body description

• return value example

{
    "errMsg": "success",
    "errCode": 0,
    "data": {
        "$cid": [
            "custom_tag1","custom_tag2"
        ]
    }
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

Name	Type	Description
$cid	Object	key: cid, value: list of tags, there will only be one element in the list, multiple separated by spaces

Blacklist devices

Blacklisted devices cannot receive push messages. When using group sending full push, sometimes it is necessary to adjust some devices not to send. At this time, you need to blacklist control by push_clientid.

Add blacklist device

Add single or multiple devices to the blacklist, and the blacklisted devices will be filtered out during the push process.

Interface form

await uniPush.addCidToBlacklist(push_clientid)

Input parameters

name	type	required	default value	description
push_clientid	String	Yes	None	Device IDs, separated by commas, up to 200 at a time

Response body description

• return value example

{
    "errCode": 0,
    "errMsg": "success"
}

For the description of the return structure, please refer to Public Return Structure

Remove blacklisted devices

Move a single push_clientid or multiple push_clientid devices out of the blacklist. For blacklisted devices that will be filtered out during the push process, messages will not be pushed to the blacklisted devices

Interface form

await uniPush.removeCidInBlacklist(push_clientid)

Input parameters

name	type	required	default value	description
getui_	String	Yes	None	Device IDs, separated by commas, up to 200 at a time

Response body description

• return value example

{
    "errCode": 0,
    "errMsg": "success"
}

For the description of the return structure, please refer to Public Return Structure

Device Information

Device online status

Check your application online status

Note: When the status is: offline offline, the message can be pushed through: other online application channels integrated with the personal push SDK under the same device (iOS does not support, Android is limited by the node setting policy of the mobile phone rom)

Interface form

await uniPush.getClientStatusByCid(push_clientid)

Input parameters

name	type	required	default value	description
push_clientid	String	Yes	None	Device IDs, separated by commas, up to 1000 at a time

Response body description

• return value example

{
    "errCode": 0,
    "errMsg": "success",
    "data": {
        "$cid": {
            "last_login_time":"1484018265935",
            "status":"offline"
        }
    }
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

Name	Type	Description
$cid	Object	key: cid, value: device status information
last_login_time	String	millisecond timestamp
status	String	Status, online online offline offline

Push channel status

Query the online status of all apps that have integrated Getui SDK on the same device (mobile phone) as your app

Notice:

1. When the interface returns to the device online, it only means that there is an online application integrated with the Getui SDK.
2. When the interface returns that the device is not online, it only means that there is no online application integrated with Getui SDK.
3. The interface needs to be activated. If you need to activate it, please contact the technical consultation on the right

Interface form

await uniPush.getDeviceStatusByCid(cid)

Input parameters

name	type	required	default value	description
cid	String	Yes	None	Device IDs, multiple separated by commas, up to 100 at a time

Response body description

• return value example

{
    "errCode": 0,
    "errMsg": "success",
    "data": {
        "$cid": {
            "errMsg":"success",
            "errCode": 0,
            "data": {
                "cid_status":"offline",
                "device_status":"online"
            }  
        }
    }
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

Name	Type	Description
$cid	Object	key: cid, value: device status information
cid_status	String	cid online status, online online offline offline
device_status	String	Device online status, online online offline offline

Device Details

Query device information

Interface form

await uniPush.getClientDetailByCid(String|Array)

Input parameters

name	type	required	default value	description
cid	String	Yes	None	Device IDs, separated by commas, up to 1000 at a time

Response body description

• return value example

{
    "errCode":0,
    "errMsg":"success",
    "data":{
        "invalidCids":[
            "invalidCid1",
            "invalidCid2",
            "invalidCid3"
        ],
        "validCids":{
            "${cid1}":{
                "client_app_id":"client_app_id",
                "package_name":"com.getui.demo",
                "device_token":"device_token",
                "phone_type":1,
                "phoneModel":"vv",
                "notificationSwitch":true,
                "createTime":"2021-06-30 00:00:00",
                "loginFreq":10
            }
        }
    }
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

Name	Type	Description
validCids	Object Array	List of device information
invalidCids	String Array	List of invalid cids

${cid} in validCids

Name	Type	Description
client_app_id	String	application id
package_name	String	Package name
device_token	String	Vendor token
phone_type	Number	Phone system 1-Android 2-ios
phoneModel	String	Model
notificationSwitch	Boolean	System notification bar switch
createTime	String	First login time
loginFreq	Number	Login Frequency

Query the total number of devices

Query the number of devices that meet the conditions by specifying query conditions

Interface form

await uniPush.getClientCount(OBJECT)

Input parameters

• parameter example

{
    "tag": [
         {
            "key":"phone_type",
            "values": [
                "android"
            ],
            "opt_type":"and"
        },
        {
            "key":"region",
            "values": [
                "11000000"
            ],
            "opt_type":"not"
        },
         {
            "key":"custom_tag",
            "values": [
                "tag1",
                "tag2"
            ],
            "opt_type":"or"
        }
    ]
}

• Request parameter description

name	type	required	default value	description
key	String	Yes	No	Query conditions (phone_type mobile phone type, region province and city, custom_tag client tag, please refer to [Interface](#%E5%AE%A2%E6%88%B7%E7%AB for setting tags) %AF%E6%A0%87%E7%AD%BE))
values	String Array	Yes	None	A list of query criteria values, where Mobile phone model uses the following parameters android and ios; Province and city use number, click to download the file region_code.data;
opt_type	String	Yes	None	or (or), and (and), not (not), intersection and complement of values

• The intersection between different keys, the same key is operated according to opt_type
• It needs to be sent to the city in A, B, C, the tagtest tag is not set, and the mobile phone model is android, it can be achieved with the conditional handover and complement function, city(A|B|C) && !tag(tagtest) && phonetype (android)

Response body description

Return value example

{
    "errCode": 0,
    "errMsg": "success",
    "data":{
        "user_count": 0
    }
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

Name	Type	Description
user_count	Number	Number of eligible devices

Set the application corner mark (only support IOS)

Notify the push server of the current iOS device's corner mark status through cid.

Interface form

await uniPush.setBadgeByCid(OBJECT)

Input parameters

name	type	required	default value	description
cid	String	Yes	None	Device IDs, multiple separated by English commas, up to 200 at a time
badge	String	Yes	None	The number displayed on the device app icon +N: +N on the original badge -N: -N on the original badge N: set badge directly (number, it will overwrite the original badge value)

• parameter example

{
	"cid":"xxx",
    "badge": "-8"
}

Response body description

Statistics API

Get push results

Query push data, you can query the number of messages that can be sent, the number of messages sent, the number of received messages, the number of impressions, the number of clicks and other results. Support single taskId query and multiple taskId query.

This API call can only query the push result data of toList or toApp; it cannot query the push result data of toSingle.

Interface form

await uniPush.getReport(OBJECT)

Input parameters

name	type	required	default value	description
taskid	String	Yes	None	The task id, returned when pushing, multiple taskIds are separated by commas, and a maximum of 200 can be uploaded at a time
actionIdList	String	No	None

Response body description

• content-type:application/json;charset=utf-8

• return value example

 {
    "errCode":0,
    "errMsg":"success",
    "data": {
        "$taskid": {
            "total": {
                "msg_num":4,
                "target_num":4,
                "receive_num":4,
                "display_num":2,
                "click_num":2
            },
            "gt": {
                "target_num":2,
                "receive_num":2,
                "display_num":1,
                "click_num":1
            },
            "actionCntMap": {
                "$actionId":2
            }
        }
    }
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

Name	Type	Description
$taskid	Object	key: task number, value: statistics
total	Object	Total Statistics
gt	Object	key represents the vendor channel, and value represents the statistics of the channel. Among them, gt: push channel; ios: APN; st: nuts; key can also be hw, xm, vv, mz, op.
msg_num	Number	Number of messages that can be sent
target_num	Number	Number of messages sent
receive_num	Number	Number of messages received
display_num	Number	Number of messages displayed
click_num	Number	Number of message clicks
actionCntMap	Object	Custom Event Statistics
$actionId	Number	$actionId is the custom event id, and the corresponding value represents the corresponding statistical data (statistics by the developer)

Task group name lookup report

Query the push results based on the task group name, and the returned results include the number of messages that can be delivered, the number of messages sent, the number of received messages, the number of impressions, and the number of clicks.

This API call can only query the push result data of toList or toApp; it cannot query the push result data of toSingle.

Interface form

await uniPush.getReportByGroupName(group_name)

Input parameters

name	type	required	default value	description
group_name	String	yes	none	task group name

Response body description

• return value example

 {
    "errCode":"0",
    "errMsg":"success",
    "data": {
        "$group_name": {
            "total": {
                "msg_num":4,
                "target_num":4,
                "receive_num":4,
                "display_num":2,
                "click_num":2
            },
            "gt": {
                "target_num":2,
                "receive_num":2,
                "display_num":1,
                "click_num":1
            },
            "ios": {
                "target_num":2,
                "receive_num":2,
                "display_num":1,
                "click_num":1
            }
        }
    }
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

Name	Type	Description
$group_name	Object	key task number, value: statistics
total	Object	Total Statistics
gt	Object	key represents the vendor channel, and value represents the statistics of the channel. Among them, gt: push channel; ios: APN; st: nuts; key can also be hw, xm, vv, mz, op.
msg_num	Number	Number of messages that can be sent
target_num	Number	Number of messages sent
receive_num	Number	Number of messages received
display_num	Number	Number of messages displayed
click_num	Number	Number of message clicks

Get push real-time results

Get real-time push results, and query the number of messages sent, received, displayed, clicked, and details of message damage. Support single taskId query and multiple taskId query.

Note: This interface needs to be activated. If you need to activate it, please contact the corresponding business students to activate it.

Interface form

await uniPush.getReportDetailByTaskid(taskid)

Input parameters

name	type	required	default value	description
taskid	String	Yes	None	The task id, returned when pushing, multiple taskIds are separated by commas, and a maximum of 200 can be uploaded at a time

Response body description

• return value example

{
    "errMsg":"success",
    "errCode":0,
    "data":{
        "$taskid":{
            "total":{
                "msg_num":320,
                "target_num":14,
                "receive_num":3,
                "display_num":3,
                "click_num":0
            },
            "gt":{
                "target_num":3,
                "receive_num":2,
                "display_num":2,
                "click_num":0
            },
            "apn":{
                "target_num":11,
                "receive_num":1,
                "display_num":1,
                "click_num":0
            },
            "failed_detail":{
                "rs":{
                    "gt":{
                        "12":{
                            "total":231
                        }
                    },
                    "apn":{
                        "11":{
                            "11999":1,
                            "total":1
                        }
                    }
                },
                "ts":{
                    "gt":{
                        "13":{
                            "13001":608,
                            "total":608
                        },
                        "14":{
                            "14001":3,
                            "total":3
                        }
                    }
                }
            }
        }
    }
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

Name	Type	Description
$taskid	Object	key: task number, value: statistics
total	Object	Total Statistics
gt	Object	key represents the vendor channel, and value represents the statistics of the channel. Among them, gt: push channel; apn: APNs channel; key can also be hw, xm, vv, mz, op.
msg_num	Number	Number of messages that can be sent
target_num	Number	Number of messages sent
receive_num	Number	Number of messages received
display_num	Number	Number of messages displayed
click_num	Number	Number of message clicks
failed_detail	Object	Message break details
ts	Object	Request-Deliverable stage loss data
rs	Object	Can be delivered-deliver the loss data at the successful stage
sf	Object	Successful delivery - damaged data at the arrival stage
fd	Object	Arrival-display stage damage data

• The meaning of the data under each channel in ts/rs/sf/fd

The breakdown details are classified as follows, 2-14 is the description of the breakdown category, 7001-8999 below the category description is the breakdown reason for the breakdown, and total represents the sum of the breakdown reasons

Name	Description
2	Invalid parameter
3	app authentication information error
4	Sensitive word filtering
5	Invalid device/app (uninstall)
6	The number of pushes exceeds the limit
7	Parameter overrun
8	No relevant permissions
10	Close notifications
11	Other Manufacturer Reasons
12	Offline within the validity period of the message
13	Invalid Device
14	Other
7001	title notification title is too long
7002	contentNotification content is too long
7003	URL is too long
7005	The content of extraData transparent transmission is too long
7006	The payload attached message is too long
2001	Parameter error
2002	title/content is empty, or url is not https protocol
2003	Untitled
2004	Click to jump to the target page is invalid (intent)
2005	This vendor does not support pure transparent transmission templates
2999	Other Reasons
8001	No API push permission/authToken not obtained
8002	System message switch not turned on
8003	Not at the time specified by the manufacturer
8999	Other Reasons

Get single-day push data

Call this interface to get the push data of an application in a single day (the push data includes: the number of deliveries, the number of receptions, the number of impressions, and the number of clicks) (currently, only data that is not on the current day can be queried)

Interface form

await uniPush.getReportByDate(date)

Input parameters

name	type	required	default value	description
date	String	yes	none	date, format: yyyy-MM-dd

Response body description

• return value example

{
    "errCode":0,
    "errMsg":"success",
    "data": {
        "$date": {
            "total": {
                "target_num":4,
                "receive_num":4,
                "display_num":2,
                "click_num":2
            },
            "gt": {
                "target_num":2,
                "receive_num":2,
                "display_num":1,
                "click_num":1
            },
             "hw": {
                "target_num":2,
                "receive_num":2,
                "display_num":1,
                "click_num":1
            }
        }
    }
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

Name	Type	Description
$date	Object	key: date, format: yyyy-MM-dd, value: statistics
total	Object	Total Statistics
gt	Object	key represents the vendor channel, and value represents the statistics of the channel. Among them, gt: push channel; ios: APN; st: nuts; key can also be hw, xm, vv, mz, op.
target_num	Number	Number of messages sent
receive_num	Number	Number of messages received
display_num	Number	Number of messages displayed
click_num	Number	Number of message clicks

Query push amount

Query the pushable amount and push balance of the application on the day

Notice:

1. Some manufacturers' messages do not limit the amount of push, so this interface does not return, such as hw/xmg manufacturers, op's private messages, xm's importance level messages, etc. 2.vv returns the request amount push_num, and the total arrival amount returned by the total limit total_num, so there may be cases where the request amount push_num exceeds the total limit total_num
2. This interface has frequency control restrictions, please do not call frequently

Interface form

await uniPush.getTodayReport()

Input parameters

none

Response body description

• return value example

{
    "errMsg":"success",
    "errCode":0,
    "data":{
        "vv":{
            "special":{
                "push_num":0,
                "total_num":"10000",
                "limit":false
            },
            "general":{
                "push_num":0,
                "total_num":"10000",
                "limit":false
            },
            "grouppush":{
                "push_num":0,
                "total_num":"1000",
                "limit":false
            }
        },
        "op":{
            "general":{
                "total_num":"100000",
                "limit":false,
                "remain_num":"100000"
            }
        },
        "xm":{
            "general":{
                "total_num":20000,
                "limit":false,
                "remain_num":20000
            }
        },
        "gt":{
            "app":{
                "total_num":3000,
                "limit":false,
                "remain_num":3000
            },
            "app_with_tag":{
                "total_num":1000,
                "limit":false,
                "remain_num":1000
            },
            "list":{
                "total_num":2000000,
                "limit":false,
                "remain_num":2000000
            }
        }
    }
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

In order to return the unified interface, special and general returns are used to represent special messages and ordinary messages.

Name	Type	Description
gt	Object	Push Channels
gt/app	Object	Push Limits for Individual Push and Group Push APIs
gt/list	Object	Limits on individual push creation message interfaces
gt/app_with_tag	Object	Individual push Filter device push interface push limit according to conditions
xm	Object	xmChannel
xm/general	Object	Common message limit for xm channel, push amount limit when channel is a common level message
op	Object	op channel
on	Object	on channel
op/general	Object	op channel Public letter message limit, push amount limit without channel or public letter channel
vv	Object	vvChannel
vv/special	Object	The vv channel system class message limit, that is, the push amount limit when classification=1
vv/general	Object	The vv channel operation message limit, that is, the push amount limit when classification=0
vv/grouppush	Object	vv group push message body configuration
total_num	long	The total amount that can be pushed in a single day
remain_num	long	The remaining amount that can be pushed in a single day
push_num	long	The number of push requests per day, only vv returns this field
limit	boolean	is limited, when the total pushable amount of the day is used up, this field will be updated to true

Get single-day device data interface

Calling this interface can get the device data of an application in a single day (device data includes: the number of new devices, the total number of registered devices, the online peak value, and the number of daily networked devices) (currently only data that is not on the current day can be queried)

Interface form

await uniPush.getClientReportByDate(date)

Input parameters

name	type	required	default value	description
date	String	yes	none	date, format: yyyy-MM-dd

Response body description

• return value example

{
    "errCode":0,
    "errMsg":"success",
    "data": {
        "$date": {
            "accumulative_num":9,
            "register_num":2,
            "active_num":5,
            "online_num":2
        }
    }
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

Name	Type	Description
$date	Object	key: date, format: yyyy-MM-dd, value: statistics
accumulative_num	Number	The cumulative number of registered devices
register_num	Number	Number of registered devices
active_num	Number	Number of active devices
online_num	Number	Number of online devices

Get the number of online devices for 24 hours

Query the number of online devices in one day at the current time (one point in 10 minutes, six points in one hour)

Interface form

await uniPush.getTodayOnlineClientReport()

Input parameters

none

Response body description

Successful response data format:

• content-type:application/json;charset=utf-8

• return value example

{
    "errCode":0,
    "errMsg":"success",
    "data": {
        "online_statics":{
            "$date":4,
            "$date":5
        }
    }
}

For the description of the return structure, please refer to Public Return Structure

• Return parameter data description

Name	Type	Description
online_statics	Object	Online device statistics
$date	Number	key: millisecond timestamp, value: number of online devices

public return structure

The following parameter formats are common formats for the data returned by each interface.

Name	Type	Description
errCode	Number	Success or failure errCode code, see [return code description](#%E8%BF%94%E5%9B%9E%E7%A0%81%E8%AF%B4%E6%98% 8E)
errMsg	String	This description is returned on failure
data	Object	See the interface description for details

Return code description

HTTP errCode description

The errCode of the uni-cloud-push extension library starts with uni-cloud-push-error-, such as: uni-cloud-push-error-10005, the following is omitted as 10005

errCode	Error description	Solution
0	successful	not involved
1	Fail	The interface input parameter is required to be in Object format, and non-Object format will not be recognized and will cause an error. It is recommended to check the code
2	Service is starting	Please wait
200	Success	View Basic Return Code
301	Domain name error	Please check whether the domain name matches the appid room
400	Parameter error	For specific exception information, please refer to the service return code
401	Permission related	For specific exception information, please refer to the business return code
403	Package related	For specific exception information, please refer to the business return code
404	URL error	Please check if the Http path is correct
405	Method not supported	The interface does not support the method request, please check the documentation to confirm the request method

10000 - permission related

errCode	Error description	Solution	Corresponding to http errCode
10001	Token error/invalid	Call the interface to get the token again	401
10002	appId or ip is in blacklist		401
10003	The authentication frequency per minute exceeds the limit	The interface is called too frequently	401
10004	No permission to query message details	You can apply for permission, if necessary, please click "Technical Consultation" on the right for details	401
10005	The call frequency per minute exceeds the limit		401

20000 - parameter related

errCode	Error description	Solution	Corresponding to http errCode
20001	Invalid parameter	Please check parameter	400
22001	The scheduled task has been executed and cannot be deleted		400
22002	The task is invalid or the time of the scheduled task is illegal		400
23001	Operation tag failed		400

30000 - Package-related, the return code related to the package can be specially configured for the application. If necessary, please click "Technical Consultation" on the right for details.

errCode	Error description	Corresponds to http errCode
30000	No permission to push fast_custom_tag	403
30001	No permission to modify and delete custom_tag	403
30002	No permission to push scheduled tasks	403
30003	The app/tag interface has no permission, or the tag is invalid	403
30004	The total number of tag pushes per day exceeds the limit (VIP users can configure it according to the application)	403
30005	The tag length exceeds the limit (tag length < 32)	403
30006	The number of fast_custom_tag exceeds the daily push limit (VIP users can configure it according to the application)	403
30007	app/all pushes, the number of pushes exceeds the daily limit of total pushes, and the maximum number of pushes per day is 100	403
30008	The number of list pushes exceeds the daily push limit, and the maximum number of pushes per day is 2,000,000	403
30009	The number of pushes exceeded the daily push limit	403
30010	The number of app/tag pushes exceeds the daily limit of total pushes, the maximum number of pushes per day is 100, and the sharing limit of the interface app/all	403
30011	The number of set tags exceeds the daily limit	403
30012	Modifying and deleting tags exceeds the frequency limit per minute, with a maximum of 5 operations per minute	403
30013	The frequency of pushing fast_custom_tag exceeds the frequency limit per minute (VIP users can configure it according to the application)	403
30014	The app push frequency exceeds the frequency limit per minute, with a maximum of 5 operations per minute	403
30015	The frequency of list push exceeds the frequency limit per minute	403
30016	The number of push/tag tags exceeds the limit	403
30017	No permission to query single push real-time report	403
30018	Query single push real-time report frequency exceeds the frequency limit per minute	403
30019	System is busy, please try again later	403

connect
push

WeChat scan
Feel free to contact Getui technical support