Set display content

You can configure the push title and content displayed in the notification bar in the following ways, with the configuration priority from low to high:

1. Configure the display attributes of push notifications;
2. Use the default push template;
3. Use message extension fields;
4. Use a custom push template.

Call updatePushNickname and updatePushDisplayStyle to configure the nickname (nickname) and notification display style (DisplayStyle), which includes the push title and content in the notification bar.

This nickname indicates the nickname of the message sender that is displayed in the push notification bar of the recipient's client when a message from the user is pushed. The nickname can be different from the nickname in user attributes. However, Agora recommends that you use the same nickname for both. Therefore, if either nickname is updated, the other should be changed at the same time. To update the nickname in user attributes, see Set user attributes.

_2

// Asynchronous processing is required.

_2

ChatClient.getInstance().pushManager().updatePushNickname("nickname");

_3

PushManager.DisplayStyle displayStyle = PushManager.DisplayStyle.SimpleBanner;

_3

// Asynchronous processing is required.

_3

ChatClient.getInstance().pushManager().updatePushDisplayStyle(displayStyle);

Call getPushConfigsFromServer to get the display attributes for push notifications, as shown in the following example:

_5

PushConfigs pushConfigs = ChatClient.getInstance().pushManager().getPushConfigsFromServer();

_5

// Get the nickname displayed in the push notification.

_5

String nickname = pushConfigs.getDisplayNickname();

_5

// Get the display style of the push notification.

_5

PushManager.DisplayStyle style = pushConfigs.getDisplayStyle();

To display the message content in the notification bar, set the notification display style (DisplayStyle). This parameter has the following two settings:

• (Default) SimpleBanner: Regardless of whether nickname is set, for any type of message pushed, the notification bar uses the default display setting, that is, the push title is "You have a new message" and the push content is "Please click to view".
• MessageSummary: Displays the message content. The nickname you set only takes effect when DisplayStyle is MessageSummary, not SimpleBanner.

The following table uses a one-to-one chat text message as an example to introduce the settings of the display attributes.

For group chats, "Push nickname of message sender" and "Chat user ID of message sender" in the table below are displayed as "Group ID".

Parameter settings	Push display	Image
DisplayStyle: (default) SimpleBanner nickname: Set or not set	Push title: "You have a new message" Push content: "Please click to view"
DisplayStyle: MessageSummary nickname: Set specific value	Push title: "You have a new message" Push content: "Push nickname of the message sender: message content"
DisplayStyle: MessageSummary nickname: Not set	Push title: “You have a new message” Push content: “Message sender's Chat user ID: message content”

The default push template is mainly used when the default configuration provided by the server does not meet your needs. It allows you to set the global push title and push content. For example, the default settings provided by the server are push titles and content in English. If you need to use push titles and content in another language, you can set the push template in the corresponding language.

To use the default template, create a default push template in Agora Console or call RESTful API. The template name is default. After setting, the default template is automatically used when pushing messages, and there is no need to enter the template name when creating messages.

Follow the steps below to create a default push template in Agora Console:

1. Log in to Agora Console and click Project Management in the left navigation bar.

2. On the Project Management page, click Config in the Action column for the project that has Chat enabled.

3. On the Edit Project page, in the Features area, click Enable / Config for Chat.

4. On the project configuration page, select Features > Push Template, click Add Push Template, and configure the fields in the pop-up dialog box, as shown in the following figure:

   

5. Set the Template Name to default, then set the Title and Content parameters, and click OK.

   Parameter	Type	Description	Required
   Template Name	String	The push template name. The default template is default.	Yes
   Title	Array	The push title. Can be set in the following ways: Enter a fixed push title. Use built-in variables and enter {$fromNickname}, {$msg}. Set custom variables through the value array. The field format is {0} {1} {2} ... {n}. If the default template is used, the first two settings do not need to pass in this parameter when creating a message. The server automatically obtains it. The third setting method needs to be passed in through the extension field.	Yes
   Content	Array	The push content. Can be set in the following ways: Enter fixed push content. Use variables and enter {$fromNickname}, {$msg}. Set custom variables through the value array. The field format is {0} {1} {2} ... {n}. If the default template is used, the first two settings do not require parameters to be passed in when creating a message. The server automatically obtains them. The third setting method needs to be passed in through the extension field.	Yes

When creating a push message, you can set the em_push_title and em_push_content message extension fields to customize the push title and content, respectively.

_12

// This takes text messages as an example. The setting methods for message types such as images and files are the same.

_12

ChatMessage message = ChatMessage.createSendMessage(ChatMessage.Type.TXT);

_12

// Set custom push display.

_12

JSONObject extObject = new JSONObject();

_12

try {

_12

extObject . put( " em_push_title " , " custom push title " ); // Custom push message title. This field is a built-in field and the field name cannot be modified.

_12

extObject . put( " em_push_content " , " custom push content " ); // Custom push message content. This field is a built-in field and the field name cannot be modified.

_12

} catch (JSONException e) {

_12

e.printStackTrace();

_12

}

_12

// Set the push extension to the message. This field is a built-in push extension field.

_12

message.setAttribute("em_apns_ext", extObject);

The data structure of the custom display field is as follows:

_6

{

_6

"em_apns_ext": {

_6

"em_push_title": "custom push title",

_6

"em_push_content": "custom push content"

_6

}

_6

}

The steps to use a custom push template are as follows:

1. If you use a custom push template, create it in Agora Console or call RESTful API. For a description of the parameters in the Add Push Template dialog box, see the section about using the default template. When using a custom template, regardless of how the Title and Content parameters are set, they must be passed in through the extension fields when creating a message.

2. When creating a message, pass in the template name, push title, and push content by using the extension fields. The push title and content in the notification bar use the formats in the template, respectively.

   
   

   _30

   // The following takes text messages as an example. The setting methods for other types of messages are the same.

   _30

   ChatMessage message = ChatMessage.createSendMessage(ChatMessage.Type.TXT);

   _30

   TextMessageBody txtBody = new TextMessageBody("message content");

   _30

   // Set the push notification recipient. For one-to-one chats, it is the recipient's user ID; for group chats, it is the group ID.

   _30

   message.setTo("receiver");

   _30

   // Use the push template.

   _30

   JSONObject pushObject = new JSONObject();

   _30

   JSONArray titleArgs = new JSONArray();

   _30

   JSONArray contentArgs = new JSONArray();

   _30

   try {

   _30

   // Set the push template name.

   _30

   pushObject.put("name", "test6");

   _30

   // Set the value array of the push title in the template. If the push title specified in the template is a placeholder, you can customize the title here; if the specified title is a fixed value, the title will be a fixed value when using this template.

   _30

   titleArgs.put("test1");

   _30

   //...

   _30

   pushObject.put("title_args", titleArgs);

   _30

   // Set the value array of the pushed content in the template. If the template content specified in the template is a placeholder, you can customize the content here; if the specified content is a fixed value, the content will be a fixed value when using the template.

   _30

   contentArgs.put("$fromNickname");

   _30

   contentArgs.put("$msg");

   _30

   //...

   _30

   pushObject.put("content_args", contentArgs);

   _30

   } catch (JSONException e) {

   _30

   e.printStackTrace();

   _30

   }

   _30

   // Add the push template to the message.

   _30

   message.setAttribute("em_push_template", pushObject);

   _30

   // Set the message status callback.

   _30

   message.setMessageStatusCallback(new CallBack() {...});

   _30

   // Send the message.

   _30

   ChatClient.getInstance().chatManager().sendMessage(message);

   
   

The JSON structure of the push template is as follows:

_10

"em_push_template":{

_10

"name":"test6",

_10

"title_args":[

_10

"test1"

_10

],

_10

"content_args":[

_10

"{$fromNickname}",

_10

"{$msg}"

_10

]

_10

}

The message receiver can call the setPushTemplate method to pass in the push template name and select the template to use.

If the sender uses a push template when sending a message, the content displayed in the push notification bar is based on the sender's push template.

_11

ChatClient.getInstance().pushManager().setPushTemplate("Template Name", new CallBack() {

_11

@Override

_11

public void onSuccess() {

_11

_11

}

_11

_11

@Override

_11

public void onError(int code, String error) {

_11

_11

}

_11

});