目录

1. Customized Notification Channel

Notification channel is a new function introduced in the Android O version to resolve the following issues:

1. More and more notification messages are sent by apps, causing obvious disturbance to users.

2. In versions earlier than EMUI 10.0, Huawei phones provide a default notification channel that is not customizable.

From EMUI 10.0 and on, three notification channels (service reminder, common notification, and marketing notification) are added to display notification messages of different priorities (high, medium, and low). Besides, a customized notification channel can be created. For details about how to create a customized notification channel, please refer to the related Android official document. To display messages in a customized channel for your app, you only need to set the channel_id field in message > android > notification of the request sent to the HUAWEI Push Kit server to the ID of the desired channel. Whether the messages can be displayed in a notification channel of your app depends on whether the channel has been created and enabled on the user device.

Notice：

Only messages with medium and high priorities can be displayed in the customized notification channel. Messages with the low priority are displayed in the marketing notification channel.

Sample code:

  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. Notification Message Localization

Notification message localization refers to displaying titles and content of notification messages in the system language of the destination device.

The following figure shows notification messages displayed in different languages.

After localization, notification messages can be displayed in NC. Alternatively, you can call a RESTful API of the HUAWEI Push Kit server to configure that notification messages are processed by the app when it runs in the foreground. This section describes how to develop the two processing modes.

2.1 Message Display in NC

You can use two methods to implement this display mode. Method 1: Call a RESTful API of the HUAWEI Push Kit server to perform configuration but do not configure the strings.xml file of your app. Method 2: Call a RESTful API of the HUAWEI Push Kit server to perform configuration (excluding defining the multi_lang_key field) and configure the strings.xml file of your app.

Note: If both the multi_lang_key field and the strings.xml file of your app are specified, the multi_lang_key field is used preferentially. If this field fails to be read, the display mode is read from the strings.xml file of your app.

Method 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. }
Notice:

The value of the multi_lang_key field is an object, whose title and body must be the same as the values of the title_loc_key and body_loc_key fields. In the preceding example, the value of the body_key field is also an object, which supports a maximum of three languages currently. The value of the en field is a formatted string, and the placeholder %s indicates a string value. The value of the body_loc_args field is a variable string array, which is used to replace the placeholders in the value of the en field. You can set the body_loc_args field based on the service requirements.

Method 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>
Note:
You can configure string resource files for multiple languages in the res directory. For example, configure the English (UK) string resource file /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. }
Notice:
The value of title_loc_key must be the same as the field name defined in the strings.xml file. The variable string array specified by title_loc_args is used to replace format specifiers in the strings.xml file. Therefore, the length of the variable string array must be greater than or equal to the number of placeholders in the corresponding field value in the strings.xml file.

2.2 Message Processing by the App

The HMS Core Push SDK does not provide the method of obtaining the value of multi_lang_key set by using a RESTful API of the HUAWEI Push Kit server. Therefore, to enable your app to display notification messages, you must configure the strings.xml file of your app. For details, please refer to Method 2 in Message Display in NC.

3. Notification Message Display on UI

Assume that you have used the HUAWEI Push Kit server's open API to configure that if the app is running in the foreground, notification messages are not displayed in NC but transparently transmitted to the app. When your app server sends a notification message, the message is processed for display by the app. You can set the foreground_show field in message > android > notification to the role that displays the message.

Notice:
This function is supported on devices running EMUI 9.1.0 or later and HMS SDK 4.0 or later.

Sample code:

  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. }

Field value description: If this field is set to true or left empty, notification messages are displayed in NC even when your app is running in the foreground. If this field is set to false, notification messages are not displayed in NC. Instead, all notification message content is transmitted to the app through the onMessageReceived(RemoteMessage message) method of the HmsMessageService class, and the app calls the method provided by the RemoteMessage class to obtain related fields. In this case, HUAWEI Push Kit does not verify the fields in the messages.

4. Notification Message Display Overwriting

If a user does not tap or delete a notification message that is displayed on a device, the notification message can be overwritten by a new notification message. This function can be implemented through an API provided by the HUAWEI Push Kit server, specifically, through the tag field (whose value is a string), the notify_id field (whose value is an integer), or the group field (whose value is a string).

Sample code containing the tag field:

  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. }

For messages with the same tag value, the older one will be overwritten by the newer one.

Sample code containing the notify_id field:

  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. }

The notify_id field specifies the unique notification ID of a message. Different notification messages can have the same notify_id value, and the older one will be overwritten by the newer one.

Sample code containing the group field:

  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. }

For multiple messages with the same group value, only the latest one will be displayed.

Notice：

tag, notify_id, and group are mutually exclusive. Only one of them should be used. However, if all of them are used, group will take the precedence, followed by tag and then notify_id.

5. Message Sending by Conditions

This function enables you to send topic-based messages based on a combination of conditions, or in another word, a Boolean expression of target topics. For example, you can send messages to users who have subscribed to both the weather and sports topics. Currently, this function is only available in Android apps. For details about the condition field, please refer to Sending Messages.

Sample code:

  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. Offline Message Overwriting

By using the offline message cache identifier, namely, the collapse_key field provided by the server API, you can control the caching and overwritting of offline messages. For details about the collapse_key field, please refer to Sending Messages.

Sample code:

  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. Offline Message Caching Duration

You can control the caching duration of offline messages using the ttl field provided by the server API. For details about the ttl field, please refer to Sending Messages.

Sample code:

  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. Large Text Style

When using the default style, a notification includes only a single line of text. To provide more information, you can use the large text style, where a large chunk of text (up to 11 lines are allowed by EMUI) can be displayed under the title line. The following figure shows an expanded notification in the large text style.

Sample code:

  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. }
Notice:

The title and text displayed before the notification is expanded use the values of the title and body fields, rather than those of the big_title and big_body fields.

9. Notification Content Hiding on the Lock Screen

If the screen of a mobile phone is locked, the content of a received notification message will not be displayed on the lock screen. To enable this function, set the visibility field in the Sending Messages API provided by the HUAWEI Push Kit server. The options are of the visibility field are as follows:

Notice:
The global parameter Hide notification content is valid only when visibility is set to PRIVATE.

Sample code:

  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. Badging

HUAWEI Push Kit provides an API for setting badges on the server. You can encapsulate badge parameters in messages. For notification messages, HUAWEI Push Kit will display the badge number on the app. For data messages, your app needs to call the getBadgeNumber() method to obtain badge parameters from the message and display the badge number.

Sample code for setting a badge on the server:

  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. }

For details about badge development on the client, please refer to Interface Description for Badging on Huawei Desktop.

Notice:

1. By default, when a user starts the app, taps a notification message, or clears a notification message, the badge number will not be deleted. To enable your app to clear the badge number, perform development on the client by referring to Interface Description for Badging on Huawei Desktop.

2. If both add_num and set_num are set, set_num will take the precedence.

11. Customizing a Notification Icon

HUAWEI Push Kit provides two methods for setting notification message icons: Method 1: Set the icon field in the Sending Messages API provided by the HUAWEI Push Kit server. Method 2: Add meta-data to the AndroidManifest.xml file. Here, we describe method 2 in detail.

Add <meta-data> to the application element. Do not modify name in the meta-data element and use resource to specify a resource icon, which must be stored in the res/drawable directory of your app.

  1. <application
  2.     <meta-data
  3.         android:name="com.huawei.messaging.default_notification_icon"
  4.         android:resource="@drawable/ic_push_notification" />
  5. </application>
Notice:

1. The icon file stored by the app must have an extension name but the extension name must not be included in the URI. Currently, supported file formats include PNG and JPG.

2. If both methods are used, the icon specified by the icon field will be displayed preferentially. If neither method is used, the desktop icon of your app will be used by default.

12. Inbox Style

Different from the large text style, the inbox style allows notification text to be displayed in sequence in separate lines, as shown in the figure below. The sequence numbers of the text lines are added manually and a maximum of five lines can be displayed. When text cannot be completely displayed in a line due to space restrictions, an ellipsis (...) will be automatically added to the end of the line.

Sample code:

  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. }
Note:

When using the inbox style, ensure that the size of the inbox_content array is at least two, namely, the array should contain at least two messages. Otherwise, it is recommended that you use the large text style instead.

13. Notification Message with Action Buttons

You can add action buttons to notification messages. A tap on the buttons will trigger the predefined actions. For details about the types of actions supported, please refer to the Button Structure provided by the server API. The figure below shows a notification message with action buttons.

Sample code:

  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. }
Notice:

If the value of name is in English, the button name will be displayed in uppercase letters in the message.

If the value of action_type is 0 or 1, a tap on the button will launch your own app and data specified by the data field will be sent to the app. Sample code:

  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. }

For details about how to read the value of the data field, please refer to the data receiving method as described in Opening the Home Page of an App.