Live800 鸿蒙访客端SDK开发指南 -harmony

本文档仅适用于 DevEco-Studio 环境的harmony 开发人员。

编译环境

DevEco Studio NEXT Release(5.0.3.900) 及以上。
HarmonyOS SDK API 12 及以上。
手机系统版本号：OpenHarmony-5.0.0

1.创建应用

请与Live800PC版本后台,自行创建 SDK 应用。创建好应用后，获取到的有效的 AppKey、 ServerUrl 和 AppSecret，将用于 SDK 的对话配置（如果 PC 端没有显示 ServerUrl，请联系Live800技术支持）。

获取接口加密秘钥 AppSecret

可通过 PC 客服端”系统设置 -> 接口地址 -> 接口加密密钥“查看
ps:请确认PC客服端是最新版本，否则会导致AppSecret不显示。

2.导入SDK

Live800 SDK 提供的压缩包中包含：visitorsdk.har、开发指南和 sdk Demo 代码。

步骤一：将Live800提供的visitorsdk.har放入主项目的lib目录下，如果没有该目录，你需要自行进行创建。

步骤二：在主项目中的 oh-package.json5 文件添加对har 包的依赖


3
1
  "dependencies": {
2
    "live800sdk": "file:./lib/visitorsdk.har"
3
  },

步骤三：在主项目中的module.json5中添加一下权限


33
1
    "requestPermissions":[
2
      {
3
        "name" : "ohos.permission.INTERNET",
4
        "reason": "$string:request_permission_internet_reason",
5
        "usedScene": {
6
          "abilities": [
7
            "EntryAbility"
8
          ],
9
          "when":"always"
10
        }
11
      },
12
      {
13
        "name" : "ohos.permission.CAMERA",
14
        "reason": "$string:request_permission_camera_reason",
15
        "usedScene": {
16
          "abilities": [
17
            "EntryAbility"
18
          ],
19
          "when":"inuse"
20
        }
21
      },
22
      {
23
        "name" : "ohos.permission.MICROPHONE",
24
        "reason": "$string:request_permission_microphone_reason",
25
        "usedScene": {
26
          "abilities": [
27
            "EntryAbility"
28
          ],
29
          "when":"inuse"
30
        }
31
      }
32
    ]
33

3.快速接入

SDK 用户只需要关心 sdkManager 与 UserInfo 两个类。sdkManager 用于 SDK 的全局配置，包括初始化、打开对话页面、修改主题色等。UserInfo 用于访客属性配置，包括访客 id、访客姓名、访客头像等信息。

3.1.初始化

在您想要进入客服页面前，您对SDK进行初始化，必须进行以下四项设置:

A.设置服务器地址 (服务器同时支持 http 和 https)

sdkManager.setServerUrl(this.serverUrl)

B.设置 appkey

sdkManager.setAppKey(this.appKey)

C.设置 appSecret

sdkManager.setAppSecret(this.appSecret)

D.设置UserInfo

sdkManager.setUserInfo(this.createUserInfo())


20
1
createUserInfo(): UserInfo {
2
  let userInfo = new UserInfo()
3
  userInfo.guestId = this.guestId
4
  userInfo.userPhotoWebUrl =
5
    'http://g.hiphotos.baidu.com/zhidao/pic/item/c8177f3e6709c93d3ed256fd9c3df8dcd1005493.jpg'
6
  userInfo.userId = this.userId
7
  if (this.userId.length > 5) {
8
    userInfo.name = '鸿蒙-' + this.userId.slice(0, 5)
9
  } else {
10
    userInfo.name = '鸿蒙-' + this.userId
11
  }
12
  userInfo.grade = '1'
13
  userInfo.mobileNo = '18408271111'
14
  userInfo.gender = '男'
15
  userInfo.memo = '鸿蒙访客-备注信息'
16
  userInfo.loginName = '鸿蒙访客-登录名'
17
  userInfo.additionalOther = '鸿蒙访客-预留字段additionalOther'
18
  userInfo.other = '鸿蒙访客-预留字段other'
19
  return userInfo
20
}

3.2.进入对话页面

完成初始化及必要设置后，调用以下方法进入客服对话页面（对应于 Demo 的 Index 类中的内容）：

sdkManager.startServer()

示例：


21
1
  build() {
2
    RelativeContainer() {
3
      Text(this.message)
4
        .fontSize(50)
5
        .fontWeight(FontWeight.Bold)
6
        .alignRules({
7
          center: { anchor: '__container__', align: VerticalAlign.Center },
8
          middle: { anchor: '__container__', align: HorizontalAlign.Center }
9
        })
10
        .onClick(() => {
11
          sdkManager.setServerUrl(this.serverUrl)
12
          sdkManager.setAppKey(this.appKey)
13
          sdkManager.setAppSecret(this.appSecret)
14
          sdkManager.setUserInfo(this.createUserInfo())
15
          sdkManager.startServer()
16
        })
17
    }
18
    .height('100%')
19
    .width('100%')
20
  }
21

4.API介绍

4.1 UserInfo介绍

设置访客信息 UserInfo，可以配置访客姓名、备注信息、IP地址等内容，这些信息将会上传给 Live800 服务器用于业务逻辑或展示。下面分别进行介绍说明（附加 * 号的为重点关注项）。

4.1.1访客ID*

userId 和 guestId 的使用场景如下：
当用户未登陆app时，为匿名访客，然后进入客服对话页面，并与客服产生对话消息（仅设置了 guestId，并未设置 userId）；
然后，该访客登陆app，成为受信任访客，并联系客服（guestId 和 userId 均设置了）；
如果1和2设置的 guestId 为同一个值，服务器将会识别为同一个访客，并将1产生的对话消息带给2。

登录用户ID

UserInfo 的 userId 属性代表登陆用户ID ，用于识别登陆用户（受信任访客）的身份。如果当前用户不是登陆用户，则忽略这个属性。可以使用您 App 中的用户ID来作为 userId，设置这个属性以后，SDK会自动将当前访客识别为信任访客。


4
1
let userInfo = new UserInfo()
2
//1.为了保证唯一性，可以使用您App中的用户id来作为userId
3
//2.userId的长度不能超过50个字符
4
userInfo.userId = this.userId

游客ID

LIVUserInfo 的 guestId 属性代表游客ID（或未登陆用户的ID）。游客ID应该储在 App 中，并确保同一个游客用户（在同一个手机上）每次咨询客服使用同一个 guestId ，不同手机的游客用户 guestId 不同。相同的 guestId ，接入对话，在客服端上会认为是同一个游客。游客ID，可以用 UUID 来保证唯一性。如果您不想管理 guestId ，可以不用设置，SDK内部会生成默认的 guestId 。


4
1
let userInfo = new UserInfo()
2
//1.为了保证唯一性，可以使用uuid来作为userId
3
//2.userId的长度不能超过50个字符
4
userInfo.guestId = this.guestId

userId 和 guestId 字段的限制：
只能由 [0-9a-zA-Z_-] 组成，即只能由字母、数字、下划线和横杠组成；
长度必须小于 50 个字符。

4.1.2访客姓名*

UserInfo 的 name 属性为访客姓名，设置以后，客服端就能显示访客的姓名，否则显示访客的 userId 。该属性仅对受信任访客生效，为选填项。


3
1
let userInfo = new UserInfo()
2
userInfo.userId = this.userId
3
userInfo.name = "张三";

4.1.3访客性别

UserInfo 的 gender 属性为访客的性别，可选值为"男"或者"女"。设置以后，客服端就能显示访客的性别。该属性仅对受信任访客生效，为选填项。


3
1
let userInfo = new UserInfo()
2
userInfo.userId = this.userId
3
userInfo.gender = "女"

4.1.4手机号码

UserInfo 的 mobileNo 属性为访客手机号码。设置以后，客服端就能显示访客的手机号码。该属性仅对受信任访客生效，为选填项。


xxxxxxxxxx
3
1
let userInfo = new UserInfo()
2
userInfo.userId = this.userId
3
userInfo.mobileNo = "18412345678"

4.1.5备注信息

UserInfo 的 memo 属性代表访客的备注信息。设置以后，客服端就能显示备注信息。该属性仅对受信任访客生效，为选填项。


xxxxxxxxxx
3
1
let userInfo = new UserInfo()
2
userInfo.userId = this.userId
3
userInfo.memo = "备注信息：test！！！"

4.1.6访客头像*

UserInfo 的 userPhotoWebUrl 属性代表访客头像的本地文件路径或远端地址，该头像目前只在 SDK 访客端生效，为选填项。


xxxxxxxxxx
4
1
let userInfo = new UserInfo()
2
userInfo.userId = this.userId
3
userInfo.userPhotoWebUrl =
4
      'http://g.hiphotos.baidu.com/zhidao/pic/item/c8177f3e6709c93d3ed256fd9c3df8dcd1005493.jpg'

4.1.7访客等级

LIVUserInfo 的 grade 属性代表访客等级。该字段为内容为数字类型的字符串（取值范围为1-9）。数字越大代表其等级越高，业务逻辑上会影响其接入顺序，等级越高越优先接入。该属性仅对受信任访客生效，为选填项。


xxxxxxxxxx
4
1
let userInfo = new UserInfo()
2
userInfo.userId = this.userId
3
// 取值范围为1-9
4
info.grade = "5"

4.1.8.访客登录名

LIVUserInfo 的 loginName 属性为访客登录名。设置以后，客服端就能显示访客的登录名。该属性仅对受信任访客生效，为选填项。


xxxxxxxxxx
3
1
let userInfo = new UserInfo()
2
userInfo.userId = this.userId
3
userInfo.loginName = "my_account"

4.1.9.访客请求信息

UserInfo 的 requestInfo 属性代表访客请求信息，对应于 RequestInfo 类，该项为选填项。

例如设置访客的 ip 地址：


xxxxxxxxxx
5
1
let request = new RequestInfo()
2
request.ip = "222.211.163.49"
3
let userInfo = new UserInfo()
4
userInfo.userId = this.userId
5
userInfo.requestInfo = request

RequestInfo 类中的所有字段如下：


xxxxxxxxxx
116
1
/**
2
 * 访客请求信息
3
 */
4
export class RequestInfo {
5
  /**
6
   * 访客ip地址
7
   * 设置以后，客服端就能显示 IP 地址
8
   * 选填项
9
   */
10
  private _ip: string = '';
11

12
  public set ip(value: string) {
13
    this._ip = value;
14
  }
15

16
  public get ip(): string {
17
    return this._ip;
18
  }
19
  /**
20
   * 对话来源/最近访问页面
21
   * 用于描述用户从哪个页面或入口进入对话页面的(例如，用户从订单页面点击客服按钮进入对话，则可传"订单页面")
22
   * 设置以后，客服端就能显示该用户的对话来源字段中的内容
23
   * 选填项
24
   */
25
  private _enterUrl: string = '';
26

27
  public set enterUrl(value: string) {
28
    this._enterUrl = value;
29
  }
30

31
  public get enterUrl(): string {
32
    return this._enterUrl;
33
  }
34
  /**
35
   * 访客来源
36
   * 它可以是您关心的任意的分类，比如填写安卓或iOS。或者是填写您公司旗下不同 App 的名称。
37
   * 设置以后，客服端就能显示该用户的访客来源字段中的内容。
38
   * 选填项
39
   */
40
  private _referrer: string = '';
41

42
  public set referrer(value: string) {
43
    this._referrer = value;
44
  }
45

46
  public get referrer(): string {
47
    return this._referrer;
48
  }
49
  /**
50
   * 访客所处省份
51
   * 设置以后，客服端就能显示该访客所处省份。
52
   * 选填项
53
   */
54
  private _province: string = '';
55

56
  public set province(value: string) {
57
    this._province = value;
58
  }
59

60
  public get province(): string {
61
    return this._province;
62
  }
63
  /**
64
   * 访客所处区域（例如：华北）
65
   * 设置以后，客服端就能显示该用户所处区域
66
   * 选填项
67
   */
68
  private _area: string = '';
69

70
  public set area(value: string) {
71
    this._area = value;
72
  }
73

74
  public get area(): string {
75
    return this._area;
76
  }
77
  /**
78
   * 访客所处城市
79
   * 设置以后，客服端就能显示该用户所处城市。
80
   * 选填项
81
   */
82
  private _city: string = '';
83

84
  public set city(value: string) {
85
    this._city = value;
86
  }
87

88
  public get city(): string {
89
    return this._city;
90
  }
91
  /**
92
   * 用于同步商品信息时向Live800传递预定参数
93
   */
94
  private _remark: string = '';
95

96
  public set remark(value: string) {
97
    this._remark = value;
98
  }
99

100
  public get remark(): string {
101
    return this._remark;
102
  }
103
  /**
104
   * 预留参数
105
   */
106
  private _other: string = '';
107

108
  public set other(value: string) {
109
    this._other = value;
110
  }
111

112
  public get other(): string {
113
    return this._other;
114
  }
115

116
}

4.2.0访客路由信息

UserInfo 的 routingInfo 属性代表访客路由配置，用于将当前访客接通到指定的客服或客服组，对应于 RoutingInfo 类，该项为非必填项，默认使用后台配置的对话接入规则。

RoutingInfo 中的所有字段如下：


xxxxxxxxxx
77
1
export class RoutingInfo {
2
  /**
3
   * 仅kab
4
   * 客服ID(由纯数字组成的字符串)
5
   * 对话将接到指定客服ID的客服人员
6
   * 客服Id的获取方式请联系Live800
7
   * 选填项
8
   */
9
  private _operatorId: string = ''
10

11
  public set operatorId(value: string) {
12
    this._operatorId = value
13
  }
14

15
  public get operatorId(): string {
16
    return this._operatorId
17
  }
18

19
  /**
20
   * 仅kab
21
   * 对话将接到指定客服登陆账号的客服人员
22
   */
23
  private _loginId: string = ''
24

25
  public set loginId(value: string) {
26
    this._loginId = value
27
  }
28

29
  public get loginId(): string {
30
    return this._loginId
31
  }
32

33
  /**
34
   * 仅kab
35
   * 对话将接到指定商家的客服人员
36
   */
37
  private _shopId: string = ''
38

39
  public set shopId(value: string) {
40
    this._shopId = value
41
  }
42

43
  public get shopId(): string {
44
    return this._shopId
45
  }
46

47
  /**
48
   * 仅kab
49
   * 客服组ID（由纯数字组成的字符串）
50
   * 对话将接到该客服组的客服人员
51
   * 客服组ID的获取方式请联系 Live800
52
   * 选填项
53
   */
54
  private _skillId: string = ''
55

56
  public set skillId(value: string) {
57
    this._skillId = value
58
  }
59

60
  public get skillId(): string {
61
    return this._skillId
62
  }
63

64
  /**
65
   * 预留参数(仅kab)
66
   */
67
  private _other: string = ''
68

69
  public set other(value: string) {
70
    this._other = value
71
  }
72

73
  public get other(): string {
74
    return this._other
75
  }
76

77
}

例如将当前访客绑定到客服id为6840841的客服：


xxxxxxxxxx
4
1
let info = new UserInfo()
2
let routing = new RoutingInfo()
3
routing.operatorId = "6840841"
4
info.routingInfo = routing

4.2 SdkManager介绍

4.2.1设置服务器地址


xxxxxxxxxx
1
1
sdkManager.setServerUrl(this.serverUrl)

4.2.2设置appKey


xxxxxxxxxx
1
1
sdkManager.setAppKey(this.appKey)

4.2.3设置AppSecret


xxxxxxxxxx
1
1
sdkManager.setAppSecret(this.appSecret)

4.2.4设置userInfo


xxxxxxxxxx
1
1
sdkManager.setUserInfo(this.createUserInfo())

4.2.5打开客服页面

注意此方法需要在最后调用


xxxxxxxxxx
1
1
sdkManager.startServer()

5.版本更新说明

2025-3-5 v.1.0.0

鸿蒙首个版本