====== Web IM 集成介绍 ======

===== 准备条件 =====

**如果要实现RTC功能，你需要满足以下条件：**

   * **你已分别创建了环信应用及声网应用**
   * **已完成环信IM的基本功能，包括登录、好友、群组以及会话等的集成**
   * **上线之前开通声网token验证时，用户需要实现自己的AppServer，根据环信ID,生成Token，创建Token服务及使用AppServer生成Token的过程参见https://docs.agora.io/cn/live-streaming/token_server**
   * **我们提供了开源的AppServer，可以供参考：https://github.com/easemob/easemob-im-app-server/tree/master/agora-app-server**

===== 搭建本地测试环境 =====

搭建环境之前需要对环信提供的参考文档有个初步的了解，主要为以下形式，请根据下面的关键字选择源码参考  
  * 基于 react 开发的完整的实时 Demo ，关键字：**至少 IE9** ，**完整流程**，**webpack+react**


1. 首先将本源码克隆到本地

<code bash>
$ git clone https://github.com/easemob/webim.git
</code>

2. 去官网安装[[https://nodejs.org/zh-cn/|NodeJS]]，建议4+

  * 因为整套代码需要依赖于[[https://www.npmjs.com/|npm]] NodeJS 的包管理工具，安装 NodeJS 会默认安装 NPM 工具

3. 定位到 webim/demo 目录 在终端执行下面的命令，安装测试所需要的依赖模块

  * 保证此过程没有 error 终止为成功，如果有错误中断，请保留错误日志并再次尝试，大多数情况是网络原因导致的无法连接而中断

<code bash>
npm i
</code>

4. 上述步骤成功后

<code bash>
# 启动测试环境
npm start （如果需要https 通过HTTPS=true npm start启动）
# 打包发布，发布后文件在 webim/demo/build 目录下
npm run build
</code>

5. 浏览器访问即可看到测试页面：
  * http：http://localhost:3000/
 
  * https：https://localhost:3001/

===== 集成 =====

可以通过以下2种方式引用 Web SDK:
  * 使用 NPM
 
  * 将文件复制到本地，引用本地文件



==== NPM ====

Web SDK已发布到[[https://www.npmjs.com/package/easemob-websdk|NPM]]。采用如下方法集成：

1. 通过 NPM 安装 Web SDK。

<code>
npm install easemob-websdk --save
</code>

2. 先 import ，再访问 Web IM 。

<code javascript>
import websdk from "easemob-websdk"
</code>

如果是 Typescript, 这样引入类型 EasemobChat：
<code javascript>
import websdk, { EasemobChat } from 'easemob-websdk'
</code>

**注：**该方式只引用了 Web SDK ，仍需在项目里配置 WebIMConfig 文件内的参数，用于实例化 websdk。

====引用本地文件====

1. 下载demo后，将sdk目录下的 webimSDK.js(现SDK包命名为websdk+版本号的形式,例如：websdk3.4.2.js)、EMedia_x1v1.js、EMedia_sdk-dev.js，按照实际项目需求选择对应的SDK拷贝到系统相应的目录下。**PS：websdk：提供全功能即时通讯SDK接口，Emedia:提供音视频功能相关SDK接口。如需音视频功能，EMedia_x1v1.js与EMedia_sdk-dev.js只引用EMedia_x1v1.js即可**。

2.新版本中 WebIMConfig 文件只做参数定义方便实例化 SDK 时使用，仅与自己项目结构有关。详细使用可以查看 /demo/src/config/WebIM.js文件

3. 新建 html 文件并引入相关 js 脚本。

<code html>
<script type='text/javascript' src='WebIMConfig.js'></script>
<script type='text/javascript' src='webimSDK.js'></script>
</code>

**注意：**Web SDK 向下兼容V1.1.2和V1.1.1。关于详细的引用文件和配置参数（WebIMConfig）的方法，请查看本页“兼容性”的内容。

初始化 WebIM.connection 和 构造消息 WebIM.message， 需要在中间加上 default,如：WebIM.default.message。


===== 配置 =====
3.0 SDK，在 WebIMConfig.js 文件内进行以下配置：
<code javascript>
socketServer: '//im-api-v2.easemob.com/ws',    // socket Server地址

restServer: '//a1.easemob.com',               // rest Server地址

appkey: 'easemob-demo#chatdemoui',        // App key

https : false,                            // 是否使用https

isHttpDNS: true,                          // 3.0 SDK支持，防止DNS劫持从服务端获取XMPPUrl、restUrl

isMultiLoginSessions: false,              // 是否开启多页面同步收消息，注意，需要先联系商务开通此功能

isDebug: false,                           // 打开调试，会自动打印log，在控制台的console中查看log

autoReconnectNumMax: 2,                   // 断线重连最大次数

heartBeatWait: 30000,                     // 心跳间隔（只在小程序中使用）

delivery: false,                           // 是否发送已读回执

useOwnUploadFun: false,         // 是否使用自己的上传方式（如将图片文件等上传到自己的服务器，构建消息时只传url）

deviceId: 'webim'               // 设备ID，默认可不传，如果传一个固定值，在没开启多端登录的情况下同一个账号会互踢
</code>

''注意：''

''为满足不同客户的业务需求，环信在多地部署了数据中心。不同数据中心的REST API请求域名、WebSocket访问域名不同。请根据您所在数据中心进行配置。''

''环信不同数据中心的REST API请求域名、WebSocket访问域名： ''
|数据中心|REST API请求地址|WebSocket访问域名|
|国内1区|a1.easemob.com 或 a1.easecdn.com|im-api-v2.easemob.com 或 im-api-v2.easecdn.com|
|国内2区|a31.easemob.com 或 a31.easecdn.com|im-api-v2-31.easemob.com 或 im-api-v2-31.easecdn.com|
|国内VIP区|请咨询商务经理|请咨询商务经理|
|客服专用|请咨询商务经理|请咨询商务经理|
|新加坡1区|a1-sgp.easemob.com 或 a1-sgp.easecdn.com|im-api-sgp-v2.easemob.com 或 im-api-sgp-v2.easecdn.com|
|美东1区|a41.easemob.com 或 a41.easecdn.com|msync-api-41.easemob.com 或 msync-api-41.easecdn.com|
|法兰克福1区|a51.easemob.com 或 a51.easecdn.com|msync-api-51.easemob.com 或 msync-api-51.easecdn.com|
'' 应用所在数据中心可以在环信用户管理后台>应用信息中查看：[[https://console.easemob.com/app/im-service/detail|Console中查看请求域名]] ''

{{:im:server:ready:console查看可用区.jpg?800|}}

2.0 SDK，在 webim.config.js 文件内进行以下配置：

<code javascript>
xmppURL: '//im-api.easemob.com',           // xmpp Server地址，对于在console.easemob.com创建的appKey，固定为该值  
                                          
apiURL: 'http://a1.easemob.com',           // rest Server地址，对于在console.easemob.com创建的appkey，固定为该值  
                                          
appkey: 'easemob-demo#chatdemoui',         // App key

https : false,                             // 是否使用https

isHttpDNS: true,                           // 防止DNS劫持从服务端获取XMPPUrl、restUrl

isMultiLoginSessions: false,               // 是否开启多页面同步收消息，注意，需要先联系商务开通此功能

isDebug: false,                            // 打开调试，会自动打印log，在控制台的console中查看log

autoReconnectNumMax: 2,                    // 断线重连最大次数

autoReconnectInterval: 3,                  // 断线重连每次尝试连接的间隔

heartBeatWait: 30000,                      // 使用webrtc（视频聊天）时发送心跳包的时间间隔，单位ms

delivery: true,                            // 是否发送已读回执

</code>
**注：**建议 xmppURL、apiURL、https 三个参数统一，否则 IE9 以下会报**拒绝访问**的错误。


**例：**

  * https: false
<code javascript>
xmppURL: 'im-api.easemob.com',

apiURL: 'http://a1.easemob.com',

appkey: 'easemob-demo#chatdemoui',

https : false, 

isMultiLoginSessions: false

isAutoLogin: true

</code>

  * https: true

<code javascript>
xmppURL: 'im-api.easemob.com',

apiURL: 'https://a1.easemob.com',

appkey: 'easemob-demo#chatdemoui',

https : true, 

isMultiLoginSessions: false 

isAutoLogin: true

</code>

===== 兼容性 =====

==== 兼容V1.1.2 ====

Web SDK V1.4.5 向下兼容 V1.1.2。如果直接用 V1.1.2 的 Demo 嵌入 V1.4.5 的 SDK ，需要修改旧的 webim.config.js，在第一行''WebIM.config = {''的前面插入一行''var WebIM = {};''。完成后，示例如下：

<code javascript>
  var WebIM = {};
  WebIM.config = {
</code>

==== 兼容V1.1.1 ====

Web SDK V1.4.5 向下兼容 V1.1.1。从V1.1.1升级到V1.4.5时，需要做如下操作：

=== 第1步：修改引入的 SDK 文件 ===

1. 下载 Web SDK V1.4.5 并解压后，将 /sdk/dist/websdk-1.4.5.js 和 /sdk/disk/websdk.shim.js 拷贝到系统相应的目录下。

2. 在原来的引用 SDK 的 html 文件中增加一行代码 ''window.WebIM = {};'' ，并使用上述两个文件替换原来引用的 SDK 的 js 文件。

替换前：

<code html>
<!--sdk相关的js-->
<script type='text/javascript' src='static/sdk/strophe.js'></script>
<script type='text/javascript' src='static/sdk/easemob.im-1.1.1.js'></script>
<script type='text/javascript' src='static/sdk/easemob.im.shim.js'></script>
<!--webim相关配置-->
<script type='text/javascript' src='static/js/easemob.im.config.js'></script>
</code>

替换后：

<code html>
<!--sdk相关的js-->
<script type='text/javascript' src='static/sdk/strophe.js'></script>
<script>
    window.WebIM = {};       // 这行代码需要加在引用strophe.js文件的代码后面
</script>
<script type='text/javascript' src='static/sdk/websdk-1.4.5.js'></script>
<script type='text/javascript' src='static/sdk/websdk.shim.js'></script>
<!--webim相关配置-->
<script type='text/javascript' src='static/js/easemob.im.config.js'></script>
</code>

3. 将 easemob.im.config.js 文件中的参数 ''multiResources'' 修改为 ''isMultiLoginSessions'' 。

=== 第2步：修改 websdk-1.4.5.js 文件 ===

1. 在 SDK 文件下搜索''%%/%%%%/%%class''，将下面的''connection = function connection(options)'' 改成''window.WebIM.connection = function connection(options)''

2. 在 SDK 文件下搜索''connection.prototype.registerUser = function (options)''，在上面一行添加''var connection = window.WebIM.connection;''


----
<WRAP group>
<WRAP half column>
上一页：[[im:web:intro:start|Web IM 介绍]]
</WRAP>

<WRAP half column>
下一页：[[im:web:intro:basic|初始化及登录]]
</WRAP>
</WRAP>