Aggregate channels by type

Chat UI SDK supports aggregating (collapsing) channels by type in the channel list. After you configure aggregation, all channels of that type appear as a single aggregated entry in the channel list. By default, the channel list displays all local channels in a flat view.

The following images show the effect of aggregating direct channels. In the channel list, all direct channels collapse into Direct messages (left). Tap the entry to open the aggregated channel list (right).

tip

Chat UI SDK includes a title bar implementation in the default aggregated channel list Activity (SubChannelListActivity). If you build an aggregated channel list page based on Fragment, implement the title bar yourself.

Limitations

• Aggregated channel entries in the channel list do not support pinning.
• Only aggregation by channel type is supported. Aggregation by channel ID is not supported.

Configure aggregated channel types

The aggregation feature supports direct, group, and system channel types. You can extend BaseDataProcessor to implement a custom data processor and provide it to Chat UI before opening the channel list page.

1. Declare a custom data processor class MyAggregateDataProcessor that extends the SDK's BaseDataProcessor. Override the isGathered method. Return true when the channel type should be aggregated. The following example aggregates all system channels.

   Java

   public class MyAggregateDataProcessor extends BaseDataProcessor<BaseChannel> {
       /**
       * Define the channel types supported by the custom channel list page. This example supports direct, group, and system channels.
       */
       @Override
       public ChannelType[] supportedTypes() {
           ChannelType[] types = {ChannelType.DIRECT, ChannelType.GROUP, ChannelType.SYSTEM};
           return types;
       }
   
       /**
       * Define which channels to aggregate. This example aggregates direct channels.
       */
       @Override
       public boolean isGathered(ChannelType type) {
           if (type.equals(ChannelType.DIRECT)) {
               return true;
           } else {
               return false;
           }
       }
   
   }

2. Before opening the channel list page, use the setDataProcessor method to set the channel list data processor.

   Java

   NCChatUIConfig.channelListConfig().setDataProcessor(new MyAggregateDataProcessor());

Aggregated channel list page

After you configure channel aggregation, aggregated channels collapse into a single gathered channel entry (GatheredConversation) in the channel list. Tap the entry to open the aggregated channel list page.

Chat UI provides aggregated channel list pages based on both Activity and Fragment classes.

• Activity-based: Chat UI provides a default aggregated channel list page SubChannelListActivity. The page displays a title bar and an aggregated channel list. When SDK internal pages need to navigate to the aggregated channel list, they navigate to this Activity by default.
• Fragment-based: You can use Chat UI's SubChannelListFragment to build a custom aggregated channel list page. You must register your custom channel list Activity with Chat UI SDK to replace the default aggregated channel list Activity.

Launch the default aggregated channel list page

To navigate to the aggregated channel list Activity from other pages in your app, use the built-in Activity router RouteUtils.

tip

If you build a custom channel list Activity, you must register it with RouteUtils before you can navigate to it this way. Otherwise, navigation opens the SDK's default SubChannelListActivity.

Parameters

Parameter	Type	Description
context	Context	Activity context
type	ChannelType	Channel type.
title	String	Channel list page title. If empty, the default title "Conversation List" displays.

Sample code

Java

RouteUtils.routeToSubChannelListActivity(context, conversationType, title);

tip

The data processor is supported through the abstract class BaseDataProcessor. If needed, you can also use the DataProcessor interface to implement your own DataProcessor class. For detailed information about data processors, see Customize data processing.

Build an aggregated channel list Activity with Fragment

If the default aggregated channel list SubChannelListActivity does not meet your requirements, we recommend extending Chat UI's aggregated channel list Fragment class SubChannelListFragment to build a custom aggregated channel list page.

tip

Your custom aggregated channel list Activity must be registered with Chat UI SDK to replace the default aggregated channel list Activity.

1. Integrate the Chat UI aggregated channel list Fragment in your app Activity. The following example declares a new MyAggregateConversationListActivity.

   xml

   <activity
       android:name="xxx.xxx.MyAggregateConversationListActivity"
       android:screenOrientation="portrait"
       android:windowSoftInputMode="stateHidden|adjustResize">
       <intent-filter>
           <action android:name="android.intent.action.VIEW" />
           <category android:name="android.intent.category.DEFAULT" />
           <data
               android:host="${applicationId}"
               android:pathPrefix="/subconversationlist"
               android:scheme="rong" />
       </intent-filter>
   </activity>

2. Implement the aggregated channel list layout. This example uses the activity_subconversation_list.xml layout.

   xml

   <?xml version="1.0" encoding="utf-8"?>
   <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
           android:orientation="vertical"
           android:layout_width="match_parent"
           android:layout_height="match_parent">
           <FrameLayout
               android:id="@+id/container"
               android:layout_width="match_parent"
               android:layout_height="match_parent" />
   </LinearLayout>

3. Extend Chat UI's SubChannelListFragment to create a subclass, such as AppSubChannelListFragment. In the onCreate method of MyAggregateConversationListActivity, create and use the SubChannelListFragment.

   Java

   SubChannelListFragment subChannelListFragment = new AppSubChannelListFragment();
   FragmentManager manager = getSupportFragmentManager();
   FragmentTransaction transaction = manager.beginTransaction();
   transaction.replace(R.id.container, subChannelListFragment);
   transaction.commit();

4. Register your custom aggregated channel list Activity with RouteUtils to replace the default Chat UI aggregated channel list Activity. Register the method once in the main process during the app lifecycle.

   Parameters

   Parameter	Type	Description
   activityType	ChatUIActivityType	Built-in Chat UI Activity type enum. Use ChatUIActivityType.SubChannelListActivity for this case.
   className	Class<? extends Activity>	Class name of your custom aggregated channel list Activity.

   Sample code

   Java

   RouteUtils.registerActivity(RouteUtils.ChatUIActivityType.SubChannelListActivity, MyAggregateConversationListActivity.class);

   After registration, when SDK internal pages need to navigate to the aggregated channel list, the SDK automatically navigates to your registered app Activity.

Customization

After you configure channel aggregation by type, the channel list page displays the corresponding gathered channel (GatheredConversation) entry. You can set the avatar and title for gathered channels.

Set gathered channel avatar

You can set a custom avatar for gathered channels (GatheredConversation) in the channel list page. If you do not set one, Chat UI uses the default avatar.

Parameters

Parameter	Type	Description
conversationType	ChannelType	Channel type to aggregate
portraitUri	Uri	URI of the custom gathered channel avatar resource

Sample code

Java

NCChatUIConfig.gatheredChannelConfig().setGatherConversationPortrait(conversationType, portraitUri);

Set gathered channel title

You can set a custom title for gathered channels (GatheredConversation) in the channel list page. In the current Android Chat UI source code, gathered channel titles are stored through GatheredChannelConfig#setConversationTitle(ChannelType, int). Define your own string resource and pass its resource ID to this method.

To change the gathered channel title, call the following method before entering the channel list:

Parameters

Parameter	Type	Description
conversationType	[ChannelType]	Channel type to aggregate
title	int	Resource ID of the custom gathered channel title

Sample code

Java

NCChatUIConfig.gatheredChannelConfig().setConversationTitle(conversationType, R.string.my_gathered_title);

If you use the default aggregated channel list Activity (SubChannelListActivity), the gathered channel title also displays in the page title bar.