概述

大约 4 分钟

概述

本页介绍 Web 集成相关内容。

前提条件

开始前,请注册有效的环信即时通讯 IM 开发者账号且获得 App key,见 环信即时通讯云管理后台open in new window

集成环境

具体见 开发环境要求

引入 SDK

对于 JavaScript SDK,导入代码如下:

import EC from "easemob-websdk";

对于 TypeScript SDK,导入代码如下, EasemobChat 是 SDK 类型的命名空间。

import EC, { EasemobChat } from "easemob-websdk";

如果对 SDK 大小有要求,可根据功能按需导入 SDK 文件。

功能导入文件使用方式
联系人和消息管理import * as contactPlugin from "easemob-websdk/contact/contact";miniCore.usePlugin(contactPlugin, "contact");
群组import * as groupPlugin from "easemob-websdk/group/group";miniCore.usePlugin(groupPlugin, "group");
聊天室import * as chatroomPlugin from "easemob-websdk/chatroom/chatroom";miniCore.usePlugin(chatroomPlugin, "chatroom");
子区import * as threadPlugin from "easemob-websdk/thread/thread";miniCore.usePlugin(threadPlugin, "thread");
翻译import * as translationPlugin from "easemob-websdk/translation/translation";miniCore.usePlugin(translationPlugin, "translation");
在线状态订阅import * as presencePlugin from "easemob-websdk/presence/presence";miniCore.usePlugin(presencePlugin, "presence");

示例代码如下:

import MiniCore from "easemob-websdk/miniCore/miniCore";
import * as contactPlugin from "easemob-websdk/contact/contact";

const miniCore = new MiniCore({
  appKey: "your appKey",
});

// "contact" 为固定值
miniCore.usePlugin(contactPlugin, "contact");

// 获取联系人列表
miniCore.contact.getContacts();

// 添加监听事件
miniCore.addEventHandler("handlerId", {
  onTextMessage: (message) => {},
});

// 登录
miniCore.open({
  username: "username",
  password: "password",
});

SDK 初始化

使用 SDK 前需要进行初始化,示例代码如下:

const conn = new EC.connection({
  appKey: "your appKey",
});

初始化 SDK 参数说明:

参数类型是否必需描述
appKeyString环信即时通讯云控制台为你的应用生成的唯一标识,由应用名称(Appname)和组织名称(Orgname)组成。
isHttpDNSBool是否开启 DNS,防止 DNS 劫持。
-(默认)true:开启 DNS;
- false:关闭 DNS。
deliveryBool是否开启送达回执:
- true:开启;
-(默认)false:关闭。
httpsBool是否支持通过 HTTPS 访问即时通讯 IM:
- (默认)true:支持 HTTPS 和 HTTP;
-false:浏览器根据使用的域名自行判断。
heartBeatWaitInt心跳间隔,单位为毫秒,默认为 30000。
deviceIdString设备 ID,为默认随机值。
useOwnUploadFunBool是否支持通过自己的路径将图片、文件上传到自己的服务器。
-true:支持,需要指定路径;
-(默认)false:关闭,通过消息服务器上传下载文件。
autoReconnectNumMaxInt最大重连次数。

注册用户

本节介绍三种用户注册方式。

控制台注册

通过控制台注册用户,详见创建 IM 用户

REST API 注册

请参考 注册用户

SDK 注册

若支持 SDK 注册,需登录环信即时通讯云控制台open in new window,选择 即时通讯 > 服务概览,将 设置下的 用户注册模式 设置为 开放注册

conn
  .registerUser({
    /** 用户 ID。 */
    username: string,
    /** 密码。 */
    password: string
  })
  .then((res) => {
    console.log(res);
  });

提示

该注册模式为在客户端注册,旨在方便测试,并不推荐在正式环境中使用。

用户登录

SDK 不支持自动登录,只支持通过以下方式手动登录:

  • 用户 ID + 密码
  • 用户 ID + token

登录时传入的用户 ID 必须为 String 类型,支持的字符集详见用户注册的 RESTful 接口

调用登录接口后,收到 onConnected 回调表明 SDK 与环信服务器连接成功。

  1. 用户 ID +密码 登录是传统的登录方式。用户 ID 和密码都是你的终端用户自行决定,密码需要符合密码规则要求。
conn
  .open({
    user: "username",
    pwd: "password",
  })
  .then(() => {
    console.log("login success");
  })
  .catch((reason) => {
    console.log("login fail", reason);
  });
  1. 用户 ID + token 是更加安全的登录方式。token 可以通过调用 REST API 获取,详见 环信用户 token 的获取

提示

使用 token 登录时需要处理 token 过期的问题,比如在每次登录时更新 token 等机制。

conn
  .open({
    user: "username",
    accessToken: "token",
  })
  .then(() => {
    console.log("login success");
  })
  .catch((reason) => {
    console.log("login fail", reason);
  });

登录重试机制如下:

  • 登录时,若服务器返回明确的失败原因,例如,token 不正确,SDK 不会重试登录。
  • 若登录因超时失败,SDK 会重试登录。

退出登录

conn.close();

连接状态相关

你可以通过注册连接监听器确认连接状态。

conn.addEventHandler("handlerId", {
  onConnected: () => {
    console.log("onConnected");
  },
  onDisconnected: () => {
    console.log("onDisconnected");
  },
  onTokenWillExpire: () => {
    console.log("onTokenWillExpire");
  },
  onTokenExpired: () => {
    console.log("onTokenExpired");
  },
});

断网自动重连

如果由于网络信号弱、切换网络等引起的连接中断,系统会自动尝试重连。重连成功或者失败分别会收到 onConnectedonDisconnected 通知。

被动退出登录

对于 onDisconnected 通知,错误码(errorCode)可能为以下几种,建议 App 返回登录界面。

错误码描述
WEBIM_CONNCTION_USER_LOGIN_ANOTHER_DEVICE=206用户已经在其他设备登录。
WEBIM_CONNCTION_USER_REMOVED=207用户账户已经被移除。
WEBIM_CONNCTION_USER_KICKED_BY_CHANGE_PASSWORD=216由于密码变更被踢下线。
WEBIM_CONNCTION_USER_KICKED_BY_OTHER_DEVICE=217由于其他设备登录被踢下线。

输出信息到日志文件

开启日志输出:

logger.enableAll();

关闭日志输出:

logger.disableAll();

设置日志输出等级:

// 0 - 5 或者 'TRACE','DEBUG','INFO','WARN','ERROR','SILENT';
logger.setLevel(0);

设置缓存日志:

logger.setConfig({
  useCache: false, // 是否缓存
  maxCache: 3 * 1024 * 1024, // 最大缓存字节
});
// 缓存全部等级日志
logger.setLevel(0);

下载日志:

logger.download();