====== HarmonyOS 访客端SDK集成 ======

  * 环信客服云（Customer Engagement Cloud, CEC）现已推出专属 HarmonyOS SDK！您只需在客服云创建 APP 关联，并按照本文档的步骤集成 HarmonyOS SDK，即可轻松实现 HarmonyOS 版 APP 接入。
  * 您在集成过程中有遇到任何问题，请联系我们为您提供技术支持服务！

===== SDK介绍 =====

==== 前提条件 ====

  * DevEco Studio NEXT Developer Beta3（5.0.3.600）及以上；
  * HarmonyOS SDK API 12 及以上；
  * 有效的环信客服云账号和坐席接入App关联信息。

==== 准备开发环境 ====

本节介绍如何创建项目，将环信客服云访客端 HarmonyOS SDK 集成到你的项目中，并添加相应的设备权限。

=== 1. 创建 HarmonyOS 项目 ===

> 参考以下步骤创建一个 HarmonyOS 项目。

  * 打开 DevEco Studio，点击 Create Project。
  * 在 Choose Your Ability Template 界面，选择 Application > Empty Ability，然后点击 Next。
  * 在 Configure Your Project 界面，依次填入以下内容：
  * Project name：你的 HarmonyOS 项目名称，如 HelloWorld。
  * Bundle name：你的项目包的名称，如 com.helpdesk.helloworld。
  * Save location：项目的存储路径。
  * Compatible SDK：项目的支持的最低 API 等级，选择 5.0.0(12) 及以上。
  * Module name：module的名称，默认为 entry。
  * 点击 Finish。根据屏幕提示，安装所需插件。

上述步骤使用 DevEco Studio NEXT Developer Beta3（5.0.3.600） 示例。

=== 2. 集成 SDK ===

  * 打开 SDK 下载链接，获取最新版的环信客服云访客端 HarmonyOS SDK，得到 har 形式的 SDK 文件。
  * 将 SDK 文件，拷贝到 Harmony 工程，例如放至 HelloWorld 工程下 entry 模块下的 libs 目录。
  * 修改模块目录的 oh-package.json5 文件，在 dependencies 节点增加依赖声明。
<code typescript>
{
  "name": "entry",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {
    "VisitorSdk": "file:libs/visitorsdk-v1.0.0.har"
  }
}
</code>

  * 最后单击 File > Sync and Refresh Project 按钮，直到同步完成。

=== 3. 添加项目权限 ===

在模块的 module.json5 ，例如：HelloWorld 中 entry 模块的 module.json5 中，配置示例如下：

<code typescript>
{
  "module": {
    "requestPermissions":[
      {
        "name" : "ohos.permission.INTERNET",
        "reason": "$string:Internet_reason",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when":"always"
        }
      },
      {
       "name": "ohos.permission.GET_NETWORK_INFO",
        ...
      },
    ],
  },
}

</code>

  * SDK所需权限为ohos.permission.INTERNET和ohos.permission.GET_NETWORK_INFO


==== 实现消息发送 ====

本节介绍如何实现消息发送:

=== 1. SDK 初始化 ===
避免重复初始化，如果进行多次初始化，仅第一次生效

<code typescript>
    //初始化sdk
    let mVisitorOptions = new VisitorOptions();
    mVisitorOptions
      .setKefuRestServer('${客服系统地址}')//选填，默认为：https://kefu.sh.absoloop.com
      .setAppkey('${AppKey}')//必填，坐席管理员模式下-接入-在线客服-App-关联信息-Appkey
      .setTenantId('${租户ID}')//必填，坐席管理员模式下-账户-账户信息-租户ID
      .setAppVersion('${app版本号}')//选填，建议填写，便于查问题
    VisitorClient.getInstance().init(mContext, visitorOptions)
</code>

=== 2. 创建账号 ===
根据业务需求，如需在访客端创建账号，可以使用如下代码注册访客账号：

<code typescript>
    VisitorClient.getInstance()
        .getVisitorManager()
        .register(username, password)
        .then((value: string)=>{//注册成功})
</code>

=== 3. 登录账号 ===
使用如下代码实现用户登录：

<code typescript>
    VisitorClient.getInstance()
        .getVisitorManager()
        .login(username, password)
        .then((value: string) => {
          //登录成功
        })
</code>


 *除了注册监听器，其他的 SDK 操作均需在登录之后进行。

=== 4. 绑定/解绑IM服务号 ===
在发送消息前调用绑定，在退出聊天时调用解绑

<code typescript>
    //绑定`toChatUsername` 为IM服务号。
    VisitorClient.getInstance().getVisitorManager().bindChat(toChatUsername)
    //解绑
    VisitorClient.getInstance().getVisitorManager().bindChat(toChatUsername)
</code>

=== 5. 发送消息 ===
以发送文本消息为例：

<code typescript>
    // `content` 为要发送的文本内容，`toChatUsername` 为IM服务号。
    let message = Message.createTxtSendMessage(content, toChatUsername);
    if(message){
        VisitorClient.getInstance().getVisitorManager().sendMessage(message)
    }
</code>

==== 监听消息接收 ====

<code typescript>
    let messageListener: MessageListener = {
        onMessage(msgs: ArrayList<Message>) {
          //收到上屏消息
        },
        onCmdMessage(msgs: ArrayList<Message>) {
          //收到cmd消息
        },
        onMessageStatusUpdate() {
          //消息状态改变
        },
        onMessageSent() {
          //消息已发送
        }
    };
    //添加消息监听
    VisitorClient.getInstance().getVisitorManager().addMessageListener(messageListener);
    //移除消息监听
    VisitorClient.getInstance().getVisitorManager().removeMessageListener(messageListener);
</code>


==== 退出登录 ====
<code typescript>
    VisitorClient.getInstance()
        .getVisitorManager()
        .logout()
        .then(() => {
          //退出成功
        })
</code>

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

<code typescript>
let connectListener: IMConnectListener = {
    onConnected: (): void => {
      // 长连接建立
    },
    onDisconnected: (errorCode: number): void => {
      // 长连接断开
      switch (errorCode) {
        case VisitorError.USER_NOT_FOUND:
        case VisitorError.USER_LOGIN_ANOTHER_DEVICE:
        case VisitorError.USER_AUTHENTICATION_FAILED:
        case VisitorError.USER_REMOVED:
          VisitorClient.getInstance().getVisitorManager().logout()
          //TODO 跳转到登录页面
          break;
      }
    }
  }
VisitorClient.getInstance().addConnectionListener(connectListener)

VisitorClient.getInstance().removeConnectionListener(connectListener)
</code>

==== 断网自动重连 ====

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

==== 被动退出登录 ====
你可以通过监听回调 ConnectionListener#onDisconnected 后，调用 #logout 进行退出并返回登录界面。

ConnectionListener#onDisconnected(number) 返回的 errorCode 有如下
  * VisitorError.USER_NOT_FOUND: 账号不存在
  * VisitorError.USER_LOGIN_ANOTHER_DEVICE: 账号在其他设备登录
  * VisitorError.USER_AUTHENTICATION_FAILED: 账号校验失败
  * VisitorError.USER_REMOVED: 账号被移除

==== 输出信息到日志文件 ====
  - 默认情况下，SDK 最多可生成和保存三个文件，easemob.log 和两个 easemob_YYYY-MM-DD_HH-MM-SS.log 文件。这些文件为 UTF-8 编码，每个不超过 2 MB。SDK 会将最新的日志写入 easemob.log 文件，写满时则会将其重命名为对应时间点的 easemob_YYYY-MM-DD_HH-MM-SS.log 文件，若日志文件超过三个，则会删除最早的文件。
  - 例如，SDK 在 2024 年 1 月 1 日上午 8:00:00 记录日志时会生成 easemob.log 文件，若在 8:30:00 将 easemob.log 文件写满则会将其重命名为 easemob_2024-01-01_08-30-00.log 文件，随后在 9:30:30 和 10:30:30 分别生成了 easemob_2024-01-01_09-30-30.log 和 easemob_2024-01-01_10-30-30.log 文件，则此时 easemob_2024-01-01_08-30-00.log 文件会被移除。
  - SDK 默认输出调试信息（所有日志，包括调试信息、警告和错误），如果只需输出错误日志，需要关闭日志输出。

==== 关闭日志输出 ====

<code typescript>
    //初始化时调用
    let mVisitorOptions = new VisitorOptions();
    mVisitorOptions.setConsoleLog(false)
    VisitorClient.getInstance().init(mContext, visitorOptions)
</code>

==== 获取本地日志 ====
  * 打开以下目录，获取本地日志。
<code typescript>
    hdc file recv /data/app/el2/100/base/{应用包名}/{AppKey}/core_log
</code>

  * 获取本地日志，需要将 {应用包名} 替换为应用的包名，例如 com.easemob.helpdesk；{AppKey} 需要替换为APP关联中的 AppKey。