快速入门

本文主要介绍如何将 Talk Web SDK 集成到你的项目中以及相关注意事项。

开发环境要求

• 一个有效的 开发者账号。

• 一款支持 Talk SDK 的主流浏览器:

  浏览器	兼容性
  Chrome 49+	✔
  Safari 9+	✔
  Firefox 52+	✔
  微信浏览器	✔
  QQ 浏览器 10.5+	✔
  Internet Explorer 11+	✔

快速集成

本小节介绍如何获取 AppID 以及如何快速将 SDK 集成到项目中。

获取 AppID

参考以下步骤获取一个 AppID。若已经拥有 AppID，请跳过当前步骤，直接查看操作流程。

• 1. 创建项目

  首先我们需要在开发者控制台创建一个「项目」。

• 2. 获取 APP ID

  获取项目的「APP ID」。

引入 SDK

1: 获取 SDK

你可以通过如下几种方式获取最新的 SDK:

• 1. 官网下载中心找到 「Talk SDK 下载」 的Web端
• 2. 前往unpkg ，ctrl + s 或 command + s 下载，或者 script 标签引入
• 3. 前往 github clone 或 Download ZIP 下载
• 4. 通过 npm 市场下载

  该方法需要安装 npm。详见 Install npm。

  npm i ar-talk-sdk
  

2: 导入 SDK

导入 SDK 支持以下方式：

• script 标签引入

  使用 <script> 标签引入的 SDK ，window 对象中会暴露一个 ArTalk 的全局变量。

  <script src="https://unpkg.com/ar-talk-sdk@latest"></script>
  

• ES6 方式引入

  import ArTalk from '/<YOUR_PATH>/to/ArTalk@latest.js';
  

• CommonJS 方式引入

  var ArTalk = require('/<YOUR_PATH>/to/ArTalk@latest.js');
  

• npm 方式引入

  // ES6
  import ArTalk from 'ar-talk-sdk';
  // 或者是 commonJS
  var ArTalk = require('ar-talk-sdk');
  

操作流程

初始化客户端

通过 ArTalk.createInstance 创建本地客户端 talkClient 的实例。

// 创建实例是需要填入我们事先准备好的 App ID。
const client = ArTalk.createInstance('<APPID>');

使用相同 App ID 的应用才能互相通信。

登录

talkClient 的实例提供了 login 方法可以登录 Talk 系统，login 方法支持传入一个对象作为参数，对象包含两个属性 token 和 uid:

• token：非必填，用于 Token 鉴权，提供应用信息的安全级别。如果应用已经开启了权限密钥，登录时需要配置 token Talk 服务器会对 token 进行验证。为了保证应用安全性，建议启用该功能（开发测试阶段不建议启用）。
• uid: 必填，用来标识用户身份，无缝对接业务系统。必须为字符串，不可超过 48 字节，但是不支持字符串 "null"。

登录 Talk 服务器之后，才可以实现 Talk 的群组对讲等功能。

// 定义登录配置
const options = {
  token: '<TOKEN>',
  uid: '<UID>'
};
// 登录
client.login(options).then(() => {
  console.log('ArTalk client login success');
}).catch(err => {
  console.log('ArTalk client login failure', err);
});

监听连接状态改变

通过监听 TalkClient 上的 ConnectionStateChanged 事件可以获得 SDK 连接状态改变的通知。

talkClient.on('ConnectionStateChanged', (newState, reason) => {
  console.log('on connection state changed to ' + newState + ' reason: ' + reason);
});

对讲群组

SDK 支持集群对讲。

创建频道

一个客户端可以加入多个频道，但是需要业务系统自己维护。

// 此处传入频道 ID
const channel = client.createChannel('<CHANNEL_ID>');
const channel1 = client.createChannel('<CHANNEL_ID1>');

监听频道事件

创建频道成功后，需要监听 UserIsTalkOn 、 UserIsTalkOff 等回调事件，来接收频道内的人员对讲、广播等回调。

// 人员上麦
channel.on('UserIsTalkOn', (channelId, userId, userData, userLevel) => {
  console.log("UserIsTalkOn"， channelId, userId, userData, userLevel)；
});
// 人员下麦
channel.on('UserIsTalkOff', (channelId, userId, userData) => {
  console.log("UserIsTalkOff"， channelId, userId, userData)；
});
// 人员上麦被打断
channel.on('BreakTalk', (memberId) => {
  console.log("BreakTalk"， memberId)；
});
// 收到群组广播
channel.on('UserIsStreamOn', (channelId, userId, userData) => {
  console.log("UserIsStreamOn"， channelId, userId, userData)；
});
// 群组广播取消
channel.on('UserIsStreamOff', (channelId, userId, userData) => {
  console.log("UserIsStreamOff"， channelId, userId, userData)；
});

加入频道

调用频道实例的 join 方法。

channel.join().then(() => {
  // 加入频道成功
}).catch(error => {
  // 加入频道失败
});

发起频道对讲

客户端加入频道成功后可以发起频道对讲。

channel.pushToTalk().then(() => {
  // 发起频道对讲成功
}).catch(error => {
  // 发起频道对讲失败
});

取消/结束频道对讲

客户端发起频道对讲后，可以取消/结束频道对讲。

channel.stopPushToTalk().then(() => {
  // 取消/结束频道对讲成功
}).catch(error => {
  // 取消/结束频道对讲失败
});

打断频道对讲

当前客户端的在频道中的等级高于正在对讲的用户等级时，可以打断当前对讲，被打断方会被强制下麦。

channel.breakTalk().then(() => {
  // 打断频道对讲成功
}).catch(error => {
  // 打断频道对讲失败
});

退出频道

调用实例的 leave 方法可以退出该频道。退出频道之后可以调用 join 方法再重新加入频道。

channel.leave();

频道其他方法

除了以上常用的 API 之外，我们还可以:

登出

talkClient 的实例提供了 logout 方法可以登出 Talk 系统。

如果需要切换账号，可以在退出登录切换 uid 再次调用 login 实现切换账号。

client.logout();

开发注意事项

• 在频道操作前，需要确保已经成功登录 Talk 系统。
• 回调多次监听会回调多次。
• Talk 支持创建多个 channel 实例。