文档中心

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

前提条件

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

集成环境

具体见 开发环境要求。

引入 SDK

对于 JavaScript SDK，导入代码如下：

import EC from 'easemob-websdk'; 

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

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

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

示例代码如下：

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 参数说明：

注册用户

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

控制台注册

登录环信即时通讯云控制台 (opens new window)，选择即时通讯 > 运营服务 > 用户管理，创建 IM 用户。

REST API 注册

请参考 注册用户。

SDK 注册

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

conn.registerUser({ /** 用户 ID。 */ username: string, /** 密码。 */ password: string, /** 显示昵称。

用于移动端推送的时候通知栏显示。 */ nickname: string, }).then((res) => { console.log(res) }) 

用户登录

目前登录服务器有两种方式：

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

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

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

手动登录

用户 ID +密码 登录是传统的登录方式。用户 ID 和密码都是你的终端用户自行决定，密码需要符合密码规则要求。

conn .open({ user: "username", pwd: "password", }) .then(() => { console.log("login success"); }) .

catch((reason) => { console.log("login fail", reason); }); 

用户 ID + token 是更加安全的登录方式。token 可以通过调用 REST API 获取，详见 环信用户 token 的获取。

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

 .catch((reason) => { console.log("login fail", reason); }); 

自动登录（Web SDK 暂不支持）

在初始化的时候，可以设置是否自动登录。如果设置为自动登录，则登录成功之后，后续启动初始化的时候会自动登录，登录结果通过回调返回。

退出登录

conn.close(); 

连接状态相关

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

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

() => { console.log("onDisconnected"); }, onTokenWillExpire: () => { console.log("onTokenWillExpire");

 }, onTokenExpired: () => { console.log("onTokenExpired"); }, }); 

断网自动重连

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

被动退出登录

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

输出信息到日志文件

开启日志输出：

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();