概述

大约 5 分钟

概述

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

前提条件

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

集成环境

具体见开发环境要求。

引入 SDK

（推荐）按需导入 SDK 文件。为了减少 SDK 体积，推荐这种方式，详见按需引入 SDK 功能模块。
对于 JavaScript SDK，导入代码如下：

import EC from "easemob-websdk";

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

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

对于服务端渲染框架, 如 Nuxt、Next 等，需要在客户端渲染阶段引入 SDK。

Nuxt 项目, 你可以在 mounted 生命周期动态导入 SDK：

export default {
  mounted: () => {
    import("easemob-websdk").then((res) => {
      const EC = res.default;
      console.log(EC, "easemob websdk");
      const conn = new EC.connection({
        appKey: "your appkey"
      });
    });
  }
};

Next 项目, 要使用客户端组件，你可以在文件顶部的导入上方添加 use client 指令。

'use client'
 
import { useEffect } from 'react'
 
export default function Home() {
  useEffect(() => {
    import('easemob-websdk').then((res)=>{
      const EC = res.default;
      console.log(EC, "easemob websdk");
      const conn = new EC.connection({
        appKey: "your appkey"
      });
    }) 
  }, [])
}

SDK 初始化

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

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

初始化 SDK 参数说明：

参数	类型	是否必需	描述
`appKey`	String	是	环信即时通讯云控制台为你的应用生成的唯一标识，由应用名称（`Appname`）和组织名称（`Orgname`）组成。
`isHttpDNS`	Bool	否	是否开启 DNS，防止 DNS 劫持。 -（默认）`true`：开启 DNS； - `false`：关闭 DNS。
`delivery`	Bool	否	是否开启送达回执： - `true`：开启； -（默认）`false`：关闭。
`https`	Bool	否	是否支持通过 HTTPS 访问即时通讯 IM： - （默认）`true`：支持 HTTPS 和 HTTP； -`false`：浏览器根据使用的域名自行判断。
`heartBeatWait`	Int	否	心跳间隔，单位为毫秒，默认为 30000。
`deviceId`	String	否	设备 ID，为默认随机值。
`useOwnUploadFun`	Bool	否	是否支持通过自己的路径将图片、文件上传到自己的服务器。 -`true`：支持，需要指定路径； -（默认）`false`：关闭，通过消息服务器上传下载文件。
`autoReconnectNumMax`	Int	否	最大重连次数。

注册用户

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

控制台注册

通过控制台注册用户，详见创建 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 与环信服务器连接成功。

用户登录流程详见用户注册与登录的产品说明文档。

用户 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 的获取。

提示

使用 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");
  },
  // 自 4.8.0 版本，`onDisconnected` 事件新增断开原因回调参数, 告知用户触发 `onDisconnected` 的原因。
  onDisconnected: () => {
    console.log("onDisconnected");
  },
  onTokenWillExpire: () => {
    console.log("onTokenWillExpire");
  },
  onTokenExpired: () => {
    console.log("onTokenExpired");
  },
  // 连接成功，开始从服务器拉取离线消息时触发。
  // 注意：如果本次登录服务器没有离线消息，不会触发该回调。
  onOfflineMessageSyncStart: () => {
    console.log("onOfflineMessageSyncStart");
  },
  // 离线用户上线后从服务器拉取离线消息结束时触发。
  // 注意：如果再拉取离线过程中因网络或其他原因导致连接断开，不会触发该回调。
  onOfflineMessageSyncFinish: () => {
    console.log("onOfflineMessageSyncFinish");
  },
});

断网自动重连

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

你可以设置最大重连次数 autoReconnectNumMax，该参数默认为 5 次。

被动退出登录

对于 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.setConsoleLogVisibility(false)

监听 SDK 日志事件：

logger.onLog = (log)=>{
  console.log('im logger', log)
}

关闭日志输出：

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

日志上报

自 4.8.1 版本，Web SDK 支持日志上报功能, 即将日志会上传到环信的服务器。该功能默认关闭，如有需要, 可联系商务开通。

概述

# 概述

# 前提条件

# 集成环境

# 引入 SDK

# SDK 初始化

# 注册用户

# 控制台注册

# REST API 注册

# SDK 注册

# 用户登录

# 退出登录

# 连接状态相关

# 断网自动重连

# 被动退出登录

# 输出信息到日志文件

# 日志上报

概述