推送服务接入指导（HarmonyOS篇）

发布者：HarmonyOS SDK
发布于：2023-06-15 15:41

消息推送作为App运营日常使用的用户促活和召回手段，是与用户建立持续互动和连接的良好方式。推送服务（Push Kit）是华为提供的消息推送平台，建立了从云端到终端的消息推送通道，本文旨在介绍HarmonyOS（Java）版本的功能及接入指导。

 

HarmonyOS（Java）版本主要功能为根据token推送通知栏和透传消息。HarmonyOS Java SDK为您的HarmonyOS应用开发提供推送消息相关的接口，适用于手机和平板。

根据Push Token推送消息

您可以输入目标用户的Push Token来推送消息，一次最多可填1000个Push Token。

透传消息

透传消息是由客户端应用负责处理的消息。终端设备收到Push云端发送的数据或指令后不直接展示，而是将数据传递给应用，由应用解析内容，并触发相关动作（如跳转网页、应用内页面等等）。您可以自定义消息样式，从而更高效灵活地推送消息。

 

透传消息的到达率受Android系统和应用是否驻留在后台影响，推送服务不保证透传消息的高到达率。

 

透传消息的常用场景：VoIP呼叫、语音播报、好友互动通知等。

开发准备

具体开发准备请参考官网。

应用开发

获取Push Token

Token是推送令牌，每个设备上的每个应用的Token都是唯一存在的，客户端调用getToken方法向Push服务端请求应用的Token，您可以根据Push服务端返回的Token向应用推送消息。当getToken方法返回为空时，可通过onNewToken方法获取Token值。

 

建议将Push Token上报到您自己的应用服务器，并定时更新Token列表。您可以调用下行消息API，根据这些Token批量推送消息。

  1. 创建一个新的线程，并调用getToken方法获取Push Token（建议在应用启动后的首个Ability中调用getToken方法）。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
public class TokenAbilitySlice extends AbilitySlice {
    private static final HiLogLabel LABEL_LOG = new HiLogLabel(HiLog.LOG_APP, 0xD001234,
"TokenAbilitySlice");
    private void getToken() {
        // 创建新线程
        new Thread("getToken") {
            @Override
            public void run() {
                try {
                    // 从agconnect-services.json文件中读取client/app_id
                    String appId = "your APP_ID";
                    // 输入token标识"HCM"
                    String tokenScope = "HCM";
                    // 获取Push Token
                    String token = HmsInstanceId.getInstance(getAbility().getAbilityPackage(), TokenAbilitySlice.this).getToken(appId, tokenScope);
                } catch (ApiException e) {
                    // 获取Push Token失败时，打印错误码
                    HiLog.error(LABEL_LOG, "get token failed, the error code is %{public}d", e.getStatusCode());
                }
            }
        }.start();
    }
}
  1. 在您的service（已继承HmsMessageService）中，覆写onNewToken方法，当Token发生变化时以onNewToken方法返回。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
public class DemoHmsMessageServiceAbility extends HmsMessageService {
    private static final HiLogLabel LABEL_LOG = new HiLogLabel(HiLog.LOG_APP, 0xD001234, "DemoHmsMessageServiceAbility");
 
    @Override
    // 获取Token
    public void onNewToken(String token) {
        HiLog.info(LABEL_LOG, "onNewToken called, token:%{public}s", token);
    }
 
    @Override
    // 获取Token失败，打印错误码
    public void onTokenError(Exception exception) {
        HiLog.error(LABEL_LOG, "get onNewtoken error, error code is %{public}d", ((ZBaseException)exception).getErrorCode());
    }
}

获取透传消息数据

在您的service（已继承HmsMessageService）中，覆写onMessageReceived方法，只要您发送透传消息至终端设备，都会获得透传消息的内容。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
public class DemoHmsMessageServiceAbility extends HmsMessageService {
    private static final HiLogLabel LABEL_LOG = new HiLogLabel(HiLog.LOG_APP, 0xD001234,
"DemoHmsMessageServiceAbility");
    @Override
    public void onMessageReceived(ZRemoteMessage message) {
        // 打印消息的内容字段
        HiLog.info(LABEL_LOG, "get token, %{public}s", message.getToken());
        HiLog.info(LABEL_LOG, "get data, %{public}s", message.getData());
 
        ZRemoteMessage.Notification notification = message.getNotification();
        if (notification != null) {
            HiLog.info(LABEL_LOG, "get title, %{public}s", notification.getTitle());
            HiLog.info(LABEL_LOG, "get body, %{public}s", notification.getBody());
        }
    }
}

发送消息

• 您可以登录AppGallery Connect网站发送消息，详情请参见HarmonyOS应用推送消息。

 

• 您可以使用服务端API向应用推送消息：

  1. 您的服务器调用华为帐号服务器的接口（2e0K9s2c8@1M7s2y4Q4x3@1q4Q4x3V1k6Q4x3V1k6G2j5i4g2@1K9q4)9J5k6r3I4G2k6$3W2F1i4K6u0W2j5$3I4G2N6h3c8Q4x3X3g2Z5N6h3q4%4k6h3W2Q4x3X3g2U0L8$3#2Q4x3V1k6G2j5i4g2@1K9o6u0Q4x3V1k6$3x3#2)9J5c8Y4c8G2K9$3g2F1i4@1g2r3i4@1u0o6i4K6R3&6i4@1f1^5i4@1q4r3i4@1t1%4i4@1f1$3i4@1t1I4i4K6R3J5i4@1f1#2i4K6R3%4i4@1q4p5i4@1f1^5i4@1q4r3i4K6R3I4g2r3!0C8k6h3&6Q4c8e0y4Q4z5o6m8Q4z5o6u0Q4c8e0S2Q4b7f1k6Q4b7U0N6Q4c8e0k6Q4b7U0q4Q4z5o6u0Q4c8e0N6Q4b7e0c8Q4b7V1q4Q4c8e0c8Q4b7V1g2Q4z5p5u0Q4c8e0g2Q4b7e0k6Q4z5o6u0Q4c8e0c8Q4b7U0S2Q4z5p5u0Q4c8f1k6Q4b7V1y4Q4z5f1p5`.
1
2
3
4
5
POST /oauth2/v3/token HTTP/1.1
Host: oauth-login.cloud.huawei.com
Content-Type: application/x-www-form-urlencoded
 
grant_type=client_credentials&client_id=<客户端ID>&client_secret=<客户端密钥>

响应示例如下：

1
2
3
4
5
6
7
8
9
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
 
{
    "access_token": "<返回的Access Token>",
    "expires_in": 3600,
    "token_type": "Bearer"
}
  1. 您的服务端调用API推送消息，请求示例如下。

HTTPS POST URL：

1
POST https://push-api.cloud.huawei.com/v1/clientid/messages:send

请求消息头示例：

1
2
Content-Type: application/json; charset=UTF-8
Authorization: Bearer CF3Xl2XV6jMK************************DgAPuzvNm3WccUIaDg==

请求消息体（通知栏消息）示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "validate_only": false,
    "message": {
        "android": {
            "notification": {
                "title": "test title",
                "body": "test body",
                "click_action": {
                    "type": 3
                }
            }
        },
        "token": ["pushtoken1"]
    }
}

自定义点击消息动作

您可以自定义点击通知栏消息的动作，例如：打开应用首页、打开网页URL和打开应用自定义页面。

打开App首页

• 您可以通过AppGallery Connect推送消息，设置点击通知动作为打开应用、App页面为首页。

 

• 您可以通过服务端API推送消息：

 

消息体中携带click_action字段，type取值为3表示点击消息后打开应用首页。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "validate_only": false,
    "message": {
        "android": {
            "notification": {
                "title": "test title",
                "body": "test body",
                "click_action": {
                    "type": 3
                }
            }
        },
        "token": ["pushtoken1"]
    }
}

打开网页

• 您可以通过AppGallery Connect推送消息，设置点击通知动作为打开网页。

 

• 您可以通过服务端API推送消息：

 

消息体中携带click_action字段，type取值为2表示点击消息后打开网页。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "validate_only": false,
    "message": {
        "android": {
            "notification": {
                "title": "test title",
                "body": "test body",
                "click_action": {
                    "type": 2,
                    "url":"c64K9s2c8@1M7s2y4Q4x3@1q4Q4x3V1k6Q4x3V1k6%4N6%4N6Q4x3X3g2Z5N6h3q4%4k6h3W2Q4x3X3g2U0L8$3@1`."
                }
            }
        },
        "token": ["pushtoken1"]
    }
}

打开应用自定义页面

  1. 客户端应用先创建自定义页面（以“MyActionAbility”为例），在您项目的“entry/src/main”目录下的“config.json”文件中添加该Ability的skills字段。其中entities的值为“entity.system.default”不可改变，actions的值由您自定义（以“com.test.myaction”为例）。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "orientation": "unspecified",
    "name": "com.test.java.MyActionAbility",
    "icon": "$media:icon",
    "description": "$string:myactionability_description",
    "label": "$string:entry_MyActionAbility",
    "type": "page",
    "launchType": "standard",
    "skills": [   
        {
            "entities": ["entity.system.default"],
            "actions": ["com.test.myaction"]   
        }
    ]
}
  1. 您可以通过AppGallery Connect推送消息，设置点击通知动作为打开应用、App页面为自定义action页面（action请输入上一步中定义的actions的值）。

您也可以通过服务端API推送消息。消息体中携带click_action和action字段，type取值为1表示点击消息后打开应用自定义页面，action取值为上一步中定义的actions的值。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "validate_only": false,
    "message": {
        "android": {
            "notification": {
                "title": "test title",
                "body": "test body",
                "click_action": {
                    "type": 1,
                    "action":"com.test.myaction"
                }
            }
        },
        "token": ["pushtoken1"]
    }
}

传递数据

您推送消息时可携带data字段，当用户点击消息时通过下述方法将data中的数据传递至客户端应用。

  1. 推送消息时携带data字段：

• 通过AppGallery Connect推送消息且设置自定义键值对。

 

• 通过服务端API推送消息，消息体中携带data字段。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "validate_only": false,
    "message": {
        "android": {
            "notification": {
                "title": "test title",
                "body": "test body",
                "click_action": {
                    "type": 1,
                    "action":"com.test.myaction"
                }
            },
            "data": "{'key_data':'value_data'}"
        },
        "token": ["pushtoken1"]
    }
}
  1. 在客户端应用开发点击消息跳转的页面获取data字段的功能，此处以点击消息跳转到应用首页（MainAbilitySlice）获取data字段为例。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
public class MainAbilitySlice extends AbilitySlice {
    private static final HiLogLabel LABEL_LOG = new HiLogLabel(HiLog.LOG_APP, 0xD001234, "myDemo");
    @Override   
    public void onStart(Intent intent) {       
        HiLog.info(LABEL_LOG, "MainAbilitySlice get started...");
        super.onStart(intent);
        super.setUIContent(ResourceTable.Layout_ability_main);
        // 调用解析方法
        parseIntent(intent);
    }
 
    private void parseIntent(Intent intent){
        if (intent == null){return;}   
        IntentParams intentParams = intent.getParams();
        if (intentParams == null) {return;}
        // 获取data字段中的键值对  
        String key = "key_data";   
        Object obj = intentParams.getParam(key);
        try{
            // 打印data字段中的键值对       
            HiLog.info(LABEL_LOG, "my key: %{public}s, my value: %{public}s", key, obj);   
        }catch (Exception e){
            HiLog.info(LABEL_LOG, "catch exception : " + e.getMessage());   
        }
    }
}

了解更多详情>>

 

访问华为推送服务联盟官网

 

获取华为推送服务开发指导文档

 

访问HMS Core 联盟官网

 

获取HMS Core 开发指导文档

 

关注我们，第一时间了解 HMS Core 最新技术资讯~

技术 开发技巧 工具脚本 合作伙伴 累积更新
声明：该文观点仅代表作者本人，转载请注明来自看雪