文档反馈
文档反馈

跑通呼叫组件(Web)

为了方便开发者快速接入音视频通话 2.0,提升应用的研发效率,音视频通话 2.0 和信令产品携手为您打造应用层呼叫组件 NERTCCallkit,组件中集成了音视频通话 2.0 和信令的多项基础功能,全方位提升接入效率。

NERTCCallkit 呼叫组件的 API 接口概览请查看组件概述

准备工作

注意事项

下载组件

请联系技术人员获取组件下载地址。

体验组件 Demo

您可以在 node 环境中部署 Demo 并体验。

注意:必须启动服务才能预览 Demo。此处以 node 服务为例,您也可以使用其他方式启动服务。

  1. 进入 Demo 目录。
     cd NIM_Web_Demo
  2. 安装 Demo。
     npm install
  3. 启动 app。
     node app
  4. 在浏览器中访问 http://127.0.0.1:8182/webdemo/imNew/index.html

集成组件

Demo 中以 script 标签形式导入音视频 2.0 SDK。

  1. 下载 NERTCCallkit 组件 并解压缩。
  2. 通过 Visual Studio Code 打开文件。
  3. 在路径 NIM_Web_Demo/webdemo/3rd/lib 找到组件。

    其中,ts 是声明文件,js 是压缩过的源码。

  4. 在 eslintignore 或 prettierignore 中添加相关忽略设置。
  5. 根据需求选择打包方式。

    组件提供 es module、commonjs、umd 三种打包方式,请根据项目的情况按需选择。

    • es module:
        import { RTCCalling } from 'yourPath';
        const rtc = new RTCCalling({  
            debug: true, // 是否需要开启日志,默认开启
        });
    • commonjs::
        const { RTCCalling } = require('yourPath');
        const rtc = new RTCCalling({  
            debug: true, // 是否需要开启日志,默认开启
        });
    • script 引入:
        <script src="/yourPath/assets/sdk/NIM_Web_SDK_v8.1.0.js"></script>
        <script src="/yourPath/assets/sdk/NIM_Web_WebRTC2_v3.7.0.js"></script>
        <script src="/yourPath/lib/index.umd.js"></script>
        <script>  
        var RTCCalling = window.NRTCCalling.RTCCalling;  
        var rtc = new RTCCalling({    
            debug: true, // 是否需要开启日志,默认开启  
        });
        </script>

实现 UI 界面

如需快速接入 NERTCCallkit 呼叫组件,您可以直接基于我们提供的组件 Demo 进行修改适配,也可以自行实现自定义的 UI 界面。

您可以参考 Demo 中 的 UI 模块:

实现组件基本功能

步骤一 初始化组件

通过以下示例代码初始化 NERTCCallkit 呼叫组件。

/**
 * 初始化,之后需要调用登录
 * appKey,用户appkey
 * token,可选,非安全模式可不传
 */
setupAppKey({ appKey }: SetupParams): void;

rtc.setupAppKey({
    appKey: CONFIG.appkey
})

步骤二 登录

调用 login 函数完成组件的登录。

NERTCCallkit 呼叫组件与 IM 的 login 方法不可共用,如果 IM 登录成功,如果需要使用组件则必须再调用组件 login 方法。推荐直接使用组件的登录逻辑,避免相同事件被覆盖。

 // 登录信令sdk  
await rtc.login({   
   account: 'account',    
   token: '',
    // 支持传入其他 IM 登录中的参数
    // ...props  
});

步骤三 设置 Token

netcall.js 中实现 setTokenService 方法。

/**
* 设置获取token的异步函数,在加入RTC之前调用
* @param cb 获取token的异步函数
*/
 setTokenService(cb: TokenService): void; 

 // 如果需要安全模式,需要手动调用设置token的函数  
 // 请保证在发起呼叫和接受呼叫之前设置,且必须保证函数返回Promise
rtc.setTokenService(async function(uid: string) {        
  // 自己的获取token逻辑    
  const token = await yourGetTokenFunc()
  return token;
})

步骤四 发起和取消呼叫

发起呼叫

支持发起一对一通话和多人通话。

取消呼叫

参考以下代码实现取消呼叫的相关逻辑。

rtc.cancel().then(() => {
    console.log('取消呼叫成功')
}).catch((err) => {
    console.log('取消呼叫失败', err)
})

步骤五 配置监听

Demo 中在 netcall.js 实现 fn.onInvited 监听被呼叫。

// 收到邀请
rtc.addDelegate('onInvited', () => {   
    // 一般在此处唤起接听和拒绝按钮,点击后调用rtc.accept接收 或者 rtc.reject拒绝 
    console.log("收到音视频呼叫");
});

// 对方取消呼叫
rtc.addDelegate('onUserCancel', () => {    
    console.log("对方取消呼叫");
});

// 用户接受  
rtc.addDelegate('onUserAccept', (account) => {    
  // 点对点呼叫一般在此设置本端视图    
  const dom = document.getElementById(`local-stream`);    
  rtc.setupLocalView(dom);  
});

// 用户进入  
rtc.addDelegate('onUserEnter', (account) => {    
    // 群呼一般在此设置远端用户的视图    
  const div = document.getElementById(`remote-container-${account}`);
  rtc.setupRemoteView(account, div as HTMLElement)
});

// 用户拒绝  
rtc.addDelegate('onUserReject', (account) => {    
    // do sth  
});

  // 用户离开  
rtc.addDelegate('onUserLeave', (account) => {    
    // do sth  
});

  // 通话结束  
rtc.addDelegate('onCallEnd', () => {    
    // do sth  
});

// 收到远端视频流订阅变更  
rtc.addDelegate('onCameraAvailable', ({ userId: account, available }) => {    

});

// 收到远端音频流订阅变更  
rtc.addDelegate('onAudioAvailable', ({ userId: account, available }) => {    

});

// 网络质量状态回调
rtc.addDelegate('onUserNetworkQuality', data => {  

});

// 通话类型切换回调
rtc.addDelegate('onCallTypeChange', type => {  

});

// 自己音视频断线回调
rtc.addDelegate('onDisconnect', () => {  

});

// 其他人音视频断线回调
rtc.addDelegate('onUserDisconnect', account => {  

});

// 其他端接受通话回调
rtc.addDelegate('onOtherClientAccept', () => {  

});

// 其他端拒绝通话回调
rtc.addDelegate('onOtherClientReject', () => {  

});

// 主叫异常话单发送回调
rtc.addDelegate('onMessageSent', (userId) => {  
  //userId: 被发送方的account
});

// 错误监听  
rtc.addDelegate('onError', (error) => {    
    // do sth  
});

步骤六

接听来电

被叫方调用 accept 函数接听来电。

/**
 * 接受呼叫
 * @param params
*/
accept(params?: Callback): Promise<void>;

// 接收呼叫 
const accept = () => {    
  // 作为被动呼叫方,一般在此设置自己的视图    
  const dom = document.getElementById(`local-stream`);   
    rtc.setupLocalView(dom);    
    rtc.accept().then(() => {});  
};

拒绝来电

被叫方调用 reject 函数拒绝来电。

/**
 * 拒绝呼叫
 * @param params
 */
reject(params?: Callback): Promise<void>;

// 拒绝呼叫  
const reject = () => {    
  rtc.reject();  
};

步骤七 挂断通话

主叫方和被叫方处于通话中时,调用 hangup 函数结束通话,并调用 leave 函数离开房间。

/**
 * 挂断,同时挂断其他人
 * @param params
 */
hangup(params?: Callback): Promise<void>;

// 挂断  
const hangup = () => {    
  rtc.hangup();  
};

/**
 * 离开,不影响通话中的其他人(多人调用)
 * @param params
 */
leave(params?: Callback): Promise<void>;

 // 离开,多人调用
const leave = () => {    
  rtc.leave();  
};

步骤八 获取话单

呼叫组件提供通话话单功能,在一通通话结束后,您会收到对应的通话话单。通话话单是一条事件通知消息,以 IM 会话类型消息抄送的形式发送,收到话单后,您可以解析消息体,获得通话时间等通话详情。

说明

正常挂断

通话正常挂断时,Demo 中的实现流程为:

  1. 调用组件封装方式的挂断之后,服务器会正常下发正常结束的话单。
  2. 客户端会通过接收消息的回调 onmsg,收到一条名为 NetcallBill 的消息。
  3. 对消息进行解析并上报到业务层进行展示。

在正常挂断的情况下,您可以通过以下方法实现话单功能解析及展示:

异常挂断

异常挂断的情况下,主叫方需要在业务层注册组件回调,被呼叫方处理逻辑与正常挂断逻辑相同。

// 主叫方需要注册发送话单事件
rtc.addDelegate('onMessageSent', () => {
    // 更新话单ui
})

组件话单由组件内部发送,直接提供给对方,其中包含超时、忙线、拒绝的消息。

底层实现方式为:

  1. 调用 SDK 发送一对一消息 sendTextMessage。
  2. 通过封装信息之后,发送给对方。
  3. 对方收到消息解析。

话单消息结构

话单以 IM 消息抄送的形式发送,抄送类型为会话类型,即 eventType 为 1。会话类型的消息体中一般包含 eventType、convType、to、fromAccount、msgTimestamp、msgType、msgidClient、msgidServer、attach 等字段,其中:

attach 字段说明:

字段 类型 示例 说明
type 1 通话类型。
  • 1:音频通话
  • 2:视频通话
channelId Number 123 房间 ID。
status Number 1 呼叫状态。
  • 1:通话正常结束。
  • 2:主叫取消呼叫。
  • 3:被叫拒绝通话。
  • 4:被叫未接听呼叫,呼叫因超时被取消。
  • 5:被叫忙线,通话未接通。
durations JsonArray - 通话过程详情,JSON 数组格式,其中包括:
  • accid:通话成员的 accid。
  • duration:对应成员的通话时长。

完整话单的 JSON 示例:

{
  "msgTimestamp": "1611904620759",
  "msgType": "NRTC_NETCALL",
  "msgidServer": "11111",
  "fromAccount": "22222",
  "to": "33333",
  "attach": "{\"durations\":[{\"duration\":68,\"accid\":\"22222\"},{\"duration\":68,\"accid\":\"11111\"}],\"type\":2,\"channelId\":1111111,\"status\":1}",
  "eventType": "1",
  "convType": "PERSON",
  "msgidClient": "33333",
  "resendFlag": "0"
}
×

反馈成功

非常感谢您的反馈,我们会继续努力做得更好。