短剧内容

短剧内容

此章节将演示如何请求在原生环境下请求与展示短剧内容

提示

工程需要引入support-v4legacy-support-v4

剧集列表短剧播放页
剧集列表短剧播放页

短剧运行流程

运行流程

加载短剧

调用ZJTubeAd#loadAd的重载方法请求广告,并在ZJTubeAdLoadListener中获取广告对象与处理错误信息

public class ZJTubeAd {
    
    /**
     * 加载广告
     */
    public static void loadAd(String posId, ZJTubeAdLoadListener loadListener);

    /**
     * 加载广告
     *
     * @param posId          广告位ID
     * @param config         短剧配置
     * @param loadListener   加载回调
     */
    public static void loadAd(String posId,  ZJTubeAdConfig config, ZJTubeAdLoadListener loadListener);

}

短剧配置说明

ZJTubeAdConfig.class

方法说明默认值
isNewUser(boolean)是否为新用户true
setUserId(String)设置用户唯一ID
此处 userId 为必传参数用于定位具体用户的广告观看情况
""
setFreeEpisodeCount(int)设置每个剧集前N集免费
N为开发者需要设置的免费集数
3
setUnlockEpisodeCount(int)设置每次解锁X集
X为开发者设置每次根据条件解锁后给到用户观看的集数
2
isHideTitleBar(boolean)是否隐藏剧集主页的 TitleBarfalse
isDisableUnlockTipDialog(boolean)是否关闭SDK的解锁提示对话框
false时SDK会自动展示解锁对话框
true时需要在showCustomUnlockDialog()回调中展示自定义提示对话框并将用户选择的结果回传给SDK
false
isDisableShowTubePanelEntry(boolean)是否关闭短剧播放页的选集入口false
isHideDetailTitleBar(boolean)是否隐藏播放页的titleBarfalse
isHideDetailBottomTitle(boolean)是否隐藏播放页底部的title文案false
isHideDetailBottomDesc(boolean)是否隐藏播放页底部的内容描述文案false
isHideDetailPlaySeekbar(boolean)是否隐藏播放页底部的进度条false
setProfileName(String)广告联盟参数配置文件,根据需求进行配置""
setTopTubeId(int)设置买量剧集id, 将在热门短剧最左侧位置展示该短剧-1
isHideChangeBtn(boolean)设置是否隐藏换一换按钮false
isHideMoreBtn(boolean)设置是否隐藏更多按钮false

加载回调说明

方法说明
onError(int code, String msg)广告加载出错
code: 错误码
msg: 错误信息
onAdLoaded(ZJTubeAd tubeAd)广告加载成功
tubeAd: 广告加载对象

展示短剧

在加载成功回调中获取到ZJTubeAd对象后,可以配置交互回调、页面回调、视频回调,getFragmentObject()方法获取到Fragment对象后展示

ZJTubeAd 说明

方法说明
setInteractionListener(ZJTubeAdInteractionListener interactionListener)配置交互回调,见交互回调说明
setPageListener(ZJTubeAdPageListener pageListener)配置页面回调(无计数需求可忽略)
setVideoListener(ZJTubeAdVideoListener videoListener)配置视频回调(无计时需求可忽略)
getFragmentObject()获取Fragment对象
onResume()从其他页面切换后需要调用
onDestroy()主动释放资源
onBackPressed()是否终止返回键点击分发

交互回调说明

方法说明
showCustomUnlockDialog(Activity activity, ZJTubeAdItem item, ZJTubeAdUnlockCallback callback)展示自定义解锁对话框,并将用户选择的结果回传给SDK
activity: 当前前台Activity对象
item: 短剧信息,见短剧信息
callback: 用户解锁事件选择结果,见解锁事件回传说明
getUnlockAdPosId(ZJTubeAdItem item)需要返回解锁广告所需的广告位ID(当前仅支持激励广告和插全屏广告)
item: 短剧信息,见短剧信息
onUnlockSuccess()观看广告解锁短剧成功
onUnlockError(int code, String msg)观看广告解锁短剧失败
code: 错误码
msg: 错误信息

解锁事件回传说明

若请求广告时,配置了isDisableUnlockTipDialog(false),会在需要观看广告解锁时回调ZJTubeAdInteractionListener#showCustomUnlockDialog方法:

  • 开发者需要在此回调中根据回传的ZJTubeAdItem对象获取待解锁信息并展示自定义解锁对话框
  • 在对话框关闭时通过回传的ZJTubeAdUnlockCallback对象将用户选择的结果通知给SDK
  • 若没有通知 SDK 用户选择结果,短剧播放页面会一直停留在解锁页面,直到用户点击返回键或点击其他页面
方法说明
callback(boolean isConfirmUnlock)回传用户是否同意观看广告以解锁剧集

短剧信息说明

属性类型说明
idString视频唯一ID
positionint当前位置,从0开始
videoDurationlong视频时长
authorIdString作者ID
authorNameString作者名称
tubeIdlong剧场ID
tubeNameString剧场名称
episodeNumberint剧集序号
totalEpisodeCountString总剧集数
playCountlong观看次数
coverUrlString封面图
isFinishedboolean是否已完结
isLockedboolean是否锁定
freeEpisodeCountint短剧前N集免费
unlockEpisodeCountint每次解锁X集短剧

页面回调说明

有视频播放计数的需求时可以调用setPageListener(ZJTubeAdPageListener)方法配置页面回调

方法说明
onPageEnter(ZJTubeAdItem item)进入页面
onPageResume(ZJTubeAdItem item)页面恢复
onPagePause(ZJTubeAdItem item)页面暂停
onPageLeave(ZJTubeAdItem item)离开页面

视频回调说明

有视频播放计时的需求时可以调用setVideoListener(ZJTubeAdVideoListener)方法配置视频回调

方法说明
onVideoPlayStart(ZJTubeAdItem item)开始播放
onVideoPlayPaused(ZJTubeAdItem item)播放暂停
onVideoPlayResume(ZJTubeAdItem item)播放恢复
onVideoPlayCompleted(ZJTubeAdItem item)播放完成
onVideoPlayError(ZJTubeAdItem item, int what, int extra)视频播放错误
code: 错误码
msg: 错误信息

短剧内容接入示例

短剧内容页属性配置

// 短剧内容页属性配置
private ZJTubeAdConfig generateTubeAdConfig() {
    return new ZJTubeAdConfig.Builder()
            // 是否为新用户
            .isNewUser(true)  
            // 此处 userId 为必传参数(传入的格式可自行定义,也可以是MD5或加密后的,
            // 但必须保证是唯一值且不可过长,用于定位具体用户的广告观看情况)
            .setUserId("userId")
            // 每个剧集前N集免费,默认值为3
            .setFreeEpisodeCount(3)
            // 每次解锁X集,默认值为2
            .setUnlockEpisodeCount(2)
            // 是否隐藏剧集主页的TitleBar,默认值为false
            .isHideTitleBar(true)
            // 是否关闭SDK的解锁提示对话框,默认值为false
            // true时可以在showAdIfNeeded回调中自定义提示对话框,默认值为false
            .isDisableUnlockTipDialog(false)
            // 是否关闭短剧播放页的选集入口,默认值为false
            .isDisableShowTubePanelEntry(false)
            // 是否隐藏播放页的titleBar,默认值为false
            .isHideDetailTitleBar(false)
            // 是否隐藏播放页底部的title文案,默认值为false
            .isHideDetailBottomTitle(false)
            // 是否隐藏播放页底部的内容描述文案,默认值为false
            .isHideDetailBottomDesc(false)
            // 是否隐藏播放页底部的进度条,默认值为false
            .isHideDetailPlaySeekbar(false) 
            // 广告联盟参数配置文件(如有需求请联系我们获取)
            .setProfileName("")
            // 设置买量剧集id, 将在热门短剧最左位置展示该短剧 
            .setTopTubeId(-1) 
            // 是否隐藏换一换按钮,默认为false
            .isHideChangeBtn(false) 
            // 设置是否隐藏更多按钮
            .isHideMoreBtn(false)  
            .build();
    }
// 短剧内容页属性配置
private fun generateTubeAdConfig(): ZJTubeAdConfig {
    return ZJTubeAdConfig.Builder() 
        // 是否为新用户
        .isNewUser(true) 
        // 此处 userId 为必传参数(传入的格式可自行定义,也可以是MD5或加密后的,
        // 但必须保证是唯一值且不可过长,用于定位具体用户的广告观看情况)
        .setUserId("userId") 
        // 每个剧集前N集免费,默认值为3
        .setFreeEpisodeCount(3) 
        // 每次解锁X集,默认值为2
        .setUnlockEpisodeCount(2) 
        // 是否隐藏剧集主页的TitleBar,默认值为false
        .isHideTitleBar(true) 
        // 是否关闭SDK的解锁提示对话框,默认值为false
        // true时可以在showAdIfNeeded回调中自定义提示对话框,默认值为false
        .isDisableUnlockTipDialog(false) 
        // 是否关闭短剧播放页的选集入口,默认值为false
        .isDisableShowTubePanelEntry(false) 
        // 是否隐藏播放页的titleBar,默认值为false
        .isHideDetailTitleBar(false) 
        // 是否隐藏播放页底部的title文案,默认值为false
        .isHideDetailBottomTitle(false) 
        // 是否隐藏播放页底部的内容描述文案,默认值为false
        .isHideDetailBottomDesc(false) 
        // 是否隐藏播放页底部的进度条,默认值为false
        .isHideDetailPlaySeekbar(false) 
        // 广告联盟参数配置文件(如有需求请联系我们获取)
        .setProfileName("") 
        // 设置买量剧集id, 将在热门短剧最左位置展示该短剧
        .setTopTubeId(-1) 
        // 是否隐藏换一换按钮,默认为false
        .isHideChangeBtn(false) 
        // 设置是否隐藏更多按钮
        .isHideMoreBtn(false)
        .build()
}

加载与展示

// 加载广告
ZJTubeAd.loadAd("posId", generateTubeAdConfig(), new ZJTubeAdLoadListener() {

    /**
     * 加载出错
     *
     * @param code 错误码
     * @param msg  错误信息
     */
    @Override
    public void onError(int code, @NonNull String msg) {
        Toast.makeText(requireContext(), "加载出错: " + code + "-" + msg, Toast.LENGTH_SHORT).show();
    }

    /**
     * 加载成功
     *
     * @param ad 广告
     */
    @Override
    public void onAdLoaded(@NonNull ZJTubeAd ad) {
        Toast.makeText(requireContext(), "加载成功", Toast.LENGTH_SHORT).show();
        TubeFragment.this.ad = ad;

        ad.setInteractionListener(new ZJTubeAdInteractionListener() {
            
            /**
             * 配置短剧解锁⼴告交互回调
             * 如禁止了SDK内置的解锁对话框,需要在此回调中展示自定义解锁对话框
             * 必须调用UnlockCallback的callback方法返回用户是否同意解锁
             */
            @Override
            public void showCustomUnlockDialog(Activity activity, @NonNull ZJTubeAdItem item, @NonNull ZJTubeAdUnlockCallback callback) {
                unlockTipDialog = new CustomUnlockTipDialog(item);
                unlockTipDialog.setListener(new CustomUnlockTipDialog.DialogListener() {
                    
                    @Override
                    public void confirm() {
                        callback.callback(true);
                        unlockTipDialog = null;
                    }

                    @Override
                    public void cancel() {
                        callback.callback(false);
                        unlockTipDialog = null;
                    }
                });
                unlockTipDialog.show(((FragmentActivity) activity).getSupportFragmentManager(), TAG);
            }

            /**
             * 获取解锁广告的广告位ID
             * 仅支持激励广告和插全屏,需要返回正确的广告位ID,返回无效的广告位ID时会无法解锁
             */
            @Override
            public String getUnlockAdPosId(@NonNull ZJTubeAdItem zjTubeAdItem) {
                String posId;
                String tip;
                if (new Random().nextBoolean()) {
                    posId = DataCenter.PosId.REWARDED_AD;
                    tip = "加载激励广告";
                } else {
                    posId = DataCenter.PosId.INTERSTITIAL;
                    tip = "加载插屏广告";
                }
                Toast.makeText(getContext(), tip, Toast.LENGTH_SHORT).show();
                return posId;
            }

            /**
             * 观看广告解锁短剧成功
             */
            @Override
            public void onUnlockSuccess() {
                Toast.makeText(getContext(), "观看广告解锁短剧成功", Toast.LENGTH_SHORT).show();
            }

            /**
             * 观看广告解锁短剧失败
             *
             * @param code 错误码
             * @param msg  错误信息
             */
            @Override
            public void onUnlockError(int code, @NonNull String msg) {
                Toast.makeText(getContext(), "观看广告解锁短剧失败:[" + code + "-" + msg + "]", Toast.LENGTH_SHORT).show();
            }

        });

        // 展示 Fragment
        getChildFragmentManager()
                .beginTransaction()
                .add(R.id.container, ad.getFragmentObject())
                .show(ad.getFragmentObject())
                .commit();
    }

});
// 加载广告
ZJTubeAd.loadAd("posId", generateTubeAdConfig(), object : ZJTubeAdLoadListener {

    /**
     * 加载出错
     *
     * @param code 错误码
     * @param msg  错误信息
     */
    override fun onError(code: Int, msg: String) {
        Toast.makeText(requireContext(), "加载出错: $code-$msg", Toast.LENGTH_SHORT).show()
    }

    /**
     * 加载成功
     *
     * @param ad 广告
     */
    override fun onAdLoaded(ad: ZJTubeAd) {
        Toast.makeText(requireContext(), "加载成功", Toast.LENGTH_SHORT).show()
        this@TubeFragment.ad = ad

        ad.setInteractionListener(object : ZJTubeAdInteractionListener {

            /**
             * 配置短剧解锁⼴告交互回调
             * 如禁止了SDK内置的解锁对话框,需要在此回调中展示自定义解锁对话框
             * 必须调用UnlockCallback的callback方法返回用户是否同意解锁
             */
            override fun showCustomUnlockDialog(
                activity: Activity,
                item: ZJTubeAdItem,
                callback: ZJTubeAdUnlockCallback,
            ) {
                unlockTipDialog = CustomUnlockTipDialog(item)
                unlockTipDialog.setListener(object : DialogListener() {
                    fun confirm() {
                        callback.callback(true)
                        unlockTipDialog = null
                    }

                    fun cancel() {
                        callback.callback(false)
                        unlockTipDialog = null
                    }
                })
                unlockTipDialog.show((activity as FragmentActivity).supportFragmentManager, TAG)
            }

            /**
             * 获取解锁广告的广告位ID
             * 仅支持激励广告和插全屏,需要返回正确的广告位ID,返回无效的广告位ID时会无法解锁
             */
            override fun getUnlockAdPosId(zjTubeAdItem: ZJTubeAdItem): String {
                val posId: String
                val tip: String
                if (Random().nextBoolean()) {
                    posId = DataCenter.PosId.REWARDED_AD
                    tip = "加载激励广告"
                } else {
                    posId = DataCenter.PosId.INTERSTITIAL
                    tip = "加载插屏广告"
                }
                Toast.makeText(getContext(), tip, Toast.LENGTH_SHORT).show()
                return posId
            }

            /**
             * 观看广告解锁短剧成功
             */
            override fun onUnlockSuccess() {
                Toast.makeText(getContext(), "观看广告解锁短剧成功", Toast.LENGTH_SHORT).show()
            }

            /**
             * 观看广告解锁短剧失败
             *
             * @param code 错误码
             * @param msg  错误信息
             */
            override fun onUnlockError(code: Int, msg: String) {
                Toast.makeText(
                    getContext(),
                    "观看广告解锁短剧失败:[$code-$msg]",
                    Toast.LENGTH_SHORT
                ).show()
            }
            
        })

        // 展示 Fragment
        getChildFragmentManager()
            .beginTransaction()
            .add(R.id.container, ad.fragmentObject)
            .show(ad.fragmentObject)
            .commit()
    }

})