目录

1. 自定义通知渠道

通知渠道(channel)是Android O版本引入的新功能,意在解决如下问题:

1、应用的通知越来越多,给用户造成明显打扰。

2、华为手机系统EMUI 10.0之前仅有一个默认通知渠道,无法做通知消息呈现方式的定制。

华为手机系统从EMUI 10.0开始新增了三个通知渠道(服务提醒,普通通知与营销通知)来实现不同级别(非常重要,重要与一般)的通知消息展示。我们也支持自定义通知渠道的消息展示功能,如何创建自定义渠道安卓官方文档已有非常详细的描述,这里不再赘述。应用想在自定义渠道上展示消息,只需要通过服务端消息请求报文中message.android.notification.channel_id字段设置要使用的渠道标识即可。消息最终能否展示在应用渠道上,受用户终端上该渠道是否创建以及渠道的开关策略控制。

注意:

自定义通知渠道仅对发给用户设备的通知消息级别为重要与非常重要时有效,一般级别消息仍然通过华为营销通知渠道展示。

示例报文:

  1. {
  2.    "message": {
  3.        "notification": {
  4.            "title": "message title",
  5.            "body": "message body"
  6.        },
  7.        "android": {
  8.            "notification": {
  9.                "channel_id": "RingRing",
  10.                "click_action": {
  11.                    "type": 2,
  12.                    "url": "https://example.com"
  13.                }
  14.            }
  15.        },
  16.        "token": [
  17.            "pushtoken1"
  18.        ]
  19.    }
  20. }

2. 通知消息本地化

通知消息本地化又可以理解为国际化多语言展示,指通知消息可以根据手机本地语言变化展示对应语言的标题和内容,从而覆盖本消息中普通的标题和内容。

通知消息多语言展示效果图如下:

通知消息本地化展示可以由华为统一消息中心(NC)展示,也可以由开发者通过服务端提供的REST API接口设置为应用在前台时由应用自己处理。下面我们分别介绍下这两种处理方式下开发者要做的事情。

2.1 华为NC展示

华为NC展示有两种方式实现,方式1是全部通过服务端提供的REST API接口实现,不需要应用本地的字符串资源文件strings.xml的配合;方式2需要服务端REST API配置(不需要配置multi_lang_key字段)与应用本地的字符串资源文件配合实现。

说明:如果同时指定了multi_lang_key字段与本地字符串资源文件,则优先使用multi_lang_key字段,本字段读取失败,则从APK本地资源文件中读取。

方式1

  1. {
  2.    "title_loc_key": "title_key",
  3.    "body_loc_key": "body_key",
  4.    "body_loc_args": [
  5.        "Jack",
  6.        "Shanghai"
  7.    ],
  8.    "multi_lang_key": {
  9.        "title_key": {
  10.            "en": "New Friend Request",
  11.            "zh": "添加好友请求",
  12.            "ru": "Запрос нового друга"
  13.        },
  14.        "body_key": {
  15.            "en": "My name is %s, I am from %s.",
  16.            "zh": "我叫%s,来自%s。",
  17.            "ru": "Меня зовут %s, я из %s."
  18.        }
  19.    }
  20. }

注意:
名称为multi_lang_key的字段的值是一个对象,对象的名称必须与title_loc_key、body_loc_key字段的值一致。上文JSON文本举例来说,body_key字段的值也是一个对象,对象中适配国际化多语言,目前最多支持三种适配语言。en字段的值是一个格式化字符串,%s代表这是字符串类型。body_loc_args字段的值是一个可变的字符串数组,用于填充en字段的值中对应的占位符%s,您可以根据自己的业务进行设置。

方式2

  1. "title_loc_key": "title_key",
  2. "body_loc_key": "body_key",
  3. "body_loc_args": ["Jack", "Shanghai"]

  1. <string name="title_key">New Friend Request</string>
  2. <string name="body_key">My name is %1$s, I am from %2$s.</string>

说明:
开发者可以在res目录下进行多语言适配,比如/res/values-en-rGB/strings.xml进行英语(英国)本地化适配。

  1. public class DemoHmsMessageService extends HmsMessageService {
  2.    @Override
  3.    public void onMessageReceived(RemoteMessage message) {
  4.        String[] bodyArrays = message.getNotification().getBodyLocalizationArgs();
  5.        String key = getResources().getString(R.string.body_key);
  6.        String body = String.format(key, bodyArrays[0], bodyArrays[1]);
  7.        Log.i(TAG, body);
  8.    }
  9. }
注意:
title_loc_key字段的值要与本地strings.xml里面定义的节点名要一致,title_loc_args中可变字符串值用于替换strings.xml中格式说明符,因此可变数组的长度要保证不小于strings.xml中对应的节点中占位符的个数。

2.2 应用处理

由于Push SDK中没有提供获取服务端REST API设置的multi_lang_key字段值方法,因此要完成应用自展示功能,开发者必须配置应用的本地字符串资源文件strings.xml,请参考华为NC展示中方式2部分。

3. 通知消息前台展示

当您在服务端推送通知消息时,通过服务端提供的开放接口设置了如果应用进程在前台则不通过华为的统一消息中心(Notification Center, 简称NC)展示消息,那么应用在前台时这个通知消息是直接透传给应用,由应用自己处理展示。您可以通过设置 message.android.notification.foreground_show 字段来表示消息由谁来展示。

注意:
该功能仅在EMUI 9.1.0以上,HMS SDK 4.0以上支持。

示例报文:

  1. {
  2.    "message": {
  3.        "notification": {
  4.            "title": "message title",
  5.            "body": "message body"
  6.        },
  7.        "android": {
  8.            "notification": {
  9.                "foreground_show": false,
  10.                "click_action": {
  11.                    "type": 1,
  12.                    "action": "com.huawei.codelabpush.intent.action.test"
  13.                }
  14.            }
  15.        },
  16.        "token": [
  17.            "pushtoken1"
  18.        ]
  19.    }
  20. }

字段值说明:值为true或者不填写值,表示应用在前台时仍旧由NC展示通知消息。如果填写false,表示应用在前台时不再由NC展示通知消息,通知消息的全部内容将会通过HmsMessageService的onMessageReceived(RemoteMessage message)方法传递给应用,应用需要通过RemoteMessage提供的方法获取相应字段,自行处理,这种情况下,华为推送服务不会校验消息字段的合法性。

4. 通知消息展示覆盖

通知消息到达终端设备展示后,如果用户没有点击或者清理,支持新来的消息覆盖掉之前展示的消息。本功能可以通过服务端提供的API来设置实现。有三种方式,1、通过tag字段(值为字符串)设置,2、通过notify_id字段(值为整数)设置,3、通过group字段(值为字符串)设置。

tag字段示例报文:

  1. {
  2.    "message": {
  3.        "notification": {
  4.            "title": "message title",
  5.            "body": "message body"
  6.        },
  7.        "android": {
  8.            "notification": {
  9.                "tag": "tagBoom",
  10.                "click_action": {
  11.                    "type": 2,
  12.                    "url": "https://example.com"
  13.                }
  14.            }
  15.        },
  16.        "token": [
  17.            "pushtoken1"
  18.        ]
  19.    }
  20. }

具有相同tag标签值的新消息覆盖老的消息。

notify_id字段示例报文:

  1. {
  2.    "message": {
  3.        "notification": {
  4.            "title": "message title",
  5.            "body": "message body"
  6.        },
  7.        "android": {
  8.            "notification": {
  9.                "notify_id": 123,
  10.                "click_action": {
  11.                    "type": 2,
  12.                    "url": "https://example.com"
  13.                }
  14.            }
  15.        },
  16.        "token": [
  17.            "pushtoken1"
  18.        ]
  19.    }
  20. }

notify_id标识每条消息在通知显示时的唯一标识。不同的通知栏消息可以相同的notify_id,实现新的通知栏消息覆盖老的。

group字段示例报文:

  1. {
  2.    "message": {
  3.        "notification": {
  4.            "title": "message title",
  5.            "body": "message body"
  6.        },
  7.        "android": {
  8.            "notification": {
  9.                "group": "espace",
  10.                "click_action": {
  11.                    "type": 2,
  12.                    "url": "https://example.com"
  13.                }
  14.            }
  15.        },
  16.        "token": [
  17.            "pushtoken1"
  18.        ]
  19.    }
  20. }

相同group的多条消息,只展示最新的一条消息。

注意:

指定tag,指定notify_id,指定group三个功能是互斥的,只能三选一。如果都设置,优先级是:group>tag>notify_id。

5. 基于条件的消息推送

支持基于主题组合条件发送,即指定目标主题的布尔表达式来进行消息推送。比如向订阅了weather和sports主题的用户推送消息。目前只有安卓应用可以使用条件推送,condition字段详细说明请参考服务端发送Push消息。

示例报文:

  1. {
  2.    "validate_only": false,
  3.    "message": {
  4.        "notification": {
  5.            "title": "message title",
  6.            "body": " message body"
  7.        },
  8.        "android": {
  9.            "notification": {
  10.                "click_action": {
  11.                    "type": 1,
  12.                    "action": "com.huawei.codelabpush.intent.action.test"
  13.                }
  14.            }
  15.        },
  16.        "condition": "'weather' in topics && 'sports' in topics"
  17.    }
  18. }

6. 离线用户消息覆盖

开发者如果想控制服务端向离线用户推送消息的覆盖策略,可以使用分类标识功能。通过服务端API中的collapse_key字段来进行控制。collapse_key字段详细说明请参考服务端发送Push消息。

示例报文:

  1. {
  2.    "validate_only": false,
  3.    "message": {
  4.        "notification": {
  5.            "title": "message title",
  6.            "body": "message body"
  7.        },
  8.        "android": {
  9.            "collapse_key": 0,
  10.            "notification": {
  11.                "click_action": {
  12.                    "type": 2,
  13.                    "url": "https://example.com"
  14.                }
  15.            }
  16.        },
  17.        "token": [
  18.            "pushtoken1"
  19.        ]
  20.    }
  21. }

7. 离线用户消息缓存时间

开发者如果想控制服务端向离线用户推送消息的缓存策略,可以通过服务端API提供的ttl字段来控制。ttl字段详细说明请参考服务端发送Push消息。

示例报文:

  1. {
  2.    "validate_only": false,
  3.    "message": {
  4.        "notification": {
  5.            "title": "message title ",
  6.            "body": "message body"
  7.        },
  8.        "android": {
  9.            "notification": {
  10.                "click_action": {
  11.                    "type": 2,
  12.                    "url": "https://example.com"
  13.                }
  14.            },
  15.            "ttl": "1000"
  16.        },
  17.        "token": [
  18.            "pushtoken1"
  19.        ]
  20.    }
  21. }

8. 大文本样式

默认样式下仅支持单行文本,单行文本支持的字数太少,会有表达不全的缺陷。大文本样式支持标题单行,内容文字多行(当前EMUI系统限制最多显示10行中文或者11行英文),供消息标题和消息内容过长时使用。大文本展开后效果如下:


示例报文:

  1. {
  2.    "validate_only": false,
  3.    "message": {
  4.        "android": {
  5.            "notification": {
  6.                "title": "message title",
  7.                "body": " message body",
  8.                "click_action": {
  9.                    "type": 1,
  10.                    "intent": "#Intent;compo=com.rvr/.Activity;S.W=U;end"
  11.                },
  12.                "style": 1,
  13.                "big_title": "the big title",
  14.                "big_body": "the big body"
  15.            }
  16.        },
  17.        "token": [
  18.            "pushtoken1"
  19.        ]
  20.    }
  21. }
注意:
大文本展开之前显示的标题与内容取自title与body字段,非big_title与big_body字段的内容。

9. 锁屏不展示通知内容

锁屏下不展示通知消息内容是指当手机处于锁屏状态下收到通知消息后不在锁屏界面上展示通知内容,可以通过服务端发送Push消息API提供的visibility字段实现。visibility字段值说明:

注意:
全局“隐藏通知内容”仅对visibility字段值为PRIVATE起作用。

样例报文:

  1. {
  2.    "message": {
  3.        "notification": {
  4.            "title": "message title",
  5.            "body": "message body"
  6.        },
  7.        "android": {
  8.            "notification": {
  9.                "visibility": "PRIVATE",
  10.                "click_action": {
  11.                    "type": 2,
  12.                    "url": "https://example.com"
  13.                }
  14.            }
  15.        },
  16.        "token": [
  17.            "pushtoken1"
  18.        ]
  19.    }
  20. }

10. 桌面角标

华为推送服务提供了在服务端设置桌面角标的API接口,开发者可以在消息中封装角标参数。如果消息为通知栏消息,华为推送服务负责应用桌面角标数量的展示。如果消息为透传消息,开发者可以调用 getBadgeNumber() 方法获取消息中的角标数字并展示角标数字值。

服务端设置角标样例报文:

  1. {
  2.    "validate_only": false,
  3.    "message": {
  4.        "notification": {
  5.            "title": "message title ",
  6.            "body": "message body"
  7.        },
  8.        "android": {
  9.            "notification": {
  10.                "click_action": {
  11.                    "type": 2,
  12.                    "url": "https://example.com"
  13.                },
  14.                "badge": {
  15.                    "add_num": 1,
  16.                    "class": "com.huawei.codelabpush.MainActivity",
  17.                    "set_num": 10
  18.                }
  19.            },
  20.            "ttl": "1000"
  21.        },
  22.        "token": [
  23.            "pushtoken1"
  24.        ]
  25.    }
  26. }

客户端角标开发请参考:华为桌面角标开发指导书

注意:

1. 打开应用或者点击、清理通知栏消息并不会清理角标数,需应用在端侧参考角标开发指导去清理角标。

2. 如果同时设置add_num与set_num,以set_num为准。

11. 自定义通知小图标

华为推送服务给开发者提供了两种设置通知栏消息小图标的方法,一种是通过服务端发送Push消息API中的icon字段设置,一种是通过应用的AndroidManifest.xml文件添加meta-data元数据来实现。添加meta-data方式如下:

在application标签添加<meta-data>元数据,meta-data元数据name不可改变,resource指定的资源图标由开发者指定,需要在应用的res/drawable目录下。

  1. <application
  2.    <meta-data
  3.        android:name="com.huawei.messaging.default_notification_icon"
  4.        android:resource="@drawable/ic_push_notification" />
  5. </application>
注意:
1. 应用存储的图标文件需要有扩展名(目前支持的文件格式为png、jpg。),但是不要把扩展名写在uri中。

2. 如果应用两种方式同时设置,优先取消息中的icon资源图标展示。如果两个都不设置,默认读取应用的桌面图标展示。

12. Inbox样式

不同于大文本样式,Inbox样式除了支持多行文本外可以做到通知消息内容有序展示(序号不会自动生成),如下图所示,文本内容最多可展示5行,每行内容展示不了时后边自动添加...。

样例报文:

  1. {
  2.    "validate_only": false,
  3.    "message": {
  4.        "android": {
  5.            "notification": {
  6.                "title": "message title",
  7.                "body": " message body",
  8.                "click_action": {
  9.                    "type": 1,
  10.                    "intent": "#Intent;compo=com.rvr/.Activity;S.W=U;end"
  11.                },
  12.                "style": 3,
  13.                "big_title": "HMS SDK 4.0.0 Feature Description",
  14.                "inbox_content": [
  15.                    "1. Added the function of displaying notification messages on the UI.",
  16.                    "2. Added the automatic initialization capability.",
  17.                    "3. Added the function of sending messages to web apps through the WebPush agent.",
  18.                    "4. Added the function of sending messages to web apps through the WebPush agent.",
  19.                    "5. Expanded the application scope of the some functions."
  20.                ]
  21.            }
  22.        },
  23.        "token": [
  24.            "pushtoken1"
  25.        ]
  26.    }
  27. }
说明:
当使用Inbox样式时,inbox_content数组大小应至少为2,既保证有两条内容,否则建议采用大文本样式。

13. 通知消息按钮

支持通知栏消息上添加按钮,点击按钮可以触发相应的动作,目前支持动作类型可以参考服务端API中Button结构体的定义。具体展示效果如下:

对应的示例报文:

  1. {
  2.    "validate_only": false,
  3.    "message": {
  4.        "android": {
  5.            "notification": {
  6.                "title": "message title",
  7.                "body": " message body",
  8.                "click_action": {
  9.                    "type": 1,
  10.                    "intent": "#Intent;compo=com.rvr/.Activity;S.W=U;end"
  11.                },
  12.                "style": 1,
  13.                "buttons": [
  14.                    {
  15.                        "action_type": 0,
  16.                        "name": "Learn more"
  17.                    },
  18.                    {
  19.                        "action_type": 3,
  20.                        "name": "Ignore"
  21.                    }
  22.                ],
  23.                "big_title": "HUAWEI Push Kit",
  24.                "big_body": "HUAWEI Push Kit is a messaging service provided by Huawei for developers. It establishes a messaging channel from the cloud to devices."
  25.            }
  26.        },
  27.        "token": [
  28.            "pushtoken1"
  29.        ]
  30.    }
  31. }
注意:

name字段的值如果为英文,通知消息展示时按钮名字会以全大写字母展示。

当action_type字段值为0或者1时,可以打开自身应用并给应用传递数据,通过data字段来设置,样例如下:

  1. {
  2.    "validate_only": false,
  3.    "message": {
  4.        "android": {
  5.            "notification": {
  6.                "title": "message title",
  7.                "body": " message body",
  8.                "click_action": {
  9.                    "type": 1,
  10.                    "intent": "#Intent;compo=com.rvr/.Activity;S.W=U;end"
  11.                },
  12.                "style": 1,
  13.                "buttons": [
  14.                    {
  15.                        "name": "Learn more",
  16.                        "action_type": 1,
  17.                        "intent_type": 0,
  18.                        "intent": "intent://com.huawei.codelabpush/deeplink?#Intent;scheme=pushscheme;launchFlags=0x4000000;i.age=180;S.name=abc;end",
  19.                        "data": "{\"key1\":\"value1\",\"key2\":\"value2\",\"keyn\":\"valuen\"}"
  20.                    }
  21.                ],
  22.                "big_title": "HUAWEI Push Kit",
  23.                "big_body": "HUAWEI Push Kit is a messaging service provided by Huawei for developers. It establishes a messaging channel from the cloud to devices."
  24.            }
  25.        },
  26.        "token": [
  27.            "pushtoken1"
  28.        ]
  29.    }
  30. }

透传数据data字段值的读取方法参考打开App首页中接收数据部分。

14. 基于第三方审核结果的消息推送

HUAWEI Push Kit禁止推送包含敏感词的消息,建议App的运营人员在推送消息的时候基于三方机构的审核结果来进行消息推送。即在推送消息给Push服务器时,需附带三方审核机构对消息体内容审核后的结果,当Push服务器检测到审核结果不通过时,会对消息进行拦截,并返回结果给App运营人员。

如何将待审核的消息体内容发送至三方机构进行审核,请参考推必安公有云接口文档。

说明:

发送给三方机构审核的消息体内容需将message结构体中token、topic、condition字段去掉后,再对剩余字段按ASCII码升序排序后的消息结构体。

推送消息给Push服务器时,将三方机构返回的审核结果放在Review对象中的result对象中。

示例报文:

  1. {
  2.    "validate_only": false,
  3.    "message": {
  4.        "notification": {
  5.            "title": "message title",
  6.            "body": "message body"
  7.        },
  8.        "android": {
  9.            "collapse_key": 0,
  10.            "notification": {
  11.                "click_action": {
  12.                    "type": 2,
  13.                    "url": "https://example.com"
  14.                }
  15.            }
  16.        },
  17.        "token": [
  18.            "pushtoken1"
  19.        ]
  20.    },
  21.    "review": [
  22.        {
  23.            "reviewer": "tuibian",
  24.            "type": 0,
  25.            "result": {
  26.                "code": 202,
  27.                "data": {
  28.                    "auditEngine": "test_engine",
  29.                    "auditId": "0f74b5126f6648a69cb7a7ba0b3f490d",
  30.                    "labels": [
  31.                        {
  32.                            "level": 3,
  33.                            "reason": "POLITIC",
  34.                            "words": "sensitive_word"
  35.                        }
  36.                    ]
  37.                },
  38.                "msg": "Review",
  39.                "sign": "MEQCIBHcTqNp2Agzq3G9uJvf/zxLop9 l57HH6ciubAq3g8XQw4Wg5rqUVJIqLjw=="
  40.            }
  41.        }
  42.    ]

  43. }