uni-app

Expand All

注意

您正在浏览的是老版uni-push1.0的文档。推荐升级到uni-push2.0

从HBuilderX 2.0.3 起，uni-app、5+App、wap2app均支持uni-push
从HBuilderX 2.7.10开始，支持谷歌FCM，参考：如何使用FCM

# uni-push介绍

查看uni-push介绍

# 1. Client integration

# 1.1 开通 `uni-push` 推送服务

uni-push 内部封装好了个推及主流厂商 SDK，开发者在使用前必须开通相关服务：点此查看如何开通uni-push推送服务。

**After completing the above steps, ios supports online and offline push; android only supports online push. **

# 1.2 Enable offline vendor push service

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:

目前华为、魅族、FCM不需要发布应用市场上就可使用离线推送(注：离线推送有条数限制)，其他厂商通道需要上架后才能使用。

# 1.3 Integration Verification

# 1.3.1 cid get

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"];
});

# 1.3.2 Check if offline vendor is available

If you do not need to use offline push, you can ignore this step.

在【uni-push/1.0/消息推送】-【配置管理】-【故障排查】-【状态查询】中输入CID 查询，看是否会返回 devicetoken 。

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.

Check whether the manufacturer parameters are configured in the background (the configured parameters need to be packaged in the cloud to take effect)

Huawei (including Honor) models require additional checks:

You need to configure the correct sha256 fingerprint certificate in the Huawei developer background
Cloud packaging uses its own certificate to print the official signature package
The name of the backend package of Huawei developers must be the same as the name of the client package.
Manufacturer push settings - Huawei manufacturers, must upload agconnect-services.json
Whether the Huawei push service has been activated on the Huawei platform
After saving the parameters, you need to resubmit the cloud package

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.

# 2. Server push message

Developers can push messages in one of the following three ways.

若您在测试过程中遇到无法收到推送的情况，请先按照 uni-push 1.0常见问题中的排查思路自助排查一下，例如常见问题：安卓离线收不到通知 。

# 2.1 Web page push in the background of the developer center

Testing online notification messages is recommended for you to use:

Test offline notification messages Recommended for you to use:

# 2.2 个推服务端 api 推送

# 2.2.1 Server message delivery process (must read)

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.

# 2.2.2 Server API usage

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.

服务端集成时首先需要获取 AppId、AppKey、MasterSecret 参数，登录 DCloud开发者中心，在“uni-push”-“1.0（老版本）”-“消息推送”下的“应用配置”页面中获取，如下图所示：

**Http request: **Parameter details can be viewed: Server RestAPI V2

Parameter example:

{
    "audience": {
        "cid": [
        ]
    },
    "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.
    },
    "push_channel": {
        "android": {
            "ups": {
                "notification": {
                    "title": "安卓离线展示的标题",
                    "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.
                }
            }
        },
        "ios": {
            "type": "notify",
            "aps": {
                "alert": {
                    "title": "苹果离线展示的标题",
                },
                "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.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.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.
        androidDTO.setUps(ups);
        pushChannel.setAndroid(androidDTO);

        //Message body pushed by ios offline apn channel
        Alert alert = new Alert();
        alert.setTitle("苹果离线通知栏标题");
        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());
        }
    }
}

# 2.2.3 Special parameter description

# 2.2.3.1 Intent

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，其中 io.dcloud.HBuilder 为 App 包名，需要替换为自己 App 的包名，与 App 云端打包界面设置的 Android 包名一致。

other instructions:

The value of S.title= is the push message title, which corresponds to the title attribute value of the PushMessage object in the 5+ API .
The value of S.content= is the push message content, which corresponds to the content attribute value of the PushMessage object in the 5+ API .
The value of S.payload= is the data of the push message, which corresponds to the payload attribute of the PushMessage object in the 5+ API value.
The launchFlags=0x4000000 field is to solve the problem that the click event may not be triggered after receiving multiple notifications.

# 2.2.3.2 Special transparent message

uni-push推送服务对透传消息的数据符合以下格式时做了特殊处理，会将如下格式的透传消息，直接在通知栏中展示通知。

Precautions:

Only applicable to Android, ios still requires developers to manually create notifications in the receive passthrough callback;
The transparent message in the following format will not enter the receive callback when the message arrives, and only trigger the "click" event when the app is activated by clicking on the message.

{"title": "xxx","content": "xxx","payload": "xxx"}

# 2.3 uniCloud development server

Use the packaged server-side to develop easy-to-use plug-ins. For details, please refer to: uniPush's uniCloud version [V2]

# 3. The client processes push messages

# 3.1 Support message scope

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

# 3.2 Client API

# 3.2.1 Message Handling

uni-push 推送服务已经封装好 iOS&Android 平台的原生集成工作，开发者只需要调用 JS 代码处理推送消息的业务逻辑。

若您需要在客户端接收处理推送 uni-push 推送内容，请先阅读了解此对接指南开头的 “消息推送流程”，客户端回调处理可参考：在uni-app中使用uni-push 。

Precautions:

Due to the limitations of the ios system, when the ios app is online, only transparent messages can be pushed. The developer needs to receive the transparent transmission message in the client receive transparent transmission callback and process the message display method according to its own business scenario. If it is not processed by default, there will be no display, and the transparent transmission message is only responsible for delivery.

other

Use Conditional Compilation to directly call 5+ Push interface, refer to [5+ APP Push Development Guide](https://ask.dcloud.net.cn/article/ 34)
The client-side js api of uni is still plus.push, and the code previously developed using plus.push can still be used.

# 3.2.2 The corner label of the application desktop icon

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

服务端 rest-v2 设置示例，注意uni-push用户的class的值请固定使用'io.dcloud.PandoraEntry'

{
    "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

根据接收到的推送消息处理桌面图标的角标，在uni-push后台的“iOS配置”项中可配置 badge 参数对角标进行设置，可取值：

"+1", indicating that the current index is +1;
"-1", which means the current index is -1 (the index >=0);
"3", indicating the specified superscript value, the value must be >=0.

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.