HarmonyOS 访客端SDK集成

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

SDK介绍

前提条件

DevEco Studio 5.0.0 Release（5.0.3.906）及以上；
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 5.0.0 Release（5.0.3.906）示例

2. 集成 SDK

打开 SDK 下载链接，获取最新版的环信客服云访客端 HarmonyOS SDK，得到 har 形式的 SDK 文件。
将 SDK 文件，拷贝到 Harmony 工程，例如放至 HelloWorld 工程下 entry 模块下的 libs 目录。
在工程 build-profile.json5 中设置支持字节码 HAR 包

{
  "app": {
    "products": [
      {
         "buildOption": {
           "strictMode": {
             "useNormalizedOHMUrl": true
           }
         }
      }
    ]
  }
}

修改模块目录的 oh-package.json5 文件，在 dependencies 节点增加依赖声明。

{
  "name": "entry",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {
    "VisitorSdk": "file:libs/visitorsdk-v1.0.0.har"
  }
}

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

3. 添加项目权限

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

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

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

实现消息发送

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

1. SDK 初始化

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

//初始化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)

2. 创建账号

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

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

3. 登录账号

使用如下代码实现用户登录：

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

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

4. 绑定/解绑IM服务号

在发送消息前调用绑定，在退出聊天时调用解绑

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

5. 发送消息

以发送文本消息为例：

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

监听消息接收

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

退出登录

VisitorClient.getInstance()
        .getVisitorManager()
        .logout()
        .then(() => {
          //退出成功
        })

监听连接状态

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

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)

断网自动重连

如果由于网络信号弱、切换网络等引起的连接终端，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 默认输出调试信息（所有日志，包括调试信息、警告和错误），如果只需输出错误日志，需要关闭日志输出。

关闭日志输出

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

获取本地日志

hdc file recv /data/app/el2/100/base/{应用包名}/{AppKey}/core_log

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

离线推送

开通推送服务与配置 Client ID

在华为开发者后台创建应用、开启推送服务、上传对应的证书指纹。详见华为官方介绍：[开通推送服务](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/push-config-setting-V5)

上传推送证书

在IM Console后台上传推送证书，选择你的应用 > 即时通讯 > 功能配置 > 消息推送 > 证书管理。点击添加推送证书，在添加推送证书窗口选择鸿蒙页签，然后设置推送证书相关参数。

推送证书参数：

证书名称，鸿蒙ClientId，必填，与鸿蒙app设置一致，详见[创建服务账号密钥](https://developer.huawei.com/consumer/cn/doc/start/api-0000001062522591#section11695162765311)
上传文件，上传 JSON 推送证书，必填，即服务账号的密钥文件，请在选择启用推送服务后，再生成服务器密钥。
Category，通知类别，选填，详见[申请通知消息自分类权益](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/push-apply-right-V5#section16708911111611)
Action，选填，消息接收方在收到离线推送通知时单击通知栏时打开的应用指定页面的自定义标记。

初始化配置推送 Client ID

let mVisitorOptions = new VisitorOptions();
    mVisitorOptions.setPushAppId('${Harmony Client ID}')
    VisitorClient.getInstance().init(context, mVisitorOptions)

监听 Push Token 上传结果

let pushListener: VisitorPushListener = {
        onError: (error: VisitorError): void => {
          console.info(`pushListener onError: ${JSON.stringify(error)}`)
        },
        onBindTokenSuccess: (token: string): void => {
          console.info(`pushListener onSuccess: ${token}`)
        }
    }
    VisitorClient.getInstance().addPushListener(pushListener)