目录

消息回执

场景介绍

消息回执是指推送服务端将消息推送到用户终端之后,Push端侧会给Push服务端反馈送达结果,与此同时,Push服务端会将消息送达状态以回执消息形式发送给您的应用回执服务端。

受网络环境以及消息量的影响,消息回执在Push服务端收到端侧响应后发送会存在一些延迟现象。

目前消息回执功能暂不支持iOS应用。

您可以基于接收到的消息回执码进行数据统计和分析,回执状态码如下表所示:

回执状态码

状态码描述

原因及处理

0

成功送达

不涉及。

2

应用未安装

成功发送到设备后发现应用不存在,通常表示应用已卸载。

5

指定的Token在当前Android终端用户下不存在

  • Android终端收到App的Push消息,但Push消息带的Token与本地App的Token不一致。请排查以下几种原因:
    • 终端用户清除了本地App数据。
    • 终端用户通过卸载再安装的方式更新了本地App。
    • 您在App中调用Push SDK的deleteToken方法删除了本地App的Token。
    • 终端设备恢复出厂设置后终端用户重新进入预安装App或者重新安装并进入App。
  • Android终端收到App的Push消息,但检查本地数据存储中并没有App的Token。请排查以下两种原因:
    • App未激活。
    • 终端用户创建过子用户,后又将子用户删除。

6

通知栏消息不展示

请排查以下三种原因:

  • 您在应用中调用Push SDK的turnOffPush方法设置了不显示通知栏消息。
  • 用户关闭了本应用的系统通知栏总开关。
  • 用户关闭了本应用的通知栏渠道开关。

10

非活跃设备

设备为非活跃设备(终端设备未接入网络达30天),消息不进行下发。

14

其它错误

系统内部网络异常。

15

离线用户消息管控

  1. 设置了离线用户消息覆盖(服务端API中的collapse_key)功能,消息被覆盖掉了,未下发到设备。
  2. 离线消息最多缓存120条,超过后旧消息被新消息覆盖。

22

userID不匹配

多用户场景,下发消息中的userID与当前实际用户不匹配。

27

在终端设备上目标应用进程不存在导致透传消息被缓存

目标应用进程不存在且应用启动管理关闭自启动和关联启动的情况下,透传消息将被缓存。

31

系统版本或应用不支持该消息

  1. 请确认目标应用是否支持该消息。如下几种情况不支持该消息:
    • 目标应用中不存在Intent中指向的页面。
    • 目标应用中的activity有权限保护。
    • 推送服务版本低于11.1.2.300且目标应用中的activity设置了exported为false。
  2. 尝试升级推送服务(EMUI 9.1.0以下不支持升级)。

51

终端设备处于开机未解锁状态

用户重启终端设备后,点亮屏幕未解锁。

102

消息频控丢弃

每天向某个设备上某个应用最多可发送3000条消息,超过3000条后当天无法向该设备的该应用继续发送消息,请超过零点后再发送消息。

144

profileId不存在

发送下行消息时请检查profile_id字段。

201

消息发送管控

消息被Push服务端管控不下发,建议做过滤处理减少无效推送。可能的原因:

  • 消息中指定的Token与设备当前登录的用户无法匹配。
  • 用户关闭了显示通知栏消息。
  • 应用被卸载。
    说明:

    您可以根据subStatus字段来确定消息是由于何种原因被管控。

256

资讯营销类消息频次限制

可能的原因:

  • 您当日的发送量超出资讯营销类消息的限制,请您调整发送策略。
  • 违反通知消息管理规则,被停止发送资讯营销类消息,或所有消息被归类为资讯营销类消息。

您需要对上述状态中的2、5、6、10、201做过滤处理,减少对这些用户的无效推送。

开发准备

[h2]开通回执权益

  1. 登录AppGallery Connect网站。
  2. 点击“开发与服务”,在项目列表中找到您的项目,通过“增长 > 推送服务 > 配置”导航到“配置”页签。
  3. 在该页面可以选择配置项目级回执或者应用级回执,需要注意的是项目级回执消息接收URL地址,对该项目下所有应用生效。如果您同时配置了项目级回执和应用级回执地址,则优先获取应用级回执地址信息。

  4. 这里以应用级回执举例,选择需要配置回执的应用,点击“开通”应用回执状态。

  5. 进入回执参数配置,可以选择已有回执或者新建回执。

[h2]回执参数配置

点击“新建回执”后,需要配置如下参数。

  1. 配置消息回执的名称和回调地址。

    回调地址配置完成后,华为Push服务器会校验回执服务器(接收回执消息的应用服务器)提供的证书是否为商用CA签发证书。

    • 商用CA提示:

    • 自签CA提示:

    证书过期将导致您无法接收消息回执,请及时更换回执服务器证书。

  2. 配置回调用户名(可选,下边描述为username)和回调密钥(可选,下边描述为secret)进行身份验证。
    1. 从回执消息的请求Header中获取X-HUAWEI-CALLBACK-ID,举例如下:
      X-HUAWEI-CALLBACK-ID: timestamp=902934;nonce=32312324;value=E4YeO*********************QXF+c=

      其中timestamp为回执消息的时间戳(标准Unix时间戳),nonce为UUID随机数,value为签名信息,签名方法为:Base64(HMAC-SHA256(secret, timestamp+nonce+username))。

    2. 您可以根据timestamp、nonce、username、secret参考示例生成签名,与value的值比较进行签名验证。

      生成签名示例:

      “Java”
      StringBuilder buf = new StringBuilder();
      buf.append(timestamp);
      buf.append(nonce);
      // 在回执配置中的回调用户名
      buf.append(userName);
      // 在回执配置中的回调密钥
      String secret = "your secret";
      String signature = "";
      try {
          Mac mac = Mac.getInstance("HmacSHA256");
          // 老旧版本的回执配置密钥使用secret.getBytes(UTF_8),新的回执配置密钥使用base64编码
          SecretKeySpec key = new SecretKeySpec(Base64.getDecoder().decode(secret), "HmacSHA256");
          mac.init(key);
          byte[] encodeV = mac.doFinal(buf.toString().getBytes(UTF_8)); 
          signature = Base64.getEncoder().encodeToString(encodeV);
      } catch (NoSuchAlgorithmException | InvalidKeyException e) { 
          System.out.println("generate signature catch exception" + e);
      }
  3. 配置回执支持版本

    回执可配置V1或者V2版本,V1版本回执仅支持下行消息接口,V2版本回执支持所有当前和后续版本新增的接口,建议您配置V2版本。

    若您是新建回执,默认勾选V2版本,若您是修改回执信息,之前创建的回执都会被分为V1版本,建议您及时修改为V2版本,以支持后续新增的接口。

    配置回执版本后,由于V1版本和V2版本的回执消息体结构不同,请参见消息回执API适配您的回执服务器代码。

  4. “测试回执”可以对回执地址进行功能测试,点击“提交”完成回执的创建。
  • 目前华为Push服务器和接收回执消息的应用服务器之间走的是HTTPS协议,华为Push服务器会校验应用服务器提供证书的合法性,推荐应用服务器使用正式商用的HTTPS证书。
  • 如果您的回执配置正确,点击“测试回执”后,您的回执服务器将收到由华为Push服务器发送的测试消息,同一回执版本该消息内容固定,仅供测试使用。
    “V1版本”
    {
        "statuses": [
            {
                "biTag": "1000211_test211",
                "clientId": "1000211",
                "token": "MsDZmCSyuS+GdonWcxC*********0013000001",
                "status": 0,
                "timestamp": 1514274013185,
                "requestId": "153362******071023"
            }
        ]
    }
    “V2版本”
    {
        "statuses":[
            {
                "appPackage":"com.****.package",
                "biTag":"a bi tag",
                "requestId":"167783171******4001301",
                "deliveryStatus":{
                    "result":0,
                    "timestamp":1607832761768
                },
                "token":"MsDZmCSyuS+Gd***********ZLs8Es0000000013000001"
            }
        ]
    }

    您的回执服务器必须返回成功的响应,才能测试通过,再点击“提交”完成回执的创建。

    {
        "code": "0",
        "message": "success"
    }

开发指导

您调用下行消息API进行消息推送时,可以设置bi_tag。消息回执时,您设置的bi_tag值会返回给您,您可通过该字段对消息的送达情况进行统计分析。

消息体示例:

{
    "validate_only": false,
    "message": {
        "notification": {
            "title": "message title",
            "body": "message body"
        },
        "android": {
            "bi_tag": "your bi_tag",
            "notification": {
                "click_action": {
                    "type": 3
                }
            }
        },
        "token": ["pushtoken1"]
    }
}