Android JVaas SDK API文档
一、SDK 概要
UISDK为移动应用提供内容分发功能,为客户提供较为简洁的API接口,方便第三方应用快速的集成并实现内容分发功能。
UISDK提供的功能如下:
- 绘制频道Feed流列表
- 绘制小视频列表
二、SDK 类
SDK主要提供了以下类:
基础类:
- JVaasContentInterface:主要提供初始化。
- JGUIConfig:用于配置个性化UI
- MediaInfo:视频的model类
- MediaDetail:视频详情的model类
- JGUser:登陆用户类
页面:
- ChannelFragment:频道导航栏 + feed流页面
- JGFeedFragment:feed流页面
- JGLittleVideoFragment:小视频页面
- JGLittleChannelFragment:小视频页面+关注页面
- KSLittleVideoFragment:类快手样式小视频页面
- VideoActivity:播放页面Activity
三、接入代码
3.1 SDK 初始化
3.1.1 代码示例
3.1.1.1 初始化配置
JVaasContentInterface.setDebugMode(boolean debugMode);
- 接口说明:
- 设置是否开启debug模式。true则会打印更多的日志信息。建议在init接口之前调用。
- 参数说明:
- debugMode:debug开头
- 调用示例:JVaasContentInterface.setDebugMode(true);//debug设置,在初始化前调用
JVaasContentInterface.setDebugMode(true);//debug设置,在初始化前调用
此代码块在浮窗中显示
- 接口说明:
JVaasContentInterface.init(Application application);
- 接口说明
- 初始化接口。
- 参数说明:
- application:上下文
- 调用示例:JVaasContentInterface.init(this);//初始化
JVaasContentInterface.init(this);//初始化
此代码块在浮窗中显示
- 接口说明
JVaasContentInterface.queryEnabled(Context context, RequestCallback requestCallback);
- 接口说明:
- appkey是否可用。
- 参数说明:
- context:上下文
- requestCallback:回调接口
- 回调说明:
- void onSuccess()
- 可用
- void onError(int code, String result)
- code:错误码
- result:错误信息
- void onSuccess()
- 调用示例:
- 接口说明:
JVaasContentInterface.queryEnabled(this, new RequestCallback() {
@Override
public void onSuccess() {
}
@Override
public void onError(int code, String result) {
}
});
code | result |
---|---|
9002 | disabled |
4001 | Request method not supported |
4002 | http media type invalid |
4010 | parameter invalid |
4011 | auth empty |
4012 | encrypt fail |
4013 | decrypt fail |
4014 | invalid appKey |
4015 | body invalid |
4016 | appKey offline (表示未开通过 vaas 业务的 appKey) |
3.1.1.2 页面UI配置
JGUIConfig config = JGUIConfig.getInstance();
config.littleComment(CommentConfig.CommentType.SHOW_COMMENT_LIST);//小视频评论展现形式
config.littleLikeShow(true);//是否显示小视频点赞
config.littleShareShow(true);//是否显示小视频分享
config.littleShowAvatar(true);//是否显示作者头像
config.littleShowGuide(true);//是否显示新手引导滑动浮层(第一次安装进入显示)
config.feedAvatarClickable(false);//短视频头像是否可以点击
config.feedPlayAuto(true);//feed自动播放(setPlayerStyle(FeedConfig.STYLE_FEED_PLAY) 时有效)
config.feedPlayStyle(FeedConfig.STYLE_FEED_PLAY);//设置feed播放方式,STYLE_FEED_PLAY:feed流当前播放, STYLE_NATIVE:跳转播放详情页播放
config.feedShowAvatar(true);//是否显示作者头像
config.feedSwipeRefreshEnable(true);//是否可以下拉刷新
config.videoComment(CommentConfig.CommentType.SHOW_COMMENT_ALL);//短视频评论展现形式
config.videoLikeShow(true);//是否显示短视频点赞
config.videoShareShow(true);//是否显示短视频分享
config.followAvailable(true);//是否显示关注按钮
config.setLittleTitleBottom(0)//设置小视频标题(所有底部的文字内容)距离底部的间距,单位dp
config.setLittleHotBarBottom(0)//设置小视频 热点view距离底部边距,单位dp
常量说明:
类名 | 常量说明 |
---|---|
CommentConfig | 设置播放页评论显示类,目前支持一下3种: CommentType.SHOW_COMMENT_ALL; //显示评论列表,并支持评论 CommentType.SHOW_COMMENT_LIST; //只显示评论列表,不支持评论 CommentType.DISMISS_COMMENT //隐藏评论列表 |
FeedConfig | 设置feed播放方式,目前支持一下2种: FeedConfig.STYLE_FEED_PLAY; //feed流当前页播放 FeedConfig.STYLE_NATIVE; //跳到播放详情页播放 |
3.1.1.3 回调相关
config.registerShareCallBack(shareCallback);//分享回调注册
config.unRegisterShareCallBack();//注销
config.registerAvatarClick(onAvatarClickListener);//头像点击回调
config.unRegisterAvatarClick();//注销
config.registerCommentCallBack(commentCallback);//注册评论回调
config.unregisterCommentCallBack();//注销
config.registerLikeCallBack(likeCallback); //注册点赞回调
config.unregisterLikeCallBack();//注销
config.registerLittleVideoCallBack(onLittleVideoCallBack);//小视频位置滑动监听
config.unRegisterLittleVideoCallBack();//注销
config.registerRelateClick(onRelateVideoListener);//视频详情页item点击回调
config.unRegisterRelateClick();//注销
/***注意***/
/***如果上述监听配置在具备生命周期的组件中,如Activity或Fragment中, ***/
/***需在组件的onDestory()中解注册监听,否则有内存泄漏的风险,解注册代码如下:***/
config.unRegisterXXXXXXXXXXX();
3.1.1.4 回调接口
//分享回调注册
config.registerShareCallBack(new ShareCallback() {
@Override
public void onShare(Context context, MediaInfo mediaInfo) {
//mediaInfo 分享的视频信息
Log.d(TAG, "onShare mediaInfo:" + mediaInfo);
}
});
//头像点击回调
config.registerAvatarClick(new OnAvatarClickListener() {
@Override
public void onAvatarClick() {
Log.d(TAG, "onAvatarClick");
}
});
//注册评论回调
config.registerCommentCallBack(new CommentCallback() {
@Override
public void onCommentClick(String videoID) {
Log.e(TAG, "onCommentClick 评论点击 " + videoID);
}
@Override
public void onCommentSend(String videoID) {
Log.e(TAG, "onCommentSend 评论发送 " + videoID);
}
@Override
public boolean onCommentShow(String videoID) {
Log.e(TAG, "onCommentShow 评论展示 " + videoID);
return false;
}
@Override
public void onCommentHide(String videoID) {
Log.e(TAG, "onCommentHide 评论关闭 " + videoID);
}
});
//注册点赞回调
config.registerLikeCallBack(new LikeCallback() {
@Override
public void onLike(String videoID, boolean isLike) {
Log.e(TAG, isLike ? "点赞:" + videoID : "取消点赞:" + videoID);
}
});
//小视频位置滑动监听
config.registerLittleVideoCallBack(new OnLittleVideoCallBack() {
@Override
public void onPositionChange(int position) {
Log.e(TAG, "当前位置:" + position);
}
});
//视频详情页item点击回调
config.registerRelateClick(new OnRelateVideoListener() {
@Override
public void onRelateClick(String videoID) {
Log.e(TAG, "相关视频被点击了:" + videoID);
}
});
3.2 短视频Feed流页面
3.2.1 Feed流页面初始化
ChannelFragment fragment = new ChannelFragment();
FragmentManager manager = getSupportFragmentManager();
manager.beginTransaction().replace(R.id.content, fragment).commitAllowingStateLoss();
如果需要刷新页面可使用:
fragment.refresh()
3.2.2 单频道Feed流页面(不带频道导航栏)
Channel channel = new Channel();
channel.setId(String id);//设置频道id
JGFeedFragment fragment = JGFeedFragment.newInstance(channel);
如果需要刷新页面可使用:
fragment.refresh()
3.3 小视频页面
LittleVideoConfig.getInstance().setVideoLoop(true);//小视频是否循环播放
3.3.1 小视频初始化(类抖音样式)
JGLittleVideoFragment fragment = JGLittleVideoFragment.newInstance();
manager.beginTransaction().replace(R.id.content, fragment).commitAllowingStateLoss();
小视频页面的超前预加载:提高首次进入小视频界面视频加载速度,建议添加
//建议放在小视频页面展示之前调用,例如在Splash页面或MainActivity中调用
JGLittleVideoFragment.preloadVideo()
小视频常见方法:
方法名 | 方法说明 |
---|---|
onPause()、 onResume()、onHiddenChange(boolean hidden)、 setUserVisibleHint(boolean) |
如果在Fragment内嵌JGLittleVideoFragment,需要手动回调以下Fragment生命周期函数。直接在Activity里面使用则不需要。否则会造成不可见播放等异常情况。 |
3.3.2 小视频初始化(小视频页面+关注页面)
JGLittleChannelFragment jgLittleChannelFragment = JGLittleChannelFragment.newInstance();
manager.beginTransaction().replace(R.id.short_content, jgLittleChannelFragment).commitAllowingStateLoss();
3.3.3 小视频初始化(快手样式)
KSLittleVideoFragment ksVideoFragment = KSLittleVideoFragment.newInstance();
manager.beginTransaction().replace(R.id.short_content, ksVideoFragment).commitAllowingStateLoss();
3.4 播放页面使用
VideoActivity.start(Context context, MediaInfo mediaInfo);
3.5 局部信息流
局部信息流提供了feed单卡片样式,小视频单卡片样式,及小视频多卡片样式,丰富了信息流的展示,以满足多样化的信息流展示需求。 注:使用信息流功能需将SDK升级至1.1.0或以上版本 注:参考一览云demo的StreamTestActivity
3.5.1 feed单卡片信息流
默认获取一个feed信息流并展示
//1.获取feed流单卡片操作接口
FeedStream feedStream = StreamManager.create().getFeedStream();
//2.直接请求并展,传入的viewGroup容器大小只控制宽度即可,高度自适应
feedStream.load(context).into(viewGroup);
//支持返回渲染好的view,自行处理view的添加操作
View view = feedStream.load(context).getView();
对请求进行简单配置,然后请求并展示
//1.获取feed流单卡片操作接口
FeedStream feedStream = StreamManager.create().getFeedStream();
//2.数据请求配置
StreamOption.Builder builder = new StreamOption.Builder()
.videoNum(4)//一次请求数据的条数
.requestMode(RequestMode.ALWAYS_NEW)//数据请求的模式,具体含义见下方说明
.dataObtainMode(DataObtainMode.LOOP);//多条数据时,填充单卡片数据的数据选择模式
feedStream.option(builder.build()).load(context).into(viewGroup);
//支持返回渲染好的view,自行处理view的添加操作
View view = feedStream.option(builder.build()).load(context).getView();
数据请求模式RequestMode说明
数据请求模式 | 说明 |
---|---|
RequestMode.FIXED | 默认为FIXED(固定数据)模式,此模式下请求一次数据后,数据的填充用已请求的数据,不在请求新的数据。 |
RequestMode.ALWAYS_NEW | 总是最新的,每次调用load都会返回新的数据填充view |
卡片获取数据模式DataObtainMode说明
数据获取模式 | 说明 |
---|---|
DataObtainMode.DEFAULT | 默认返回数据的第一条 |
DataObtainMode.LOOP | 循环返回 |
DataObtainMode.RANDOM | 随机返回 |
3.5.2 小视频单卡片信息流
默认获取一个小视频信息流并展示
//1.获取小视频信息流单卡片操作接口
LittleStream littleStream = StreamManager.create().getLittleStream();
//2.直接请求并展,传入的viewGroup容器大小只控制宽度即可,高度自适应
littleStream.load(context).into(viewGroup);
//支持返回渲染好的view,自行处理view的添加操作
View view = littleStream.load(context).getView();
对请求进行简单配置,然后请求并展示
//1.获取小视频信息流单卡片操作接口
LittleStream littleStream = StreamManager.create().getLittleStream();
//2.数据请求配置
StreamOption.Builder builder = new StreamOption.Builder()
.videoNum(4)//一次请求数据的条数
.requestMode(RequestMode.ALWAYS_NEW)//数据请求的模式,具体含义见下方说明
.dataObtainMode(DataObtainMode.LOOP);//多条数据时,填充单卡片数据的数据选择模式
littleStream.option(builder.build()).load(context).into(viewGroup);
//支持返回渲染好的view,自行处理view的添加操作
View view = littleStream.option(builder.build()).load(context).getView();
3.5.3 小视频多卡片样式
获取小视频多卡片信息流并展示
//1.获取小视频多卡片信息流操作接口
LittleStream cardStream = StreamManager.create().getCardStream();
//2.直接请求并展
littleStream.load(context).into(viewGroup);
//支持返回渲染好的view,自行处理view的添加操作
View view = littleStream.load(context).getView();
对请求进行简单配置,然后请求并展示
//1.获取小视频信息流单卡片操作接口
LittleStream littleStream = StreamManager.create().getLittleStream();
//2.数据请求配置
StreamOption.Builder builder = new StreamOption.Builder()
.videoNum(4)//一次请求数据的条数
.requestMode(RequestMode.ALWAYS_NEW)//数据请求的模式,具体含义见下方说明
.dataObtainMode(DataObtainMode.LOOP);//多条数据时,填充单卡片数据的数据选择模式
littleStream.option(builder.build()).load(context).into(viewGroup);
//支持返回渲染好的view,自行处理view的添加操作
View view = littleStream.option(builder.build()).load(context).getView();
3.6 视频播放回调
JGPlayerConfig.config().registerPlayerCallBack(new OnPlayerCallBack() {...})
/***注意***/
/***如果上述视频监听配置在具备生命周期的组件中,如Activity或Fragment中, ***/
/***需在组件的onDestory()中解注册监听,否则有内存泄漏的风险,解注册代码如下:***/
JGPlayerConfig.config().unRegisterPlayerCallback();
//OnPlayerCallBack 回调方法相关说明
public interface OnPlayerCallBack {
/**
* 开始播放
* @param pager 播放回调来源
JGPlayerConfig.PAGE_FEED feed流页
JGPlayerConfig.PAGE_LITTLE 小视频页
JGPlayerConfig.PAGE_DETAIL 播放详情页(JGVideoFragment)
JGPlayerConfig.PAGE_WEB feed流 H5播放页
* @param videoID 视频id
* @param taskID 本次播放任务唯一标识
*/
void onStart(String pager,String videoID, String taskID);
/**
* 暂停播放
*
* @param videoID 视频id
* @param taskID 本次播放任务唯一标识
*/
void onPause(String pager,String videoID, String taskID);
/**
* 继续播放
*
* @param videoID 视频id
* @param taskID 本次播放任务唯一标识
*/
void onResume(String pager,String videoID, String taskID);
/**
* 播放完成
*
* @param videoID 视频id
* @param taskID 本次播放任务唯一标识
*/
void onComplete(String pager,String videoID, String taskID);
/**
* 在循环播放模式下,一次播放完成
*
* @param videoID 视频id
* @param taskID 本次播放任务唯一标识
* @param num 第几次循环播放
*/
void onLoopComplete(String pager,String videoID, String taskID, int num);
/**
* 视频卡顿,开始缓冲
*
* @param videoID 视频id
* @param taskID 本次播放任务唯一标识
*/
void onStuckStart(String pager,String videoID, String taskID);
/**
* 视频卡顿,缓冲完毕,继续播放
*
* @param videoID 视频id
* @param taskID 本次播放任务唯一标识
*/
void onStuckEnd(String pager,String videoID, String taskID);
/**
* 视频播放错误
*
* @param videoID 视频id
* @param taskID 本次播放任务唯一标识
*/
void onError(String pager,String videoID, String taskID);
/**
* 视频停止
*
* @param videoID 视频id
* @param taskID 本次播放任务唯一标识
*/
void onStop(String pager,String videoID, String taskID);
}
3.7 实时热点新闻
SDK提供了一个接口,通过该接口可以获取一些实时热点新闻数据,这些新闻是由我们的编辑人工挑选出来的,客户端在获取这些数据之后可以自己渲染UI,用户点击之后通过sdk的方法跳转到播放页(VideoActivity.start(Context context, MediaInfo info);) 使用该功能时客户端需要加入展现上报,这样通过数据分析编辑可以在挑选视频时更有针对性,提高用户的点击率 示例代码
JVaasContentDataRequest.videoHot(params, new CallBack<MediaList>() {
@Override
public void onSuccess(MediaList data) {
}
@Override
public void onError(int httpCode, String code, String msg) {
}
});
//展现上报:
JVaasContentReporter.reportVideoShow(mMediaInfo,position);
params为一个String类型的Map,里面参数说明如下:
参数名称 | 类型 | 默认值 | 是否必传 | 说明 |
---|---|---|---|---|
begin_time | String | 无 | 否 | 指定区间开始时间戳, 时间戳单位为秒,默认不传,代表获取最新的数据 |
end_time | String | 无 | 否 | 指定区间结束时间戳, 时间戳单位为秒,默认不传,代表获取最新的数据 |
type | String | 1 | 是 | 1为横版视频,2为竖版视频 |
key | String | 无 | 否 | 内容池名称,默认不传 |
pg | String | 1 | 否 | 需要翻页时传入的页数 |
sz | String | 10 | 否 | 每次返回视频的个数 |
3.8 社交模块
社区功能主要包括评论、点赞、分享等,未登录用户只能进行浏览,不能进行参与。如发表评论、删除评论等等。
3.8.1 用户登陆、退出
JGUser.getInstance().login(nick, avatar, phone, userId);
JGUser为单例使用,常用的方法如下。
方法名 | 方法说明 | 备注 |
---|---|---|
void login(String nickname, String avatar, String phone, String userId) | nickname:用户昵称。必传。 avatar:用户头像。 phone:用户手机号。非必传 userId:用户id。必传 |
调用时机:在APP启动和用户登陆后 |
void logout() | 退出登录 | 调用时机:在用户主动退出登录后 |
String getToken() | 获取用户token | 在登陆后获取 |
3.9 获取 频道列表
获取 1横版/2竖版 频道列表
/**
*
* @param videoType 1:横版,2:竖版
* @param callback
*/
JVaasContentDataRequest.getChannels(int videoType, new CallBack<ChannelList>() {
@Override
public void onSuccess(ChannelList data) {
}
@Override
public void onError(int httpCode, String code, String msg) {
}
});
四、自定义内容
4.1 继承BaseViewHolder和IExtraHolder 自定义ViewHolder
public class ExtraViewHolder extends BaseViewHolder<ExtraData> implements IExtraHolder {
public ExtraViewHolder(Context context, ViewGroup parent) {
//在构造方法中填入参数和自定义的布局文件
super(context, parent, R.layout.feed_item);
}
private TextView textView;
@Override
protected void initView() {
// 在此方法中初始化 view
textView = itemView.findViewById(R.id.text_content);
}
@Override
public void onBindViewHolder(ExtraData extra) {
//在此处绑定数据,此方法会在RecycleView 的 Adapter 的 onBindViewHolder方法中调用
textView.setText("我是自定义内容");
}
@Override
public void onResume() {
//如果此item 在屏幕中,则在页面 onResume 被时调用
}
@Override
public void onPause() {
//如果此item 在屏幕中,则在页面 onPause 被时调用
}
@Override
public void onDestroy() {
//页面被onDestroy销毁时 所有被创建的viewholder 都会被调用,可在此处做释放资源的操作
}
@Override
public void onItemSelected(boolean isSelected) {
// 在抖音样式下,当item被选中时(被滑到屏幕中间)会被调用
}
}
4.2 横版列表添加自定义内容
1.设置数据回调
FeedConfig.getInstance().setExtraCallback(new ExtraDataCallback<ExtraData>() {
@Override
public List<ExtraData> getData() {
// 在此方法中返回自定义类型的数据,信息流会根据下面的规则
ArrayList<ExtraData> list = new ArrayList();
list.add(new ExtraData());
return list;
}
@Override
public int getInterval() {
// 间隔数,1表示每隔一个视频会插入一条自定义的内容
return 1;
}
@Override
public int getStartIndex() {
// 表示从列表的第几个位置开始插入自定义内容
return 1;
}
@Override
public BaseViewHolder<ExtraData> createViewHolder(Context context, ViewGroup parent) {
//返回一个BaseViewHolder类型的ExtraViewHolder,ExtraViewHolder
return new ExtraViewHolder(context,parent);
}
});
4.3 类抖音样式添加自定义内容
//通过LittleVideoConfig来注册配置接口,范型填入自己需要的类型
LittleVideoConfig.getInstance().setExtraCallback(new ExtraDataCallback<ExtraData>() {
@Override
public List<ExtraData> getData() {
// 在此方法中返回自定义类型的数据,信息流会根据下面的规则
ArrayList<ExtraData> list = new ArrayList();
list.add(new ExtraData());
return list;
}
@Override
public int getInterval() {
// 间隔数,1表示每隔一个视频会插入一条自定义的内容
return 1;
}
@Override
public int getStartIndex() {
// 表示从列表的第几个位置开始插入自定义内容
return 1;
}
@Override
public BaseViewHolder<ExtraData> createViewHolder(Context context, ViewGroup parent) {
//返回一个BaseViewHolder类型的ExtraViewHolder,ExtraViewHolder
return new ExtraViewHolder(context,parent);
}
});