目录

应用开发

获取Push Token

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

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

  1. 创建一个新的线程,并调用getToken方法获取Push Token(建议在应用启动后的首个Ability中调用getToken方法)。

    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_id”
                        String appId = "your client_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();
        }
    }

  2. 在您的service(已继承HmsMessageService)中,覆写onNewToken方法,当Token发生变化时以onNewToken方法返回。

    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, get 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方法,只要您发送透传消息至终端设备,都会获得透传消息的内容。

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 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());
        }
    }
}

发送消息

  1. 您可以通过OAuth 2.0开放鉴权(客户端模式)或者基于服务账号生成鉴权令牌(JSON Web Token)方式获取鉴权信息。

    • 使用OAuth 2.0开放鉴权(客户端模式)方式时,客户端ID和客户端密钥请输入您在AppGallery Connect项目下的HarmonyOS应用里的OAuth 2.0客户端ID(凭据)中的Client ID和Client Secret;获取的 Access Token 在有效期(expires_in)内可以多次使用,请勿过于频繁请求,否则可能会被流控(当前应用级Access Token的流控阈值为1000个/5分钟,5分钟内申请Access Token超过1000个,后续将提示被流控,无法申请。5分钟后重置,可以再次申请)。
    • 使用基于服务账号生成的鉴权令牌(JSON Web Token)有效期不要超过1小时,有效期内可以多次使用。
    • 其他错误码请参见错误与异常机制。

  2. 您的服务端调用API推送消息,请求示例如下。

    HTTPS POST URL:

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

    URL中的“[clientid]”为您在AppGallery Connect项目下的HarmonyOS应用里的OAuth 2.0客户端ID(凭据)中的Client ID。

    调用API推送消息时,接口URL版本为V1(https://push-api.cloud.huawei.com/v1/[clientid]/messages:send)和V2(https://push-api.cloud.huawei.com/v2/[projectid]/messages:send)时,仅支持给HarmonyOS 3.x/4.x的系统版本推送通知。如果您想给HarmonyOS Next/5.x及之后的系统版本推送通知,请使用V3 版本URL(https://push-api.cloud.huawei.com/v3/[projectId]/messages:send)。

    请求消息头示例:

    Content-Type: application/json; charset=UTF-8
    Authorization: Bearer CF3Xl2XV6jMK************************DgAPuzvNm3WccUIaDg== 
    请求消息体(通知栏消息)示例:
    {
        "validate_only": false,
        "message": {
            "android": {
                "notification": {
                    "title": "test title",
                    "body": "test body",
                    "click_action": {
                        "type": 3
                    }
                }
            },
            "token": ["pushtoken1"]
        }
    }

    请求消息体中的token值为推送服务Token,更多消息体内容请参见下行消息参数。

自定义点击消息动作

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

[h2]打开App首页

[h2]打开网页

[h2]打开应用自定义页面

配置action参数打开应用自定义页面:

  1. 客户端应用先创建自定义页面(以“MyActionAbility”为例),在您项目的“entry/src/main”目录下的“config.json”文件中添加该Ability的skills字段。其中entities的值为“entity.system.default”不可改变,actions的值由您自定义(以“com.test.myaction”为例)。

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

  2. 您可以通过AppGallery Connect推送消息,设置点击通知动作为打开应用、App页面为自定义action页面(action请输入上一步中定义的actions的值)。

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

    {
        "validate_only": false,
        "message": {
            "android": {
                "notification": {
                    "title": "test title",
                    "body": "test body",
                    "click_action": {
                        "type": 1,
                        "action":"com.test.myaction"
                    }
                }
            },
            "token": ["pushtoken1"]
        }
    }

配置uris参数打开应用自定义页面:

  1. 客户端应用先创建自定义页面(以“MyActionAbility”为例),在您项目的“entry/src/main”目录下的“config.json”文件中添加该Ability的skills字段。其中uris的值由您自定义。

    {
        "orientation": "unspecified",
        "name": "com.test.java.MyActionAbility",
        "icon": "$media:icon",
        "description": "$string:myactionability_description",
        "label": "$string:entry_MyActionAbility",
        "type": "page",
        "launchType": "standard",
        "skills": [    
            {
                "uris": [
                    {
                        "scheme": "pushscheme",
                        "host": "pushscheme.host",
                        "path": "/deeplink"
                    }
                ] 
            } 
        ]
    }

  2. 您可以通过AppGallery Connect推送消息,设置点击通知动作为打开应用、App页面为自定义intent页面(请输入上一步中定义的uris的值,格式为intent://定义的host定义的path?#Intent;scheme=定义的scheme;end,详细示例:intent://pushscheme.host/deeplink?#Intent;scheme=pushscheme;end)。

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

    {
        "validate_only": false,
        "message": {
            "android": {
                "notification": {
                    "title": "test title",
                    "body": "test body",
                    "click_action": {
                        "type": 1,
                        "intent":"intent://pushscheme.host/deeplink?#Intent;scheme=pushscheme;end"
                    }
                }
            },
            "token": ["pushtoken1"]
        }
    }

[h2]传递数据

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

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

    • 通过AppGallery Connect推送消息且设置自定义键值对。
    • 通过服务端API推送消息,消息体中携带data字段。
      {
          "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"]
          }
      }

  2. 在客户端应用开发点击消息跳转的页面获取data字段的功能,此处以点击消息跳转到应用首页(MainAbilitySlice)获取data字段为例。

    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());    
            }
        }
    }