Local search is supported starting from Enhanced Edition v5.4.666. To use local search, you need to purchase the Flagship Edition package. For operation details, please see Purchase Guide.

Feature Demonstration

The search API interface consists of three parts: the upper part is for friend search, the middle part is for group and group member search, and the lower part is for message search, where messages are classified by conversation.

Integration Guide

Scheme 1: Integrating TUIKit search source code

Step 1. Purchase the package

Purchase the Flagship Edition package by referring to Purchase Guide.

Step 2. Download source code

Download source code to integrate the TUIKit module. TUIKit supports local search starting from v5.4.666.

implementation project(':tuikit')

Step 3. Initialize TUIKit and log in

// Initialize TUIKit
TUIKitConfigs configs = TUIKit.getConfigs();
TUIKit.init(this, SDKAPPID, configs);
// Log in to TUIKit
TUIKit.login(userID, userSig, new IUIKitCallBack() {
@Override
public void onSuccess(Object data) {
  // Login succeeded
}
@Override
public void onError(String module, final int code, final String desc) {
  // Login failed
}
});

Step 4. Start the search interface

You only need to start SearchMainActivity.

Scheme 2: Integrate the IM SDK search API

Step 1. Purchase the package

Purchase the Flagship Edition package by referring to Purchase Guide.

Step 2. Integrate IM SDK Enhance Edition

The IM SDK supports local search starting from v5.4.666.

dependencies {
api 'com.tencent.imsdk:imsdk-plus:Version number`
}

Step 3. Call the local user profile search API

You can call the searchFriends API to search for local user profiles. The API supports the following search fields: userID, nickName, and remark.

Step 4. Call the local group and group member search APIs

You can call the searchGroups API to search for the profiles of local groups.
You can call the searchGroupMembers API to search for the profiles of local group members. There are two cases, depending on whether the value of groupIDList in V2TIMGroupMemberSearchParam is null:

• groupIDList == null: search the members in all groups, and the returned results will be classified by group ID.
• groupIDList != null: search the members in a specified group.

Step 5. Call the local message search API

You can enter keywords in the search box to call searchLocalMessages to search for local messages. There are two cases, depending on whether the value of conversationID in the V2TIMMessageSearchParam API is null:

• conversationID == null: search all conversations, and the returned results will be classified by conversation.
• conversationID != null: search a specified conversation.

Displaying recent active conversations
As shown in Figure 1, the bottom part of the search interface is the list of the last 3 conversations to which the messages found belong. The implementation method is as follows:

• In the V2TIMMessageSearchParam API, conversationID is set to null, indicating the messages of all conversations are searched; pageIndex is set to 0, indicating data on page 0 of the conversations to which the messages found belong; pageSize indicates the number of recent conversations to be returned. Usually, 3 recent conversations are displayed on the UI.
• In the search callback result API V2TIMMessageSearchResult, totalCount indicates the total number of conversations to which the matched messages belong; messageSearchResultItems indicates the information of the recent conversations (conversation quantity specified by pageSize). In V2TIMMessageSearchResultItem, conversationID indicates the conversation ID, messageCount indicates the total number of messages found in the current conversation, and messageList indicates the list of messages found. messageList has two cases:
  • If the number of messages found is greater than 1, messageList is empty. You can display related chat records (quantity specified by messageCount) on the UI.
  • If the number of messages found is equal to 1, messageList is the matched message. You can display the message content on the UI and highlight the search keyword, such as test in the above figures.

Sample

List<String> keywordList = new ArrayList<>();
keywordList.add("test");
V2TIMMessageSearchParam v2TIMMessageSearchParam = new V2TIMMessageSearchParam();
// Setting `conversationID` to `null` is to search for messages in all conversations and the results will be classified by conversation
v2TIMMessageSearchParam.setConversationID(null);
v2TIMMessageSearchParam.setKeywordList(keywordList);
v2TIMMessageSearchParam.setPageSize(3);
v2TIMMessageSearchParam.setPageIndex(0);
V2TIMManager.getMessageManager().searchLocalMessages(v2TIMMessageSearchParam, new V2TIMValueCallback<V2TIMMessageSearchResult>() {
  @Override
  public void onSuccess(V2TIMMessageSearchResult v2TIMMessageSearchResult) {
      // Total number of matched conversations to which messages belong
      int totalCount = v2TIMMessageSearchResult.getTotalCount();
      // Last 3 messages classified by conversation
      List<V2TIMMessageSearchResultItem> resultItemList = v2TIMMessageSearchResult.getMessageSearchResultItems();
      for (V2TIMMessageSearchResultItem resultItem : resultItemList) {
          // Conversation ID
          String conversationID = resultItem.getConversationID();
          // Total number of messages matching the conversation
          int totalMessageCount = resultItem.getMessageCount();
          // List of messages. If `totalMessageCount` is greater than 1, the list is empty. If `totalMessageCount` is equal to 1, the list contains the current message.
          List<V2TIMMessage> v2TIMMessageList = resultItem.getMessageList();
      }
  }
   @Override
  public void onError(int code, String desc) {}

Displaying the list of conversations to which the messages found belong
For example, you can click More Chat History in Figure 1 to redirect to the list of conversations to which the messages found belong, as shown in Figure 2. The search parameters and results are similar to those in the preceding scenario. To avoid memory ballooning, it is strongly recommended that you load the conversation list with pagination. For example, to display 10 conversations as the result, you can set the search parameter API V2TIMMessageSearchParam as follows:

• First call: Set pageSize to 10 and pageIndex to 0, and call searchLocalMessages. Then you can get the total number of conversations from totalCount in the callback.
• Page quantity calculation: totalPage = (totalCount % pageSize == 0) ? (totalCount / pageSize) : (totalCount / pageSize + 1)
• Second call: You can specify pageIndex (pageIndex < totalPage) to return the subsequent page number.

Sample

......
// Calculate the total number of pages, given that 10 messages are displayed per page
int totalPage = (totalCount % 10 == 0) ? (totalCount / 10) : (totalCount / 10 + 1);
......
private void searchConversation(int index) {
  if (index >= totalPage) {
      return;
  }
  List<String> keywordList = new ArrayList<>();
  keywordList.add("test");
  V2TIMMessageSearchParam v2TIMMessageSearchParam = new V2TIMMessageSearchParam();
  v2TIMMessageSearchParam.setConversationID(null);
  v2TIMMessageSearchParam.setKeywordList(keywordList);
  v2TIMMessageSearchParam.setPageSize(10);
  v2TIMMessageSearchParam.setPageIndex(index);
  V2TIMManager.getMessageManager().searchLocalMessages(v2TIMMessageSearchParam, new V2TIMValueCallback<V2TIMMessageSearchResult>() {
      @Override
      public void onSuccess(V2TIMMessageSearchResult v2TIMMessageSearchResult) {
            // Total number of matched conversations to which messages belong
            int totalCount = v2TIMMessageSearchResult.getTotalCount();
            // Calculate the total number of pages, given that 10 messages are displayed per page
            int totalPage = (totalCount % 10 == 0) ? (totalCount / 10) : (totalCount / 10 + 1);
            // Information of messages classified by conversation
            List<V2TIMMessageSearchResultItem> resultItemList = v2TIMMessageSearchResult.getMessageSearchResultItems();
            for (V2TIMMessageSearchResultItem resultItem : resultItemList) {
                // Conversation ID
                String conversationID = resultItem.getConversationID();
                // Total number of messages matching the conversation
                int totalMessageCount = resultItem.getMessageCount();
                // List of messages. If `totalMessageCount` is greater than 1, the list is empty. If `totalMessageCount` is equal to 1, the list contains the current message.
                List<V2TIMMessage> v2TIMMessageList = resultItem.getMessageList();
            }
            @Override
        public void onError(int code, String desc) {}
  });
}
// Load the next page
public void loadMore() {
  searchConversation(++pageIndex);
}

Searching for messages in a specified conversation
Figure 2 shows the effect of displaying the conversation list, while Figure 3 shows the effect of displaying the list of the messages found in a specified conversation. To avoid memory ballooning, it is strongly recommended that you load the message list with pagination. The implementation method is as follows:

• In the V2TIMMessageSearchParam API, set conversationID to the ID of the conversation to search, and set pageIndex and pageSize by referring to the settings in the preceding calculation mode.
• In the V2TIMMessageSearchResult API, totalCount indicates the total number of messages matched in the conversation, and messageSearchResultItems lists only the results in the conversation. In V2TIMMessageSearchResultItem, messageCount is the number of messages on the current page, and messageList is the list of messages on the current page.

Sample

......
// Calculate the total number of pages, given that 10 messages are displayed per page
int totalMessagePage = (totalMessageCount % 10 == 0) ? (totalMessageCount / 10) : (totalMessageCount / 10 + 1);
......
private void searchMessage(int index) {
if (index >= totalMessagePage) {
    return;
}
List<String> keywordList = new ArrayList<>();
keywordList.add("test");
V2TIMMessageSearchParam v2TIMMessageSearchParam = new V2TIMMessageSearchParam();
v2TIMMessageSearchParam.setConversationID(conversationID);
v2TIMMessageSearchParam.setKeywordList(keywordList);
v2TIMMessageSearchParam.setPageSize(10);
v2TIMMessageSearchParam.setPageIndex(index);
V2TIMManager.getMessageManager().searchLocalMessages(v2TIMMessageSearchParam, new V2TIMValueCallback<V2TIMMessageSearchResult>() {
    @Override
    public void onSuccess(V2TIMMessageSearchResult v2TIMMessageSearchResult) {
        // Total number of messages matching the conversation
        int totalMessageCount = v2TIMMessageSearchResult.getTotalCount();
        // Calculate the total number of pages, given that 10 messages are displayed per page
        int totalMessagePage = (totalMessageCount % 10 == 0) ? (totalMessageCount / 10) : (totalMessageCount / 10 + 1);
        // Information of the messages on the conversation page
        List<V2TIMMessageSearchResultItem> resultItemList = v2TIMMessageSearchResult.getMessageSearchResultItems();
        for (V2TIMMessageSearchResultItem resultItem : resultItemList) {
            // Conversation ID
            String conversationID = resultItem.getConversationID();
            // Number of messages on the current page
            int totalMessageCount = resultItem.getMessageCount();
            // List of messages on the current page
            List<V2TIMMessage> v2TIMMessageList = resultItem.getMessageList();
    }
        @Override
    public void onError(int code, String desc) {
    }
});
}
// Load the next page
public void loadMore() {
  searchMessage(++pageIndex);
}

FAQs

1. How do I search for custom messages?

Use the createCustomMessage (byte[] data, String description, byte[] extension) API to create and send a search request. In the request, you need to specify the text to search in the description parameter. Custom messages created via the createCustomMessage (byte[] data) API cannot be searched because the binary data stream passed in by parameters is saved locally.
If you configure the offline push feature and the description parameter, custom messages will also be pushed offline, and the content specified in the description parameter will be displayed in the notification bar. If offline push is not needed, disable it using disablePush in V2TIMOfflinePushInfo in the sendMessage API. If you do not want to display the searched text in the push notification bar, set other push content using setDesc in V2TIMOfflinePushInfo.

2. How do I search for rich media messages?

Rich media messages include file, image, voice, and video messages.
For file messages, the screen usually displays the filename. Therefore, you can set the fileName parameter as the searched content when creating messages. If fileName is not set, the system gets the filename from filePath and saves it to the local storage and the server.
For image, voice, and video messages, the screen usually displays the thumbnail or duration. In this case, you can specify the message type to search by type, but cannot search by keywords.