ArIM

ArIM 是 IM Web SDK 的命名空间，提供 create 方法、version 属性。

创建实例

使用 create 方法创建 IM 实例。

import { create, type CreateOptions } from 'ar-im';

const options: CreateOptions = {
  appID: 'YOUR_APPID',
  mimIdx: 'YOUR_INDEX',
};
const im = create(options);

IM 实例

通过 create 方法创建的 IM 实例 ArIMClient，拥有一下方法和事件回调。

登录/登出

|API|说明| |--|--| |login|登录即时通信 (IM) 系统。| |logout|登出即时通信 (IM) 系统。|

消息

|API|说明| |--|--| |createAudioMessage|创建音频消息。| |createCustomMessage|创建自定义消息。| |createFileMessage|创建文件消息。| |createForwardMessage|创建转发消息。| |createImageMessage|登创建图片消息。| |createTextMessage|创建文字消息。| |createVideoMessage|创建视频消息。| |deleteMessage|删除本地消息。| |sendMessage|发送(点对点或群组)消息。|

会话

|API|说明| |--|--| |createConversation|用于创建 C2C（单聊） 或群组会话（群聊）。| |deleteConversation|删除本地会话。| |getConversationInfo|获取会话信息。| |getConversationList|获取会话列表。| |getMessageList|获取会话的消息列表。| |sendMessageReadReceipt|发送消息已读回执。| |setConversationActive|设置会话活动状态。| |setConversationNotDisturb|设置会话免打扰状态。| |setConversationPinned|设置会话置顶状态。| |updateConversation|更新会话的信息。| |updateConversationProfile|更新会话的资源。|

呼叫

|API|说明| |--|--| |acceptCall|同意远端呼叫邀请。| |endCall|结束/挂断呼叫。| |getCallState|获取当前呼叫状态。| |joinCall|主动加入呼叫。| |makeCall|发起呼叫。| |rejectCall|拒绝远端呼叫邀请。|

事件

事件名称枚举可见ArIMClientEventsName。 事件列表枚举可见ArIMClientEvents。

|事件名称|API|说明| |--|--|--| |ArIMClientEventsName.CALL_ENDED|OnEndCall|呼叫结束通知。| |ArIMClientEventsName.CALL_MEMBER_JOIN|OnCallMemberJoin|呼叫成员加入通知。| |ArIMClientEventsName.CALL_MEMBER_LEAVE|OnCallMemberLeave|呼叫成员离开通知。| |ArIMClientEventsName.CALL_MEMBER_STATE|OnCallMemberState|呼叫成员状态通知。| |ArIMClientEventsName.CALL_RECEIVED|OnCallMemberLeave|呼叫成员加入通知。| |ArIMClientEventsName.CONNECTION_STATUS|OnConnectionStatus|网络状态变化通知。| |ArIMClientEventsName.CONVERSATION_CALL_BEGINNING|OnConversationCallBeginning|群呼进行中的通知。| |ArIMClientEventsName.CONVERSATION_CALL_ENDED|OnConversationCallEnded|群呼结束通知。| |ArIMClientEventsName.CONVERSATION_CREATED|OnConversationCreated|新会话通知。| |ArIMClientEventsName.CONVERSATION_DELETED|OnConversationDeleted|会话被删除通知。| |ArIMClientEventsName.CONVERSATION_INFO_UPDATED|OnConversationInfoUpdated|会话信息变更通知。| |ArIMClientEventsName.JOIN_CALL_RESULT|OnJoinCallResult|加入呼叫结果的通知。| |ArIMClientEventsName.KICKED_OUT|OnCallMemberLeave|呼叫成员加入通知。| |ArIMClientEventsName.MESSAGE_RECEIVED|OnMessageReceived|新消息通知。| |ArIMClientEventsName.MESSAGE_STATUS|OnMessageStatus|发送的消息状态通知。| |ArIMClientEventsName.NEW_REPORT_EVENT|OnNewReportEvent|新事件通知。|

Usage

1. 创建客户端实例

import { create, type CreateOptions } from 'ar-im';

const options: CreateOptions = {
  appID: 'YOUR_APPID',
  mimIdx: 'YOUR_INDEX',
};
const im = create(options);

2. 监听事件

监听事件，应当在创建实例之后保证全局只监听一次，否则当事件广播触发后，就会广播多次（即监听次数），如果只需要监听一次，可以使用 once, 具体参考EventEmitter。

import {
  Message,
  TextMessage,
  ArIMClientEventsName,
  ConnectionStatus,
  DisconnectReason
} from 'ar-im';

const onNewMessage = (message: Message) => {
  if (message instanceOf TextMessage) {
    const { text } = message.payload;
    console.log('收到新的文字消息:', text);
  }
  // TODO
};
const onConnectionStatus = (currentState: ConnectionStatus, prevState: ConnectionStatus, reason?: DisconnectReason | string) => {
  // TODO
};

// 监听新消息通知
im.on(ArIMClientEventsName.MESSAGE_RECEIVED, onNewMessage);
// 监听连接状态变化
im.on(ArIMClientEventsName.CONNECTION_STATUS, onConnectionStatus);

3. 发送文字消息

import {
  createTextMessage,
} from 'ar-im';

const textMessage = createTextMessage({
  to: conversationId.value,
  conversationType,
  payload: {
    text: content.text!
  }
});
// 发送
im.sendMessage(message);

4. 发起呼叫

import {
  createTextMessage,
} from 'ar-im';

// 被呼叫的用户 ID
const userIds = ['123', '456'];
// 发送
im.makeCall(
  userIds,
  // 自定呼叫数据
  JSON.stringify({
    mediaType: 'audio', // audio or video
  }),
  {
    // 可选参数，呼叫等待时长（秒）
    wait: 60,
    // 可选参数，自定呼叫 ID
    // callId,
    // 可选参数，自定群组 ID
    // groupId
  }
);

完整 Demo

import {
  create,
  type CreateOptions,
  Message,
  TextMessage,
  createTextMessage,
  ArIMClientEventsName,
  ConnectionStatus,
  DisconnectReason,
  CallProfile
} from 'ar-im';

let im: ArIMClient || null = null;

const onNewMessage = (message: Message) => {
  if (message instanceOf TextMessage) {
    const { text } = message.payload;
    console.log('收到新的文字消息:', text);
  }
  // TODO
};
const onConnectionStatus = (currentState: ConnectionStatus, prevState: ConnectionStatus, reason?: DisconnectReason | string) => {
  // TODO
};
const onCallInvite = (callProfile: CallProfile) => {
  // TODO
};
const init = async (userId: string) => {
  const options: CreateOptions = {
    appID: 'YOUR_APPID',
    mimIdx: 'YOUR_INDEX',
  };
  im = create(options);
  // 监听新消息通知
  im.on(ArIMClientEventsName.MESSAGE_RECEIVED, onNewMessage);
  // 监听连接状态变化
  im.on(ArIMClientEventsName.CONNECTION_STATUS, onConnectionStatus);
  // 监听呼叫邀请
  im.on(ArIMClientEventsName.CALL_RECEIVED, onCallInvite);

  await im.login({
    userID: userId,
    userName: '',
    userAvatar: ''
  });
};

const destroy = () => {
  im.logout();
  // 取消监听新消息通知
  im.off(ArIMClientEventsName.MESSAGE_RECEIVED, onNewMessage); // 保证 this 指向，否则无法取消监听
  // 取消监听连接状态变化
  im.off(ArIMClientEventsName.CONNECTION_STATUS, onConnectionStatus);
  // 取消监听呼叫邀请
  im.off(ArIMClientEventsName.CALL_RECEIVED, onCallInvite);
  im = null;
}