全部产品
云市场

Web开发文档

更新时间:2019-08-06 14:03:04

一、接入前准备

客户端需要从阿里云申请融合通信账号后才能接入,为了保证安全性,融合通信SDK通过服务端下发的临时token作为身份标识与服务进行交互。临时token可通过融合通信服务pop接口从阿里云获得(详见服务端接入文档),并且具有时效性。SDK在token即将失效或其他需求而需要更新token时,会通过回调通知接入方,接入方需自行实现接口获取最新token并传递给SDK。推荐的交互流程如下:

WebSDK交互流程

二、获取SDK

npm安装:

  1. npm install aliyun-voip-web-sdk -S

开源Demo项目:

VoIP Web SDK的Demo项目已开源至Github社区,您可通过Demo演示快速进入开发,VoIP Web Demo

三、快速开始

1、创建实例

  1. import AlicomRTC from 'aliyun-voip-web-sdk'
  2. /**
  3. * 创始实例
  4. */
  5. var rtc = new AlicomRTC()

2、设置参数与回调(可选)

  1. /**
  2. * 设置服务监听
  3. */
  4. rtc.setServiceListener({
  5. /**
  6. * 服务连接成功,当前处于可用状态
  7. */
  8. onServiceAvailable: function () {
  9. // 此时可以开始呼叫操作
  10. },
  11. /**
  12. * 服务连接失败、或者连接断开了,当前处于不可用状态,服务正在销毁。
  13. * @param errCode {number} 错误码
  14. * @param errMsg {string} 错误描述
  15. */
  16. onServiceUnavailable: function (errCode, errMsg) {
  17. },
  18. /**
  19. * 服务闲时
  20. * @param errCode {number} 错误码
  21. * @param errMsg {string} 错误描述
  22. */
  23. onServiceIdle: function (errCode, errMsg) {
  24. },
  25. })
  26. /**
  27. * 可选,设置默认的呼叫超时时间
  28. */
  29. rtc.setDefaultCallTimeout(30)

3、连接服务

  1. /**
  2. * 使用RtcId初始化AlicomRTC实例
  3. */
  4. rtc.initWithRtcId('RTCID', {
  5. updateToken: function (tokenHandler) {
  6. var token = {} // todo: 通过服务端接口获取Token
  7. tokenHandler.setToken(token)
  8. }
  9. })

4、始初化通话实例

ServiceListener中的onServiceAvailable回调被唤起时,表示服务已经连接成功,此时可以开始创建VoIP2PSTN通话实例,设置并开始通话:

  1. /**
  2. * 创建Call实例,每一次通话都需要生成一个Call实例
  3. */
  4. var pstnCall = rtc.createVoIP2PstnCall('被叫号显', '被叫号码')
  5. /**
  6. * 开启服务端录音(可选)
  7. */
  8. pstnCall.setServerRecordEnabled(true)
  9. /**
  10. * 本地禁音(可选)
  11. */
  12. pstnCall.muteLocalAudio()
  13. /**
  14. * 本地取消禁音(可选)
  15. */
  16. pstnCall.unmuteLocalAudio()

5、通话状态管理

  1. /**
  2. * 设置Call状态监听
  3. */
  4. pstnCall.setCallListener({
  5. /**
  6. * 电话已通知到被叫方,被叫振铃中
  7. * @param talk {Talk} 通话对象
  8. */
  9. onCalleeRinging: function (talk) {},
  10. /**
  11. * 被叫已接听电话,正在连接中
  12. * @param talk {Talk} 通话对象
  13. */
  14. onCalleeConnecting: function (talk) {},
  15. /**
  16. * 电话拨通了可以正常通话了。被叫已接听
  17. * @param talk {Talk} 通话对象
  18. */
  19. onActive: function (talk) {},
  20. /**
  21. * 对端传来DTMF信息,每次回调只传入一个字符,如果是一连串输入的话则会多次回调,需要接入方自行根据时间戳处理
  22. * @param dtmf {string} 对端传入的DTMF信息
  23. * @param timestamp {number} 时间戳
  24. * @param talk {Talk} 通话对象
  25. */
  26. onDtmfData: function (dtmf, timestamp, talk) {},
  27. })

6、开始呼叫

  1. pstnCall.start()

7、停止呼叫/通话

  1. pstnCall.stop()

8、销毁实例

  1. rtc.destroy()

四、类型定义

  1. export = AlicomVoIP
  2. export as namespace AlicomVoIP
  3. declare namespace AlicomVoIP {
  4. /**
  5. * 网络质量
  6. */
  7. export enum NetworkQuality {
  8. /**
  9. * 好
  10. */
  11. HIGH,
  12. /**
  13. * 中
  14. */
  15. MEDIUM,
  16. /**
  17. * 差
  18. */
  19. LOW,
  20. }
  21. /**
  22. * RTC Token,由服务端返回
  23. */
  24. export type Token = {
  25. tokenData: string,
  26. cleansession: boolean,
  27. clientId: string,
  28. conferenceTopic: string,
  29. host: string,
  30. sdkClientPort: number,
  31. serverId: string,
  32. meetingEventKeepAliveInterval: number,
  33. phoneTopic: string,
  34. port: number,
  35. reconnectTimeout: number,
  36. registerTime: number,
  37. sgwServerTopic: string,
  38. tlsport: number,
  39. useTLS: boolean,
  40. username: string,
  41. password: string,
  42. vRtcId: string,
  43. }
  44. /**
  45. * 通话角色:被叫
  46. */
  47. export type Callee = {
  48. isPstn: boolean,
  49. phoneNumber: string,
  50. showNumber: string,
  51. uuid: string,
  52. }
  53. /**
  54. * 所有类型通话事件监听回调的基类,定义了所有通话的公共事件回调。。
  55. * @see CallListener
  56. */
  57. export interface TalkListener {
  58. /**
  59. * 通话成功连接到媒体服务器
  60. * @param talk
  61. */
  62. onConnected(talk: Talk): void
  63. /**
  64. * 通话正在断开
  65. * @param errCode 错误码
  66. * @param errMsg 错误消息
  67. * @param talk 通话对象
  68. */
  69. onStoppping(errCode: number, errMsg: String, talk: Talk): void
  70. /**
  71. * 通话已结束
  72. * @param errCode 错误码
  73. * @param errMsg 错误消息
  74. * @param talk 通话对象
  75. */
  76. onStopped(errCode: number, errMsg: string, talk: Talk): void
  77. /**
  78. * 通话中网络质量消息
  79. * @param quality 质量
  80. * @param talk 通话对象
  81. */
  82. onNetworkQuality(quality: NetworkQuality, talk: Talk): void
  83. /**
  84. * 通话中的监控数据回调
  85. * @param monitorStats 监控数据
  86. * @param talk 通话对象
  87. */
  88. onMediaStatistics(monitorStats: any, talk: Talk): void
  89. }
  90. /**
  91. * 电话生命周期中的所有回调
  92. * @see Call
  93. */
  94. export interface CallListener extends TalkListener {
  95. /**
  96. * 电话已通知到被叫方,被叫振铃中
  97. * @param talk 通话对象
  98. */
  99. onCalleeRinging(talk: Talk): void
  100. /**
  101. * 被叫已接听电话,正在连接中。(拨打类型为PSTN与呼叫中心的电话时无此回调)
  102. * @param talk 通话对象
  103. */
  104. onCalleeConnecting(talk: Talk): void
  105. /**
  106. * 电话拨通了可以正常通话了。主叫中代表被叫已接听,被叫中表示电话已接听
  107. * @param talk 通话对象
  108. */
  109. onActive(talk: Talk): void
  110. /**
  111. * 对端传来DTMF信息,每次回调只传入一个字符,如果是一连串输入的话则会多次回调,需要接入方自行根据时间戳处理
  112. * @param dtmf 对端传入的DTMF信息
  113. * @param timestamp 时间戳
  114. * @param talk 通话对象
  115. */
  116. onDtmfData(dtmf: string, timestamp: number, talk: Talk): void
  117. }
  118. export interface Talk {
  119. /**
  120. * 开始呼叫
  121. */
  122. start(): void
  123. /**
  124. * 终止呼叫
  125. */
  126. stop(): void
  127. /**
  128. * 禁音
  129. */
  130. muteLocalAudio(): void
  131. /**
  132. * 取消禁音
  133. */
  134. unmuteLocalAudio(): void
  135. /**
  136. * 本地是否禁音
  137. */
  138. isLocalAudioMuted(): boolean
  139. /**
  140. * 发送dtmf
  141. * @param dtmf dtmf信息,只能是0-9、*、#,最大长度不超过32位
  142. */
  143. sendDtmfData(dtmf: string): boolean
  144. }
  145. /**
  146. * 表示具体的一通点对点音频通话。
  147. * 生命周期从创建实例开始,至通话停止结束,不能重复使用。
  148. * 通话生命周期中的事件会在回调{@link CallListener}中体现
  149. * @see CallListener
  150. */
  151. export interface Call extends Talk {
  152. /**
  153. * 获取被叫信息
  154. */
  155. getCallee(): Callee
  156. /**
  157. * 设置通话状态Listener
  158. * @param callListener
  159. */
  160. setCallListener(callListener: CallListener): void
  161. setServerRecordEnabled(enabled: boolean): void
  162. }
  163. /**
  164. * 整个服务生命周期的回调。在服务连接成功或者断开时回调。
  165. */
  166. export interface ServiceListener {
  167. /**
  168. * 服务连接成功,当前处于可用状态
  169. */
  170. onServiceAvailable(): void
  171. /**
  172. * 服务连接失败、或者连接断开了,当前处于不可用状态,服务正在销毁,此时不能调用init操作。
  173. * @param errCode 错误码
  174. * @param errMsg 错误描述
  175. */
  176. onServiceUnavailable(errCode: number, errMsg: string): void
  177. /**
  178. * 服务闲时
  179. * @param errCode 错误码
  180. * @param errMsg 错误描述
  181. */
  182. onServiceIdle(errCode: number, errMsg: string): void
  183. }
  184. /**
  185. * 用户成功获取token后调用{@link TokenHandler#setToken(Token)}设置token
  186. * @see TokenUpdater
  187. */
  188. export interface TokenHandler {
  189. /**
  190. * 将已获取的token传入给alicomRTC
  191. * @param token token以及其他必要的初始化参数
  192. */
  193. setToken(token: Token): void
  194. }
  195. /**
  196. * 需要接入方实现的获取{@link Token}的具体实现
  197. * @see Token
  198. */
  199. export interface TokenUpdater {
  200. /**
  201. * 通知客户更新token
  202. * @param tokenHandler
  203. */
  204. updateToken(tokenHandler: TokenHandler): void
  205. }
  206. /**
  207. * AlicomRTC
  208. */
  209. export class AlicomRTC {
  210. /**
  211. * 设置监听回调。用于监听服务在整个生命周期中的事件通知。
  212. * @param listener
  213. */
  214. setServiceListener(listener: ServiceListener): void
  215. /**
  216. * 创建VoIP2PSTN呼叫
  217. * @param calleeShowNumber 被叫号显
  218. * @param calleePhoneNumber 被叫号码
  219. * @param extend
  220. */
  221. createVoIP2PstnCall(calleeShowNumber: string, calleePhoneNumber: string, extend?: string): Call
  222. /**
  223. * 使用云通信音视频账号模式初始化服务并开始连接。连接的结果会在回调{@link ServiceListener}中体现。使用结束后需调用{@link AlicomRTC#destroy()}释放资源
  224. * @param rtcId 云通信音视频账号id
  225. * @param tokenUpdater 接入方传入的获取token的具体实现
  226. */
  227. initWithRtcId(rtcId: string, tokenUpdater: TokenUpdater): void
  228. /**
  229. * 设置默认的呼叫超时时间,限制在30-90秒之间
  230. * @param seconds 呼叫超时时间,单位为秒
  231. */
  232. setDefaultCallTimeout(seconds: number): void
  233. /**
  234. * 停止服务并销毁
  235. */
  236. destroy(): void
  237. }
  238. }

四、错误码

错误码 数值 原因
ERROR_MQTT_CONNECT_FAIL 1000100 mqtt连接失败
ERROR_UPLOAD_TOKEN_FAIL 1000104 token上传失败
ERROR_LOCAL_STOP 2000000 本地主动挂断
ERROR_REMOTE_HANGUP 2000099 对端主动挂断
ERROR_CALL_SELF 2000100 拨打自己
ERROR_CALL_EMPTY 2000101 拨打电话为空
ERROR_REMOTE_REFUSE 2000106 主叫时,对端拒绝应答
ERROR_NO_ANSWER 2000108 被叫无人接听
ERROR_SERVICE_UNAVAILABLE 2000113 AlicomRTC服务不可用
ERROR_LOCAL_DESTROY 2000116 本地主动销毁服务
ERROR_TIME_OUT 2000102 joinChannel超时
ERROR_NETWORK_INVALID 2000121 网络异常
ERROR_MICROPHONE_NO_PERMISSION 2000131 麦克风无权限
ERROR_SERVER_BASE 3000000 服务端返回业务异常的错误基准
ERROR_SERVER_KICKED 3110000 账号被登录或被踢
ERROR_SERVER_UNAVAILABLE 3110001 服务异常
ERROR_MEDIA_BASE 4000000 媒体sdk返回异常的错误基准