Hooks

Hooks are used by Global IM UIKit to fetch necessary data from the business layer when required, such as user profiles, group information, and more. Developers need to implement the necessary hooks as required during the initialization of Global IM UIKit.

tip

Since hook definitions can be complex, this chapter uses Typescript code examples to help users better understand the parameters and return value data structures of the hooks.

Hooks Definition

All required hooks in Global IM UIKit are defined through the IRCKitServiceHooks interface, declared as follows:

export interface IRCKitServiceHooks {
  /**
   * Fetch user profiles in bulk based on userIds
   * @param userIds - List of user IDs
   */
  reqUserProfiles(userIds: string[]): Promise<IRCKitUserProfile[]>;
  /**
   * Fetch group profiles in bulk based on groupIds
   * @param groupIds - List of group IDs
   */
  reqGroupProfiles(groupIds: string[]): Promise<IRCKitGroupProfile[]>;
  /**
   * Fetch system conversation profiles in bulk. This method is called when the conversation list contains ConversationType.SYSTEM.
   * @param targetIds - List of system conversation IDs
   */
  reqSystemProfiles(targetIds: string[]): Promise<IRCKitSystemProfile[]>;
  /**
   * Fetch group member profiles
   * @param groupId - Group ID
  */
  reqGroupMembers(groupId: string): Promise<IRCKitGroupMemberProfile[]>;
  /**
    * [Optional] Define default user profiles to replace SDK's default initial data, such as avatar and naming rules.
    * @param userId - User ID
    */
  getDefaultUserProfile?(userId: string): IRCKitUserProfile;
  /**
    * [Optional] Define default group profiles to replace SDK's default data, such as avatar and naming rules.
    * @param groupId - Group ID
    */
  getDefaultGroupProfile?(groupId: string): IRCKitGroupProfile;
  /**
    * [Optional] Define default system conversation profiles to replace SDK's default data, such as avatar and naming rules.
    * @param systemId - System conversation ID
    */
  getDefaultSystemProfile?(systemId: string): IRCKitSystemProfile;
  /**
   * [Optional] Request user online status
   * @param userIds - List of user IDs
   */
  reqUserOnlineStatus?(userIds: string[]): Promise<IRCKitUserOnlineStatus[]>;
}

Invocation and Caching

Global IM UIKit caches user profiles, group information, and other data fetched from the business layer internally to avoid redundant requests.

The following diagram illustrates the mechanism for fetching and updating user profiles in Global IM UIKit.

When user profiles, group information, or other data changes, the business layer can call methods like updateUserProfile to notify Global IM UIKit to update the cached data and refresh the UI display accordingly. For more details, refer to the Data Update section.

Code Example

import { IRCKitServiceHooks, RCKitInstaller } from '@rongcloud/global-im-uikit';
// You can also reference Global IM UIKit as follows. For clarity in documentation examples, we use import * as RCIMKit here.
// import { RCKitInstaller } from '@rongcloud/global-im-uikit';

const hooks: IRCKitServiceHooks = {
  // Define method to fetch user profiles
  async reqUserProfiles(userIds: string[]): Promise<IRCKitUserProfile[]> {
    // userIds is a list of user IDs. The business layer needs to provide corresponding user profiles based on userIds.
    return userIds.map((userId) => ({
      userId,
      name: '', // User name. Provide a valid value; otherwise, it will affect user profile display.
      portraitUri: '', // User avatar. Provide a valid value; otherwise, the SDK will use a default avatar.
    }));
  },

  // Define method to fetch group profiles
  async reqGroupProfiles(groupIds: string[]): Promise<IRCKitGroupProfile[]> {
    // groupIds is a list of group IDs. The business layer needs to provide corresponding group profiles based on groupIds.
    return groupIds.map((groupId) => ({
      groupId,
      name: '', // Group name. Provide a valid value; otherwise, it will affect group profile display.
      memberCount: 0, // Group member count. Provide a valid value; otherwise, it will affect group profile display.
      portraitUri: '', // Group avatar. Provide a valid value; otherwise, the SDK will use a default avatar.
    }));
  },

  // Define method to fetch group member profiles
  async reqGroupMembers(groupId: string): Promise<IRCKitGroupMemberProfile[]> {
    // groupId is the group ID. The business layer needs to provide corresponding group member profiles based on groupId.
    return [
      // The business layer needs to provide real group member information. The nickname field is optional.
      // If nickname is empty, the SDK will use the name field from the user profile fetched via reqUserProfiles as the group member's nickname.
      // For performance optimization, it is recommended that the business layer provide real nicknames to avoid multiple calls to reqUserProfiles internally.
      { userId: 'user-01', nickname: '' },
      { userId: 'user-02' }
    ]
  },

  // Define method to fetch system conversation profiles
  async reqSystemProfiles(systemIds: string[]): Promise<IRCKitSystemProfile[]> {
    // systemIds is a list of system conversation IDs. The business layer needs to provide corresponding system conversation profiles based on systemIds.
    return systemIds.map((systemId) => ({
      systemId,
      name: '', // System conversation name. Provide a valid value; otherwise, it will affect system conversation display.
      portraitUri: '', // System conversation avatar. Provide a valid value; otherwise, the SDK will use a default avatar.
    }));
  },
}

// Initialize Global IM UIKit by passing hooks as a parameter
const kitApp = RongIMLib.installPlugin(RCKitInstaller, { hooks });