Integrating Push Kit

Overview

Push Kit enables you to send latest messages from the cloud to devices, improving user perception and engagement and building good user relationships.

Push messages can be sent to mobile phones running EMUI 8.0 or later.

The following figure shows the process of sending a push message.

Before You Start

Before integrating Push Kit into your app, you'll need to complete the following preparations:

• Register as a Huawei developer and pass identity verification on HUAWEI Developers.
• Create a quick app in AppGallery Connect.
• Enable Push Kit in AppGallery Connect.
• Install Huawei Quick App IDE for Push Kit integration.

Integration Guide

1. Call the push.getProvider API in your quick app to check whether the current device supports Push Kit.

   Only the return value huawei indicates yes. You can develop relevant functions and call Push Kit APIs only when the current device supports Push Kit.

2. Call the push.subscribe API to obtain regId.

   regId is also called token or push token, which is used to send push messages. The value length is not fixed. The following examples show the two formats in which the value can be:

   • 0862767037246841300005665000CN01
   • ANDmbp0JwPTftSc4tY90C2aW6xTGyKtTIY4idTf5GekYFfOKYmKTeqYlyKYUS0CQbf2xmUdkKWaYU6AoO1Ju6bL5lQgU7pmzQD_6cdIEABhHTLPYhMcsoF64B0tNAE_eBg
   NOTICE

   regId obtained from Huawei Quick App Loader can only be used in the quick apps running on the loader to push messages. It cannot be used in the quick apps released on AppGallery.

3. Obtained regId can be reported to your server through the Fetch API for further message pushing.

   Generally, the value of regId does not change and does not need to be reported to the server each time after it is obtained.

   You are advised to store regId using the Data Storage API locally and compare obtained regId each time with the local one. If they are the same, regId does not need to be reported to the server, and vice versa.

   The following figure shows the overall process.

   

   Sample code for obtaining regId and comparing it with locally stored content:

   checkToken() {
       var subscribeToken=this.$app.$def.dataApp.pushtoken;
       console.log("checkToken subscribeToken= "+subscribeToken);
       var storage = require("@system.storage");
       var that=this;
       storage.get({
           key: 'token',
           success: function (data) {
               console.log("checkToken handling success data= "+data);
               if (subscribeToken != data) {
                  // Report to your server.
                    that.uploadToken(subscribeToken);
                   that.saveToken(subscribeToken);
               }
           },
           fail: function (data, code) {
               console.log("handling fail, code = " + code);
           }
       })
   },

   Sample code for storing regId locally:

   saveToken(subscribeToken){
     console.log("saveToken");
     var storage = require("@system.storage");
     storage.set({
       key: 'token',
       value: subscribeToken,
          success: function (data) {
           console.log("saveToken handling success");
       },
       fail: function (data, code) {
           console.log("saveToken handling fail, code = " + code);
       }
     })
   },

4. Send a push message.
5. Process the push message.

   Push messages are displayed in the notification panel. When a user taps the message, a quick app page is displayed and the parameter values carried are assigned to the corresponding parameters on the page.

Sending Messages

You can use either of the following methods to send messages:

• From AppGallery Connect: You can specify some target users and send the messages to both quick apps on the live network and those running on Huawei Quick App Loader.
• Through server API: You can send messages to a large number of users in batches for both quick apps on the live network and those running on Huawei Quick App Loader.

A quick app can receive push messages when the following conditions are met.

Sending Messages in AppGallery Connect

1. Sign in to AppGallery Connect and click My projects.
2. Click the project card for which you want to configure a push message.
3. Go to Grow > Push Kit.

   

4. Click Add notification to configure a push message. For details, please refer to Sending a Notification Message to a Huawei Quick App.
   NOTE

   • To improve user experience and reduce the disturbance to users, a quick app can push a maximum of five messages to the same user every day.
   • Push messages shall not contain content irrelevant to the quick app services or information such as fraudulently-induced ads or information related to vulgarity, fraud, pornography, terrorism, and politics. Otherwise, the violators will be punished. For details, please refer to Penalty Regulations on Push Message Violation in Quick Apps.
   • You can push messages up to 100 times to each of your app and to no more than 500 devices each time.

Sending Messages Through the Server API

APIs for obtaining the access token and sending push messages are included in this mode.

API for obtaining the access token

For details about the API, please refer to OAuth 2.0-based Authentication.

API for sending push messages

Sends push messages.

Protocol: HTTPS POST

API access URL: https://push-api.cloud.huawei.com/v1/[clientid]/messages:send

Request parameters (HTTP header)

Request parameters (HTTP body):

{
    "validate_only": false,
    "message": {
        "data": JSON_FORMAT_STRING,
        "android": {
            "fast_app_target": 1
        },
        "token": ["AJRqlvj_atpAUr6qa2hZY-dRBSqzs-OJpF37fXShdXa7hXRHgX5v0M_-aF3KSXqLqhUreGMXmiiyzGVWYVToAa4ohlAUy_RsC75wxv7lnG2-rxf6RV_ivNbLjOCbYQ-tdw"]
    }
}

Request parameters

message structure

Sample code in data:

{
    "pushtype": 0,
    "pushbody": {
        "title": "Push message title",
        "description": "Push message content",
        "page": "/",
        "params": {
            "key1": "test1",
            "key2": "test2"
        }
    }
}

data structure

AndroidConfig structure

Sample code of the push message body:

var mData = {
    "pushtype": 0, // The value 0 indicates that the message is a notification message.
    "pushbody": {
        "title": "Push message title",
        "description": "Push message content",
        "page": "/", // Path of the quick app page that is displayed when a user taps a notification message. This parameter is valid only when pushtype is set to 0. The value / indicates that the target page is the quick app home page.
        "params": {
            "key1": "test1",
            "key2": "test2"
        },
    }
};
var formatJsonString = JSON.stringify(mData);
var messbody = {
    "validate_only": false,
    "message": {
        "data": formatJsonString, // Note that the type of data is a JSON string, not a JSON object.
        "android": {
            "fast_app_target": 1, // The value 1 indicates that the message is sent to a quick app running on Quick App Loader. To send message to a quick app to be released on AppGallery, set the value to 2.
            "collapse_key": -1,
            "delivery_priority": "HIGH",
            "ttl": "1448s",
            "bi_tag": "Trump",
         },
         "token": ['pushtoken1','pushtoken2'], // Target user of the message.
    }
};

Response parameters

The responses are as follows.

Result Codes

HTTP Result Codes

System Result Codes (Returned by HTTP Header Extension NSP_STATUS)

App Result Codes

Penalty Regulations on Push Message Violation in Quick Apps

Purpose and Scope

This document is hereby developed to ensure that quick app developers properly use the push capabilities provided by quick apps, ensure that the push content complies with relevant rules, and improve user satisfaction.

Definition of Content Violations and Penalties

(1) Definition of Violation Levels

(2) Penalty Rules for Violations

Penalty Execution

1. Huawei performs continuous supervision through operations monitoring and user feedback. If any violation is found in your quick app's push content, the corresponding penalty will be executed and you will be notified by an email sent by developer@huawei.com. The notification email will be sent to the email address you have set on HUAWEI Developers.
2. If you promise to rectify the violations and do not violate the rules again, the push service will be restored for the quick app when the penalty period ends.

Effectiveness and Interpretation

This document takes effect from July 30, 2020. HUAWEI Quick App reserves the right of final interpretation on this document. If any rules are adjusted, they will be updated on the HUAWEI Developers official website.

Demo

Watch video

app.ux file: Obtain the value of regId.

<script>
    import push from '@service.push';
    import fetch from '@system.fetch';
    import prompt from '@system.prompt';
    
    module.exports = {
        dataApp: {
            pushtoken: ''
        },
        onCreate() {
            console.info('Application onCreate');
            setTimeout(() => {
                this.checkPushIsSupported();
            }, 1000);

        },

        checkPushIsSupported() {
            let provider = push.getProvider();
            console.log("checkPush provider= " + provider);
            if (provider === 'huawei') {
                this.pushsubscribe();
            }
        },

        pushsubscribe() {
            console.log("pushsubscribe start");
            var that = this;
            push.subscribe({
                success: function (data) {
                    console.log("push.subscribe succeeded, result data=" + JSON.stringify(data));
                    that.dataApp.pushtoken = data.regId;
                    console.log("app oncreate this.dataApp.pushtoken=" + that.dataApp.pushtoken);
                    that.checkToken();

                },
                fail: function (data, code) {
                    console.log("push.subscribe failed, result data=" + JSON.stringify(data) + ", code=" + code);
                },
                complete: function () {
                    console.log("push.subscribe completed");
                }
            })
        },

        checkToken() {
            var subscribeToken = this.dataApp.pushtoken;
            console.log("checkToken subscribeToken= " + subscribeToken);
            var storage = require("@system.storage");
            var that = this;
            storage.get({
                key: 'token',
                success: function (data) {
                    console.log("checkToken storage data= " + data);
                    if (subscribeToken !== data) {
                        //upload it to your own service server
                        that.uploadToken(subscribeToken);
                        that.saveToken(subscribeToken);
                    } else {
                        console.log("checkToken regid is  the same as local storage");
                    }
                },
                fail: function (data, code) {
                    console.log("checkToken handling fail, code = " + code);
                }
            })
        },

        saveToken(subscribeToken) {
            console.log("saveToken");
            var storage = require("@system.storage");
            storage.set({
                key: 'token',
                value: subscribeToken,
                success: function (data) {
                    console.log("saveToken handling success");
                },
                fail: function (data, code) {
                    console.log("saveToken handling fail, code = " + code);
                }
            })
        },

        uploadToken(subscribeToken) {
            console.log("uploadToken");
            var that = this;
            var body = {
                xx: subscribeToken
            };

            fetch.fetch({
                url: 'https://xxx',
                method: 'POST',
                data: body,
                success: function (data) {
                    console.log("uploadToken code: " + data.code);
                    console.log("uploadToken data: " + data.data);
                },
                fail: function (data, code) {
                    console.log("handling fail, code = " + code);
                }
            })
        },

        pushunsubscribe() {
            push.unsubscribe({
                success: function (data) {
                    console.log('push.unsubscribe succeeded, result data = ' + JSON.stringify(data));
                    prompt.showToast({
                        message: 'push.unsubscribe succeeded',
                        duration: 2000,
                        gravity: 'center'
                    })
                },
                fail: function (data, code) {
                    console.log('push.unsubscribe failed, result data = ' + JSON.stringify(data) + ', code = ' + code);
                },
                complete: function () {
                    console.log('push.unsubscribe completed');
                }
            })
        }

    }
</script>

sendnotify.ux file: This sample code uses the fetch API to simulate a server to send messages. In actual development, use your own server.

<template>
  <div class="doc-page">
    <input type="button" class="btn" value="send notify msg" onclick="sendNotifyMsg" />
    <input type="button" class="btn" value="Do not receive Push messages" onclick="unregister" />
  </div>
</template>

<style>
    .doc-page {
      flex-direction: column;
      flex-direction: column;
      justify-content: center;
      align-content: center;
      align-items: center;
    }

    .btn {
      border-radius: 8px;
      margin-top: 16px;
      width: 80%;
      background-color: #4169e1;
      color: white;
    }
    .btn:active {
      background-color: #20b2aa;
    }
</style>
<script>
    import router from "@system.router"
    import prompt from '@system.prompt'
    import push from '@service.push';
    import fetch from '@system.fetch';
    import account from '@service.account';
    export default {
        props: ['websrc'],
        data: {
            attoken: '',
        },

        onInit: function () {
            //this.$page.setTitleBar({text: 'Simulating Notify Message Sending'});
            this.$page.setTitleBar({ text: 'Simulating Notify Message Sending', textColor: '#FFFFFF', backgroundOpacity: 0.9 });
        },

        sendNotifyMsg: async function () {
            try {
                var body = {
                    grant_type: 'client_credentials',
                    client_id: '101266687',
                    client_secret: 'd873aa90c3e8792517317e09f24b97df366ee10433b2f1bb3282d6ca6ce3f425'
                }
                const response = await fetch.fetch({
                    url: 'https://oauth-login.cloud.huawei.com/oauth2/v3/token',
                    method: 'POST',
                    data: body
                })
                var result = response.data.data;
                console.info('getAccessTokenV3 success data : ', result)
                this.attoken = JSON.parse(result).access_token;

                console.info('getAccessTokenV3 success attoken: ', this.attoken)
                this.beginSendNotifyMsg();
            } catch (err) {
                console.info('getAccessTokenV3 fail code: ', err.code)
                console.info('getAccessTokenV3 fail data: ', err.data)
            }
        },
        beginSendNotifyMsg: async function () {
            console.log("start sending push msg V3");
            var token = this.$app.$def.dataApp.pushtoken;
            console.log("send push msg app token=" + token);
            let tokenlist = Array.of(token);
            console.log("send push msg token list=" + tokenlist);
            var mData = {
                "pushtype": 0,
                "pushbody": {
                    "title": "How can young people make a living?",
                    "description": "Why did he choose to be a security guard after college graduation?",
                    "page": "/",
                    "params": {
                        "key1": "test1",
                        "key2": "test2"
                    }
                }
            };
            var formatJsonString = JSON.stringify(mData);
            var messbody = {
                "validate_only": false,
                "message": {
                    "data": formatJsonString,
                    "android": {
                        "fast_app_target": 1
                    },
                    "token": tokenlist,
                }
            };
            var access = 'Bearer ' + this.attoken;
            try {
                const response = await fetch.fetch({
                    url: 'https://push-api.cloud.huawei.com/v1/101266687/messages:send',
                    header: { 'Authorization': access, 'Content-Type': 'application/json;charset=utf-8;' },
                    method: 'POST',
                    data: messbody
                });
                console.info('sendPushMsg3 success code: ', response.data.code)
                console.info('sendPushMsg3 success data: ', response.data.data)
                console.info('sendPushMsg3 success headers: ', JSON.stringify(response.data.headers))
            } catch (error) {
                console.info("beginSendNotifyMsg catch error: " + error);
            }

        },

        unregister: function () {
            this.$app.pushunsubscribe();
        },

        getTimeStap: function () {
            const between = Date.now();
            console.log(" getTimeStap between=" + between);
        },

        onShow: function () {
            console.info(" onshow");
        },
        onHide: function () {
            console.info(" onHide");
        },

        onDestroy: function () {
            console.info("ondestroy");
        },
    }
</script>

Links

FAQs

• Can the regId parameter be left empty if I want to push messages to all users?
• What can I do if the token disappears after I enter it in AppGallery Connect to push a message?
• What can I do if a message indicating that the app has been removed or is not in the service area is displayed when I tap the push notification bar of a quick app?
• Messages are pushed more than five times, but the user receives only five of them and the status code received by the return server address is 102. What should I do?
• What should I do if the message "illegal tokens" is displayed when I send a push message?
• Is regId of a quick app globally unique?
• When I call the server API to send a push message to my test device, the message is successfully sent but not received by the device. What do I do?
• What can I do if the push.getProvider API returns an empty response?
• How do I redirect users from a push message to the loader?
• What can I do if the error message "200 request apptoken error" is displayed when the push.subscribe API is used to obtain the value of regId?
• What should I do if "503 Service temporarily unavailable" is returned when the server sends a push message?
• How do I distinguish the test environment from the online environment for a quick app?
• Why does my quick app fail to push messages? Is this because of frequency control?
• Is there any restriction on the account for integrating Push Kit? Can I use an individual developer account for integration?
• Each time the notification is sent, the configured receipt URL will receive a status code. What do these status codes mean?
• How can I obtain the parameters of notifications?

Cases

No Message Is Displayed on the Notification Bar Event If Result Code 80000 Is Returned by a Quick App