Local Search (Android)

Last updated: 2021-10-15 16:46:33

    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:

    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.