English
注意
您正在浏览的是老版uni-push1.0的文档。推荐升级到uni-push2.0
From HBuilderX 2.0.3, uni-app, 5+App, wap2app all support UniPush From HBuilderX2.7.10, support Google FCM, reference: https://ask.dcloud.net.cn/article/37356
UniPush is an integrated unified push service launched by DCloud and a push company. It has built-in system-level push and personal push and other third-party push from mobile phone manufacturers such as Apple, Huawei, Xiaomi, OPPO, VIVO, Meizu, and Google FCM.
Domestic Android Push is a chaotic world, because Google's Push service FCM is blocked, so some domestic Android mobile phone manufacturers have made their own push, such as Huawei, Xiaomi, OPPO, VIVO, Meizu, etc., but there are many domestic Mobile phone manufacturers do not provide an official push program. A three-party independent company, such as a push, provides an independent push solution. Before there was no uniPush, if only three-way push was used, the push process could not be kept alive on many domestic mobile phones due to power saving settings, resulting in the inability to push. If the official Push SDK of each Android phone is integrated and developed, the workload of so many platforms will be huge, and the management and maintenance will be very troublesome.
uniPush solves this problem, and developers only need to develop it once. The system will automatically select the most reliable push channel to send push messages on different mobile phones to ensure the delivery rate.
UniPush not only reduces the development cost, but also improves the delivery rate of push, and it is free. It is the best solution for push at present.
With unipush, developers should no longer use other push schemes. However, we found that many developers have misunderstandings, which lead to the wrong use of other pushes.
Common Misunderstanding 1: "Is uniPush's professionalism comparable to professional personal push, Aurora and other services?"
Answer: uniPush is a push product that was originally charged by a pusher, and some important VIP functions are provided to DCloud developers for free. There are only 2 differences between it and vip push:
Common misunderstanding 2: "uniPush is so troublesome, I just like simple sdk such as Push and Aurora, and I don't want to go to various rom manufacturers to apply for a circle" A: uniPush is not based on applying for authorization from a mobile phone manufacturer. If you don't apply for those, it will be the same as using an ordinary push button. However, special attention should be paid to the current status of the push industry: **Without integrating the push of the rom manufacturer, it is impossible to send push when the app is offline. **. According to the ordinary push mode, the consequence is that offline messages cannot be sent on Huawei, Xiaomi, OPPO, VIVO, and Meizu.
Common Misunderstanding 3: "The delivery rate of uniPush is still not enough. Is it possible to pay to increase the delivery rate? There is a way to pay to increase the delivery rate of uniPush" A: It has been mentioned above. The paid product of a push to improve the delivery rate is vip push, and uniPush is a push vip push. DCloud is freely available to DCloud developers through negotiation.
Common Misunderstanding 4: To open uniPush, you need real-name authentication, and you have to pass your ID card. You don't need to be so troublesome to open a normal push. A: This problem existed before, and it has been dealt with later, keeping the same identity information as Getui, and no longer needing an ID card.
Noun | Explanation |
---|---|
Notification Message | After specifying the notification title and content, the Getui SDK will automatically display the notification bar message in the system notification bar, and at the same time ring or vibrate to remind the user (the ringing and vibration are affected by the setting status of the mobile phone system). |
Transparent message | That is, a custom message, the message body format can be defined by the customer, such as plain text, json string, etc. The pass-through message only transmits data and does not do any processing. After the client receives the pass-through message, it needs to do follow-up actions by itself, such as notification bar display, pop-up box, etc. |
ClientId | The external user ID in the Getui business layer, used to identify the client identity. It is obtained by the third-party client and saved to the third-party server. It is the unique identification number of the Getui SDK, or CID for short. |
Online Push | When the app opens and runs in the foreground, it sends messages through a push channel. |
Offline push | When the app is in the background, locked screen, or the process is closed, messages are sent through the manufacturer's channel. If the android multi-vendor is not integrated and the ios push certificate is not configured, the model cannot use offline push. |
For more noun explanation reference: Tweet noun explanation
Unipush has internally packaged a push and mainstream manufacturer SDK, and developers must activate related services before using it: Click here to see how to activate the UniPush push service .
**After completing the above steps, ios supports online and offline push; android only supports online push. **
If you need to support mainstream android vendor clients to receive offline push, you need to complete: android multi-vendor configuration.
After configuring the manufacturer parameters, be sure to submit the cloud package and use the "own certificate" to sign the package; install the cloud packaged installation package on the mobile phone, and then obtain the cid for offline manufacturer push test, which cannot be obtained by the pedestal method. cid for offline vendor push testing.
Precautions:
The plus.push.getClientInfoAsync method of 5+ API should be called to obtain the client ID when the application is run for the first time after installation .
If the obtained cid is empty, it means that the client's registration with the push server has not been completed, and you can use setTimeout to delay retry.
plus.push.getClientInfoAsync((info) => {
let cid = info["clientid"];
});
If you do not need to use offline push, you can ignore this step.
Enter the CID query in [Uni Push]-[Configuration Management]-[Troubleshooting]-[Status Query] to see if the devicetoken will be returned.
If devicetoken is returned:
Offline push testing can be started.
If no devicetoken is returned:
It means that the manufacturer is not properly integrated, and the offline push function cannot be used.
Huawei (including Honor) models require additional checks:
pay attention
When changing the application package name or certificate on the Huawei vendor platform, the cloud agconnect-services.json and package name need to be updated synchronously. Otherwise, the packaging will fail.
Developers can push messages in one of the following three ways.
If you encounter a situation where you cannot receive push notifications during the test, please follow the troubleshooting ideas in Unipush FAQs to check by yourself, for example, common problems Problem: Android offline can't receive notifications.
Log in to DCloud Developer Center, select an app in the "Apps I Created" list, and select "Uni Push" on the left to open the message push page.
Testing online notification messages is recommended for you to use:
Test offline notification messages Recommended for you to use:
When the CID is online (i.e. the app is open and running in the foreground):
The message is sent to the client through a push channel, specifically in the server-side Rest-V2 code, that is, the notification (notification) or transmission (transparent transmission) content in push_message is passed to the client.
When CID is offline (i.e. app in background, locked screen, process closed):
If the offline function of the corresponding manufacturer is enabled, the message will request the server of the corresponding manufacturer through a push side, which is specific to the Rest-V2 code of the server, that is, the notification content in the push_channel is passed to the manufacturer, and the actual message is sent through the manufacturer's server. Sent to the client; if the server push_channel does not pass a value, it cannot receive offline messages.
For those who do not have the corresponding manufacturer function enabled, the message will be stored in the offline library of Ge Push, waiting for the CID to be online, and then sent to the client through the push channel.
You can view the server interface documentation of GePush: Server RestAPI V2, it supports the following two ways to call, just choose one of them, It is recommended that you use Http requests.
When integrating the server, you first need to obtain the AppId, AppKey, and MasterSecret parameters, log in to DCloud Developer Center, and obtain them on the "App Configuration" page under "Uni Push" ,As shown below:
**Http request: **Parameter details can be viewed: Server RestAPI V2
Parameter example:
{
"request_id": "请填写10到32位的id",
"audience": {
"cid": [
"请输入clientid"
]
},
"settings": {
"ttl": 3600000,
"strategy": {
"default": 1
}
},
"push_message": {
//The transparent transmission message in this format is specially processed by unipush, and the notification bar will be displayed automatically. Developers can also customize other formats and handle them on the client side.
"transmission": "{title:\"标题\",content:\"内容\",payload:\"自定义数据\"}"
},
"push_channel": {
"android": {
"ups": {
"notification": {
"title": "安卓离线展示的标题",
"body": "安卓离线展示的内容",
"click_type": "intent",
//Note: The intent parameter must be passed in the fixed format required by the following document (special parameter description). If the intent is wrong, the client will not be able to receive the message.
"intent": "请填写固定格式的intent"
}
}
},
"ios": {
"type": "notify",
"payload": "自定义消息",
"aps": {
"alert": {
"title": "苹果离线展示的标题",
"body": "苹果离线展示的内容"
},
"content-available": 0,
"sound": "default"
},
"auto_badge": "+1"
}
}
}
SDK Integration:
The main goal of Getui server SDK is to improve the development efficiency of developers integrating Getui push service on the server side. Developers do not need to perform complex programming to use the common functions of the Getui push service. The SDK can automatically help you meet the non-functional requirements such as authentication, assembly parameters, and sending HTTP requests during the calling process. Currently, only supports Java and PHP languages.
Before using the following code, please check the Getui Server Java SDK, and configure to use the latest version of the SDK. If you want to see detailed field descriptions, or want to integrate PHP SDK, you can check: Server-side RestAPI V2 .
Java SDK parameter example:
import com.getui.push.v2.sdk.ApiHelper;
import com.getui.push.v2.sdk.GtApiConfiguration;
import com.getui.push.v2.sdk.api.PushApi;
import com.getui.push.v2.sdk.common.ApiResult;
import com.getui.push.v2.sdk.dto.req.Audience;
import com.getui.push.v2.sdk.dto.req.Settings;
import com.getui.push.v2.sdk.dto.req.message.PushChannel;
import com.getui.push.v2.sdk.dto.req.message.PushDTO;
import com.getui.push.v2.sdk.dto.req.message.PushMessage;
import com.getui.push.v2.sdk.dto.req.message.android.AndroidDTO;
import com.getui.push.v2.sdk.dto.req.message.android.ThirdNotification;
import com.getui.push.v2.sdk.dto.req.message.android.Ups;
import com.getui.push.v2.sdk.dto.req.message.ios.Alert;
import com.getui.push.v2.sdk.dto.req.message.ios.Aps;
import com.getui.push.v2.sdk.dto.req.message.ios.IosDTO;
import java.util.Map;
public class UnipushTest {
public static void main(String[] args) {
GtApiConfiguration apiConfiguration = new GtApiConfiguration();
//Fill in the application configuration, the parameters are obtained from the "Application Configuration" page under "Uni Push"
apiConfiguration.setAppId("请填写AppId");
apiConfiguration.setAppKey("请填写AppKey");
apiConfiguration.setMasterSecret("请填写MasterSecret");
apiConfiguration.setDomain("https://restapi.getui.com/v2/");
// Instantiate the ApiHelper object for creating interface objects
ApiHelper apiHelper = ApiHelper.build(apiConfiguration);
// Create an object, it is recommended to reuse. Currently there are PushApi, StatisticApi, UserApi
PushApi pushApi = apiHelper.creatApi(PushApi.class);
//Single push according to cid
PushDTO<Audience> pushDTO = new PushDTO<Audience>();
// Set push parameters, requestid needs to be unique each time
pushDTO.setRequestId(System.currentTimeMillis() + "");
Settings settings = new Settings();
pushDTO.setSettings(settings);
//The validity period of the message, this value must be set for the manufacturer message
settings.setTtl(3600000);
//The message body pushed when a push channel is online
PushMessage pushMessage = new PushMessage();
pushDTO.setPushMessage(pushMessage);
//The transparent transmission message in this format is specially processed by unipush, and the notification bar will be displayed automatically. Developers can also customize other formats and handle them on the client side.
pushMessage.setTransmission(" {title:\"标题\",content:\"内容\",payload:\"自定义数据\"}");
// set recipient information
Audience audience = new Audience();
pushDTO.setAudience(audience);
audience.addCid("请填写cid");
//Set the message body for offline push
PushChannel pushChannel = new PushChannel();
//The message body pushed by the Android offline vendor channel
AndroidDTO androidDTO = new AndroidDTO();
Ups ups = new Ups();
ThirdNotification thirdNotification = new ThirdNotification();
ups.setNotification(thirdNotification);
thirdNotification.setTitle("安卓离线展示的标题");
thirdNotification.setBody("安卓离线展示的内容");
thirdNotification.setClickType("intent");
//Note: The intent parameter must be passed in the fixed format required by the following document (special parameter description). If the intent is wrong, the client will not be able to receive the message.
thirdNotification.setIntent("请填写固定格式的intent");
androidDTO.setUps(ups);
pushChannel.setAndroid(androidDTO);
//Message body pushed by ios offline apn channel
Alert alert = new Alert();
alert.setTitle("苹果离线通知栏标题");
alert.setBody("苹果离线通知栏内容");
Aps aps = new Aps();
aps.setContentAvailable(0);
aps.setSound("default");
aps.setAlert(alert);
IosDTO iosDTO = new IosDTO();
iosDTO.setAps(aps);
iosDTO.setType("notify");
pushChannel.setIos(iosDTO);
pushDTO.setPushChannel(pushChannel);
// Perform cid single push
ApiResult<Map<String, Map<String, String>>> apiResult = pushApi.pushToSingleByCid(pushDTO);
if (apiResult.isSuccess()) {
// success
System.out.println(apiResult.getData());
} else {
// failed
System.out.println("code:" + apiResult.getCode() + ", msg: " + apiResult.getMsg());
}
}
}
In view of the fact that each manufacturer's SDK has multiple ways to open application custom pages, and some of them are incompatible with each other, in order to maintain unity and facilitate developers, Getui provides a standard and unique way to open custom pages in apps through the server API. Specify the intent parameter.
Intent must be set when using manufacturer push to deliver push messages. This data format is the origin of Android native Intent object serialization. For details, please refer to Details. And the intent must conform to the following format. This format is encapsulated twice on the basis of the inferred amount, so this format must prevail. Not setting the intent in this format may cause the user to click on the push message to fail to launch the app, and the click event cannot be responded to when offline. The intent data format is as follows:
intent://io.dcloud.unipush/?#Intent;scheme=unipush;launchFlags=0x4000000;component=io.dcloud.HBuilder/io.dcloud.PandoraEntry;S.UP-OL-SU=true;S.title=测试标题;S.content=测试内容;S.payload=test;end
Precautions:
component=io.dcloud.HBuilder/io.dcloud.PandoraEntry, where io.dcloud.HBuilder is the app package name, which needs to be replaced with the package name of your own app, which is the same as the Android package name set in the app cloud packaging interface.
other instructions:
UniPush push service makes special processing for the data of the transparently transmitted message in the following format, and will directly display the notification in the notification bar of the transparently transmitted message in the following format.
Precautions:
{"title": "xxx","content": "xxx","payload": "xxx"}
Use the packaged server-side to develop easy-to-use plug-ins. For details, please refer to: uniPush's uniCloud version [V2]
Client | Individual Push Notification | Individual Push Transparent Transmission | Manufacturer Notification | Vendor Transparent Transmission |
---|---|---|---|---|
android | supported | supported | supported | not supported |
ios | not supported | supported | supported | not supported |
The UniPush push service has already encapsulated the native integration work of the iOS & Android platform, and developers only need to call the JS code to process the business logic of the push message.
If you need to receive and process UniPush push content on the client side, please read and understand "Message Push Process" at the beginning of this linking guide. For client-side callback processing, please refer to: [Using UniPush in uni-app](https 😕/ask.dcloud.net.cn/article/35726) .
Precautions:
other
For models that support badge setting, you can call 5+ API plus.runtime.setBadgeNumber to set or clear the badge when the app is pushed online.
Android Platform
Different ROMs have differences in the processing logic of desktop icons when receiving push messages. The Android manufacturers support offline corner icons as follows:
For oppo/Meizu, some mobile phone systems can set up corner mark dots, but there is no function of digital corner mark.
The Xiaomi system has its own offline notification digital corner display function, which is processed by +1 by default and cleared when turned on.
The high version of vivo system comes with the offline notification digital corner mark display function, which is processed by +1 by default and cleared when turned on. The lower version does not have the corner mark function.
Huawei's logo requires the server api to set the field, and the client needs to manually set the number of logos to 0
Version supported by add method: EMUI version 8.0.0 and push service application version 8.0.0 and above
Example of server-side rest-v2 setting, please use 'io.dcloud.PandoraEntry' for the value of the Unipush user's class
{
"android": {
"ups": {
"notification": {
// ...other push_channel parameters omitted
},
"options": {
"HW": {
"/message/android/notification/badge/class": "io.dcloud.PandoraEntry",
"/message/android/notification/badge/add_num": 1
}
}
}
}
}
iOS Platform
The corner label of the desktop icon is processed according to the received push message. In the "iOS Configuration" item of the uniPush background, the badge parameter can be configured to set the corner label. The possible values are:
By default (without setting the badge parameter), the badge number remains unchanged, or you can call the 5+ API [plus.runtime.setBadgeNumber](https://www.html5plus.org/doc/zh_cn/runtime.html# plus.runtime.setBadgeNumber) to dynamically set the badge number.
Android platform APP is online (a push channel is available) Both push notifications and pass-through messages use a push channel to deliver push messages. APP is offline (Push channel is unavailable) Push notifications, using a push offline push channel, offline messages will be stored in the offline message library, and the APP will send push messages when it is online during the offline time. Transparent transmission of the message, if it matches the manufacturer's mobile phone (configured with the mobile phone manufacturer's push parameters and on the mobile phone of the corresponding manufacturer), then use the manufacturer's push channel to deliver the push message; otherwise, use the offline push channel of Personal Push, and the offline message will be stored. In the message offline library, the APP will send push messages after the APP is online during the offline time.
iOS platform Push notification. This type of push notification is not supported in the uniPush background management interface. The server-side API provided by Ge Push supports the sending of push notifications (the APN parameter is set through Apple's APNS channel, otherwise the Ge Push channel is used). The message is transparently transmitted. If the APN parameter is set, the push message will be sent through Apple's APNS channel. If the APN parameter is not set, the push message will be sent through the Push channel.
To use Huawei's manufacturer push channel, you must install "Huawei Mobile Services" on a Huawei mobile phone. First, make sure that the "Huawei Mobile Services" application has been installed on your mobile phone. If you cannot receive push messages after exiting the Huawei mobile app, you need to ensure that:
After HBuilderX3.0.7, in addition to configuring the original vendor information, Huawei needs to add a new configuration agconnect-services.json file.
You need to be online in the VIVO app store to apply for VIVO's manufacturer push Precautions:
You need to be online in the OPPO app store to apply for OPPO's manufacturer push
and has the following requirements:
The Android phone needs to have GMS installed, and the mobile phone network can be connected to the Google FCM push server. For detailed tutorials, see: https://ask.dcloud.net.cn/article/37356.
If the application can receive push messages online, but cannot receive push messages using the vendor channel when offline, please refer to UniPush vendor channel FAQ [https://ask.dcloud.net.cn/article/36611](https:/ /ask.dcloud.net.cn/article/36611)
Finally, you can also log in to Getui Official Website, or use WeChat to scan the QR code below for technical consultation
Q: What if 5+app and wap2app need uniPush? A: Since HBuilderX 2.0.3, 5+app and wap2app also support uniPush. 5+app and wap2app upgrade uniPush without changing the front-end code of the app, just open the "SDK Configuration" page of manifest.json in HBuilderX, check "DCloud UniPush" under "Push", and click "Configure", in the background Activate the unipush service, configure the manufacturer's push parameters, and resubmit the cloud package. The backend server needs to refer to the second step to connect to the push service.
Q: How to configure offline packaging? A: Android Platform App Offline Packaging-Push iOS Platform App Offline Packaging-Push
Q: How does the iOS platform realize that the "Send Notification" system authorization box does not pop up immediately after the app is launched? A: Reference: https://ask.dcloud.net.cn/article/36955
Q: Why after the Android app enters the background (the app is not destroyed), the app cannot be launched by clicking the notification message. A: Check whether the device has a pop-up interface in the background, path >> Settings - Application Management - Test Application - Permission Management - Pop-up interface in the background, (usually Xiaomi, oppo, vivo devices).