PAAS 聊天服务 开发指南
产品介绍
基本描述
微吼云提供的聊天互动服务,基于微吼多年在行业内的沉淀,为用户提供了一套完整的聊天解决方案,通过集成SDK即可实现多终端实时通讯的功能,您可以快速将聊天服务集成到您的APP中。
核心能力
1.实时互动
支持发送文字消息;支持低延时实时聊天
2.智能垃圾过滤
通过人工智能技术实现过滤聊天中的垃圾消息,帮助用户降低色情、暴恐、涉政等违规风险,节省人工审核成本
3.多终端接入
提供多终端SDK,实现多终端聊天互动
主要功能
类别 | 功能名称 | 详细内容 |
---|---|---|
聊天配置 | 智能垃圾消息过滤 | 开启智能垃圾消息过滤后,将为用户提供智能垃圾消息过滤服务,过滤聊天中的垃圾消息 |
聊天管理 | 管理方式 | 支持通过控制台和API两种方式对聊天室进行管理 |
控制台管理 | 支持聊天室的创建、查询、导出、修改、演示 | |
API管理 | 支持频道的创建、删除、发送消息、设置第三方用户信息 | |
数据统计 | 控制台统计 | 查询消息统计(消息数量&智能垃圾过滤消息数量)和进入人次 |
数据统计 | API统计 | 查询消息数量&智能垃圾过滤消息数量 |
产品定价
1、计费类型及说明
微吼云聊天服务采用后付费方式,即使用服务后扣费的计费方式。您需要先在微吼云账户预先充值,系统会按照使用的功能进行扣费。
2、计费方式说明
按照提供的智能垃圾过滤功能进行计费
您可以通过控制台查询微吼云聊天服务的实际使用量。
2.1 智能垃圾过滤服务
价格
单价:800.00元/月
计费规则
计费方式:后付费计费方式
计费统计项:智能垃圾过滤功能
计费规则:按月进行扣费
- 使用智能垃圾过滤功能,则每月扣掉800.00元
计费周期:按月扣费,按月出消费明细,每个月出账单。每个月的账单会在次月1号生成。
计费说明
1.功能默认关闭,可在微吼云控制台手动开启。
2.使用智能垃圾过滤服务,将会收取相应的功能费。
3.控制台开通该功能,则立即产生扣费,次月一号出账单。
4.按月扣费,请确保账户余额充足,以免影响您的业务。
3、欠费说明
1.欠费后工作人员会与您进行联系,如还未进行充值,将会停掉您的服务。
2.开通策略:账户充值余额为正后则会自动开通服务。
控制台指南
创建账号
申请开通微吼云账号,提供用户资料,微吼服务人员在后台为用户开通平台账号,或者在微吼云网站自助进行账号注册,账号开通后,用户即可登录,成为一名开发者。
创建应用
登录成功后,点击左侧或者应用管理页面中的创建应用按钮,创建一个新应用。
添加服务
创建应用后,点击添加服务,弹出添加服务对话框,选择聊天服务,点击确定,聊天服务添加成功。
聊天配置
服务添加成功后,可对服务进行配置,聊天配置包含应用信息和智能垃圾过滤两部分
应用信息:AppId
智能垃圾过滤:可对智能垃圾过滤服务进行开启关闭操作,开启后将为用户提供智能垃圾过滤服务。
提醒:开启智能垃圾过滤服务会产生对应费用,请根据实际情况留意相关成本支出。
聊天管理
聊天管理支持聊天室的创建、删除、查询、修改、演示和导出
聊天室创建
点击创建,弹出聊天室创建对话框,填写描述信息,点击确定,聊天室创建成功,列表中增加一条聊天室记录。
提醒:聊天室与接口中的频道概念是一致的,消息是通过频道来进行发送和接受的。
聊天室删除
选择需要删除的聊天室,点击删除或批量删除按钮,确认删除后,选中的聊天室删除成功。
聊天室查询
搜索框中填写聊天室ID,点击查找,系统依照条件检索出符合要求的聊天室并显示在列表中。
聊天室演示
点击演示,会弹出聊天室演示页面,在演示页面用户可体验聊天室提供的功能服务。
聊天记录导出
选择某个聊天室点击导出,或点击全局导出按钮,可分别导出某个聊天室的聊天记录和全部聊天室的聊天记录。
消息统计
用户可以通过菜单选择消息统计,对聊天消息数和智能垃圾过滤消息数的信息根据日期进行查看。
访问统计
用户可以通过菜单选择访问统计,对聊天室进入次数信息根据日期进行查看。
客户端集成
客户端SDK下载:
客户端SDK集成文档:
服务端集成
服务端API
接口概述
1 请求说明
1.1 请求地址
http://api.vhallyun.com/api/v1/controller/action
- controller/action 为每个接口单独提供
1.2 通信协议
请求支持HTTP和HTTPS两种访问方式
1.3 请求方法
同时支持POST&GET方式,GET方式查询字符串(名称/值对)是在GET请求的URL中发送的,POST方式查询字符串(名称/值对)是在POST请求的HTTP消息主体中发送的。
1.4 请求参数
每个请求都需要包含的公共请求参数
1.5 字符编码
所有接口均使用UTF-8编码
2 公共参数
2.1 公共请求参数(如无特殊说明,接口中均包含公共请求参数)
所有接口均需要放置以下公共参数在请求头中,用于标识用户和接口鉴权。后续的接口说明不再对这些参数进行说明,但每次发起请求均需要携带。
参数 | 类型 | 是否必选 | 含义 |
---|---|---|---|
app_id | string | 是 | 应用ID |
signed_at | string | 是 | 鉴权时间,时间戳 |
sign | string | 是 | 鉴权签名 |
2.2 公共响应参数(如无特殊说明,接口中的响应参数均为data中的数据)
参数 | 类型 | 是否必选 | 含义 |
---|---|---|---|
code | int | 是 | 请求状态码 (200 成功) |
msg | string | 是 | 失败原因(默认空字符串) |
data | json | 是 | 请求数据 |
2.3 公共错误码
参数 | 类型 | 含义 |
---|---|---|
10001 | int | 应用ID不能为空 |
10002 | int | 鉴权时间不能为空 |
10003 | int | 鉴权签名不能为空 |
20001 | int | 应用查询为空 |
20003 | int | 开发者不存在 |
30004 | int | 接口鉴权失败 |
30003 | int | 当前开发者尚未通过认证 |
3 API鉴权方案
使用业界通用方案。
- 我们为客户的每个应用,分配一个app_id和一个secret_key。
- app_id和一个secret_key获取地址 : http://yun.vhall.com/console/app/index (应用->设置->应用信息)
- 客户的所有API请求中,需携带app_id。用于识别应用。
- 同时,客户对请求中所有参数(包括app_id)进行字典序排序,并拼接成字符串。
- 在此字符串首尾各拼接secret_key。
- 对拼接后的字符串进行md5,得到sign。
- 将得到的sign作为请求参数之一传递。
- VOP服务器收到所有参数后,根据app_id取得对应的secret_key,然后依照同样的算法计算sign。验证与传递的sign是否一致。
例如:
<?php
$secret_key = "f145b675f441cc00dd3e55746a0f4780";
$params = [
"room_id"=> "123456789",
"app_id"=> "3eb7261",
"signed_at"=> "1484620708"
];
// 按参数名升序排列
ksort($params);
// 将键值组合
array_walk($params,function(&$value,$key){
$value = $key . $value;
});
// 拼接,在首尾各加上$secret_key,计算MD5值
$sign = md5($secret_key . implode('',$params) . $secret_key);
AccessToken
生成AccessToken
API 名称
base/create-access-token,用于SDK权限校验,针对聊天服务。如果您同时集成多个服务,可在入参时传入相应服务的权限值,具体权限值可参考个服务的参数描述。
入参
参数 | 类型 | 是否必选 | 含义 |
---|---|---|---|
third_party_user_id | string | 是 | 第三方用户ID |
expire_time | string | 否 | 过期时间 默认为一天,最大为一天 格式为 2017/01/01 00:00:00 |
chat | string | 否 | 发聊天,对应的值为频道ID (通过消息API 创建频道接口获得) |
参数示例
{
third_party_user_id : "vhall_user_nelsonking", // 第三方用户ID
expire_time : 2017/01/01 00:00:00, // 过期时间
chat : "ch_af793b0e,ch_cb593b12",//发聊天:“频道ID”
}
// 多个频道ID,请使用英文逗号分割
// 需要多个服务时,可传入对应权限,权限列表可有多个,无先后顺序
// 各权限可对应多个资源ID,请使用英文逗号分割
出参
参数 | 类型 | 是否必选 | 含义 |
---|---|---|---|
access_token | string | 是 | token 令牌 |
错误码
错误码 | 类型 | 含义 |
---|---|---|
10012 | int | 第三方用户ID不能为空 |
40004 | int | 时间类型不正确 |
40003 | int | 没有该权限类型 频道ID |
30006 | int | 不是这些频道拥有者 |
响应格式
{
"code": 200,
"msg": "",
"data": {
"access_token": ""
}
}
销毁AccessToken
API 名称
base/destroy-access-token
入参
参数 | 类型 | 是否必选 | 含义 |
---|---|---|---|
access_token | string | 是 | 访问令牌 |
出参
参数 | 类型 | 是否必选 | 含义 |
---|---|---|---|
destory_token | string | 是 | 销毁的AccessToken |
错误码
错误码 | 类型 | 含义 |
---|
响应格式
{
"code": 200,
"msg": "",
"data": [
"destory_token" : "access:app_id_1:jfalsiecnm"
]
}
创建频道
描述
channel/create,创建频道
- 频道:聊天室是承载了聊天的频道,用户可以通过创建的频道进行聊天、文档演示等操作
请求参数
- 只有公共参数
响应参数
参数 | 类型 | 是否必选 | 含义 |
---|---|---|---|
channel_id | string | 是 | 频道ID |
响应示例
{
"code": 200,
"msg": "",
"data": {
"channel_id": "ch_e5fa35b2"
}
}
删除频道
描述
channel/delete,删除频道
请求参数
参数 | 类型 | 是否必选 | 含义 |
---|---|---|---|
channel_id | string | 是 | 频道ID/房间ID |
响应参数
参数 | 类型 | 是否必选 | 含义 |
---|---|---|---|
delete_channel_id | string | 是 | 删除的频道ID |
错误码
参数 | 类型 | 含义 |
---|---|---|
10016 | int | 频道ID不能为空 |
20004 | int | 频道查询为空 |
30002 | int | 不是当前频道拥有者 |
40006 | int | 频道类型不正确 |
50002 | int | 系统删除失败 |
响应示例
{
"code": 200,
"msg": "",
"data": {
"delete_channel_id": "ch_e5fa35b2"
}
}
发送消息
描述
channel/sent,发送聊天消息
请求参数
参数 | 类型 | 是否必选 | 含义 |
---|---|---|---|
type | int | 是 | 消息类型 |
body | string | 否 | 消息体 |
channel_id | string | 是 | 频道ID/房间ID |
type
参数 | 类型 | 含义 |
---|---|---|
CustomBroadcast | string | 自定义消息 |
错误码
参数 | 类型 | 含义 |
---|---|---|
10010 | int | 消息类型不能为空 |
10016 | int | 频道ID不能为空 |
20002 | int | 房间查询为空 |
20004 | int | 频道查询为空 |
30002 | int | 不是当前频道拥有者 |
40002 | int | 消息类型不正确 |
40012 | int | 消息体过长,最长为500 |
50002 | int | 消息发送失败 |
响应示例
{
"code": 200,
"msg": "",
"data": []
}
查看消息&过滤数量
描述
channel/get-message-num,查询指定时间范围内的消息数&垃圾过滤消息数
请求参数
参数 | 类型 | 是否必选 | 含义 |
---|---|---|---|
start_time | string | 是 | 查询开始时间 格式 2017/01/01 |
end_time | string | 否 | 查询结束时间 格式 2017/01/01 |
响应参数
参数 | 类型 | 是否必选 | 含义 |
---|---|---|---|
msg_count | int | 是 | 消息数量 |
msg_filter_count | int | 是 | 过滤消息数量 |
错误码
参数 | 类型 | 含义 |
---|---|---|
10020 | int | 开始时间不能为空 |
40004 | int | 时间类型不正确 |
响应示例
{
"code": 200,
"msg": "",
"data": {
"2017-12-12": {
"msg_count": 2,
"msg_filter_count": 4
},
"2017-12-13": {
"msg_count": 4,
"msg_filter_count": 8
},
"2017-12-14": {
"msg_count": 0,
"msg_filter_count": 0
}
}
}
设置第三方用户信息
- 注意,该接口只作为消息服务,消息内容头像和昵称安全不被篡改的一种保障,不作其他使用
描述
channel/save-user-info,设置第三方用户信息
请求参数
参数 | 类型 | 是否必选 | 含义 |
---|---|---|---|
third_party_user_id | string | 是 | 第三方用户ID |
nick_name | string | 是 | 昵称 |
avatar | string | 是 | 头像(头像网络路径) |
响应示例
{
"code": 200,
"msg": "",
"data": []
}
iOS SDK开发集成
iOS SDK简介
简介
微吼云为用户提供了聊天室功能,用户可通过集成SDK,快速在iOS平台接入聊天互动服务。
功能特性
- 聊天室实时发送文本消息
- 聊天室实时接收文本消息
iOS SDK开发指南
1 概念说明
频道:聊天、文档服务,依赖于频道。例如在使用文档演示时,需要先通过基础通讯服务创建一个频道。并将文档演示方与观看方连接至同一个频道。 消息发送也需要依赖频道的创建来进行消息传送。
智能垃圾过滤:开启智能垃圾过滤,可以为用户智能过滤掉聊天消息中的垃圾消息,帮助用户降低色情、暴恐、涉政等违规风险,节省人工审核成本。
2 接入准备
2.1 成为开发者
申请开通微吼云账号,提供用户资料,微吼服务人员在后台为用户开通平台账号,用户也可在微吼云网站自行注册账号,账号开通后,用户即可登录,成为一名开发者。
2.2 创建应用
登录微吼云平台后,控制台选择应用管理,进入应用管理页面点击创建应用,根据页面提示信息,完成应用创建。应用创建完成,您可以在控制台界面找到在应用管理界面您可以找到 AppID。
2.3 添加服务
应用创建完成后,选择添加服务,添加聊天服务,添加成功后可在聊天服务下聊天管理的【聊天配置】页面查看AppID
2.4 SDK下载
3 工程配置
3.1 支持平台
- SDK支持iOS 8.0以上系统
3.2 开发环境
- Xcode 8或更高版本
- OS X 10.10或更高版本
3.3 Xcode工程设置
下面通过一个简单的iOS Application工程,说明如和在Xcode工程中配置SDK。
3.3.1 拷贝SDK文件
在本例中,新建一个名字叫做VHSDKDemo的iOS工程,将下载下来的文件夹拷贝至工程目录。目录结构如下图所示:
3.3.2 添加库和Framework
3.3.3 工程设置修改
- AppDelegate.m 文件名修改为AppDelegate.mm
- Build Setting 中 Enable Bitcode 设置为NO
- 设置Info.plist中 App Transport Security Settings -> Allow Arbitrary Loads 设置为 YES
- 设置Info.pplist中 Privacy - Camera Usage Description 是否允许使用相机
- 设置Info.pplist中 Privacy - Microphone Usage Description 是否允许使用麦克风
3.4 验证
下面在VHSDKDemo的代码中,调用SDK的接口,设置appID 获取SDK版本信息,以验证工程设置是否正确。
3.4.1 引用头文件
在AppDelegate.mm开头引用SDK的头文件:
#import "VHLiveBase.h"
3.4.2 添加调用代码
在application: didFinishLaunchingWithOptions:方法中添加代码:
3.4.3 编译运行
如果前面各个步骤都操作正确的话,VHSDKDemo工程应该可以顺利编译通过。在Debug模式下运行APP,Xcode的Console窗格会打印出SDK的版本信息。
至此,工程配置完成。
4 注册APP
[VHLiveBase registerApp:@"xxxxxxxxx"];//AppID:xxxxxxxxx
5 设置第三方ID
[VHLiveBase setThirdPartyUserId:@"xxxxxxxx"];//第三方账号id:xxxxxxxx
6 LOG打印
在 VHLiveBase 中可以设置 log的级别,具体代码如下:
[VHLiveBase setLogLevel:VHLogLevelDebug];
7 获取channel_id、access_token
8 代码对接
8.1 创建IMSDK
SDK 中的 VHImSDK 模块负责实现 IM服务相关功能。
8.2 设置 delegate
- delegate 设置IM代理
8.3 发送聊天内容
现在支持最长消息 200字
9 事件处理
9.1 接收聊天内容
9.2 错误回调
iOS SDK版本更新
日期 | 版本 | 内容 | SDK下载 |
---|---|---|---|
2017.12.29 | v1.0 | 提供iOS平台基本的聊天功能 | 下载 |
Android SDK开发集成
Android SDK简介
简介
微吼云为用户提供了聊天室功能,用户可通过集成SDK,快速在Android平台接入聊天互动服务。
功能特性
- 聊天室实时发送文本消息
- 聊天室实时接收文本消息
Android SDK开发指南
1 概念说明
频道:聊天、文档服务,依赖于频道。例如在使用文档演示时,需要先通过基础通讯服务创建一个频道。并将文档演示方与观看方连接至同一个频道。 消息发送也需要依赖频道的创建来进行消息传送。
智能垃圾过滤:开启智能垃圾过滤,可以为用户智能过滤掉聊天消息中的垃圾消息,帮助用户降低色情、暴恐、涉政等违规风险,节省人工审核成本。
2 接入准备
2.1 成为开发者
申请开通微吼云账号,提供用户资料,微吼服务人员在后台为用户开通平台账号,账号开通后,用户即可登录,成为一名开发者。
2.2 创建应用
登录微吼云平台后,控制台选择应用管理,进入应用管理页面点击创建应用,根据页面提示信息,完成应用创建。应用创建完成,您可以在控制台界面找到在应用管理界面您可以找到 AppID。
2.3 添加服务
应用创建完成后,选择添加服务,添加聊天服务,添加成功后可在聊天服务下聊天管理的【聊天配置】页面查看AppID
2.4 SDK下载
3 工程配置
3.1 开发环境
- Android SDK Tools: android-sdk_22.0.|+
- minSdkVersion: 16
- targetSdkVersion: 22
- Android Studio
3.2 系统要求
- SDK 支持 在 Android 4.1(API 16)及以上系统上运行,但只有 ( Android 4.3) API 18 以上的系统才能开启硬件编码
3.3 接入流程
- 新建gradle工程
- 复制vhallframework1.0.jar到工程lab目录下
- 复制jnilibs文件夹内容到appjni目录下
3.4 库简介
- vhallframework1.0.jar:vhallsdk基础包,用户sdk基础通迅、全局配置、日志管理、权限控制等。
- socket.io 一款公共I/O库,基础通讯功能使用,目前使用截止文档编写之日最新稳定版
3.5 配置权限
3.6 接口简介
3.6.1 VhallSDK初始化
appid为注册应用时配置的应用ID 初始化操作为SDK的入口,一切SDK功能都在初始化成功后才能使用,建议在应用application启动时调用
3.6.2 SDK信息配置
1、配置用户ID
用户ID为客户平台用户唯一标识,建议在用户登录之后配置
2、配置日志显示
设置SDK日志显示(警告和错误级别日志必打印,此开关控制debug/info/verbose级别日志
3.6.3 获取SDK状态
SDK是否初始化成功并处于可用状态,初始化操作会校验appid对应当前包名和签名,请确保配置正确
3.6.4 加入频道
加入频道并接收频道信息,channelid表示当前频道号,如果是lss服务,房间号即为频道号
3.6.5 离开频道
4 功能使用
4.1 获取channel_id、access_token
4.2 集成过程
- 复制vhallims1.0.jar到工程lib目录下
4.3 创建VHIM实例
- ChannelId 频道id 可以通过调用 api 创建
- accessToken 可以通过调用 api 获得
4.4 添加监听
当VHIM创建完毕,需要添加监听消息,每当有消息推送会回调onMessage(),用户需要根据自己的场景解析数据
4.5 进入聊天室
4.6 发送消息及回调
- message 需要发送的消息
- callback 消息发送后的回调
4.7 离开聊天室
Android SDK版本更新
日期 | 版本 | 内容 | SDK下载 |
---|---|---|---|
2017.12.29 | v1.0 | 提供Android平台基本的聊天功能 | 下载 |
Javascript SDK开发集成
Javascript SDK简介
简介
微吼云Javascript SDK,是微吼云面向web开发者提供的基于微吼直播服务的开发工具包,面向开发者提供直播推流、直播观看、点播观看、聊天、文档等功能。此部分为聊天包,用于聊天服务。
功能特性
- 支持websocket和长链接
Javascript SDK开发指南
1 概念说明
频道:聊天、文档服务,依赖于频道。例如在使用文档演示时,需要先通过基础通讯服务创建一个频道。并将文档演示方与观看方连接至同一个频道。 消息发送也需要依赖频道的创建来进行消息传送。
智能垃圾过滤:开启智能垃圾过滤,可以为用户智能过滤掉聊天消息中的垃圾消息,帮助用户降低色情、暴恐、涉政等违规风险,节省人工审核成本。
2 使用步骤
2.1 成为开发者
申请开通微吼云账号,提供用户资料,微吼服务人员在后台为用户开通平台账号,账号开通后,用户即可登录,成为一名开发者。
2.2 创建应用
登录微吼云平台后,控制台选择应用管理,进入应用管理页面点击创建应用,根据页面提示信息,完成应用创建。应用创建完成,您可以在控制台界面找到在应用管理界面您可以找到 AppID。
2.3 添加服务
应用创建完成后,选择添加服务,添加聊天服务,添加成功后可在聊天服务下聊天管理的【聊天配置】页面查看AppID
2.4 页面引用SDK文件
在需要播放视频的页面(包括PC或H5)中引入初始化脚本
<script src="https://static.vhallyun.com/jssdk/vhall-jssdk-chat-1.0.0.js"></script>
<script src="https://static.vhallyun.com/jssdk/vhall-jssdk-base-1.0.0.js"></script>
注意:
- 直接用本地网页是调试不了的
- 上面所有文件都需要引用,而且顺序需要保持与上面一致
- 建议直接复制上面代码
2.5 注册ready事件
Vhall.ready(function(){
//todo
})
注意: 初始化完成之后,会执行ready回调事件,机制同jQuery ready事件,播放器调用逻辑需要写在此事件里。
2.6 初始化SDK配置
初始化配置:
Vhall.config({
appId :'',//应用 ID ,必填
accountId :'',//第三方用户唯一标识,必填
token:'',//token必填
})
注意: appId获取方式:登陆微吼云>>进应用管理>>取得对应AppId token生成方式:通过API生成,生成accessToken接口说明
API文档
调用说明
所有接口通过VhallLive对象来调用,参数是一个对象,除了每个接口本身需要传的参数之外,还有以下通用参数:
- success:接口调用成功时执行的回调函数。
- fail:接口调用失败时执行的回调函数。
- complete:接口调用完成时执行的回调函数,无论成功或失败都会执行。
API接口
1.初始化接口
聊天对象初始化
var chat = new VhallChat({
token:'',//认证令牌,必填
appId:'',//在微吼云申请的appId,必填
channelId:''//频道Id,必填
});
- token生成方式:通过API生成,生成accessToken接口说明
- appId获取方式:登陆微吼云>>进应用管理>>取得对应AppId
- channelId可通过接口获取,创建频道
2.监听聊天消息
注册消息监听事件,示例如下:
//监听聊天消息
chat.on(function(msg){
//console.log(msg)
//在此收到聊天消息,消息内容为msg
//todo
})
3.发送聊天消息
//发送聊天消息
chat.emit("要发送的聊天消息内容");
Javascript SDK版本更新
日期 | 版本 | 内容 | SDK演示 |
---|---|---|---|
2017.12.29 | v1.0 | 提供web平台基本的聊天功能 | SDK演示 |
Demo使用指南
iOS Demo
主要功能
- 发送消息
- 接收消息
示例代码
下载地址
Android Demo
主要功能
- 发送消息
- 接收消息