# 分享视频模块 ------ #### **简介** 小游戏生态中，普遍把平台提供的分享/视频接口更多用于某个奖励领取、获取n倍奖励、游戏死亡复活、转盘额外次数获得等等一种有效途径（分享：拉取新用户，视频：赚钱广告费）；噗嗤游戏在分享or视频推送不断的探索迭代中，总结了一套分享/视频积分策略，集成在SDK中开放给开发者，开发者只需对游戏中分享视频功能点命名一个英文名称key（分享视频key），这个key关联分享文案、分享图、分享开关（推送类型）、视频uid等等在后台配置好，使用SDK提供的一个dispatch api传入英文名称key即可完成接入工作。 - 分享/视频配置可以让开发者在后台中动态修改相关功能点的分享/视频配置内容。 - 新增某个功能的分享点配置、在线修改相关功能点的分享图或文案、在线切换某个功能点按钮的分享/视频推送类型。 - 调用SDK的dispatch api，dispatch会根据后台配置的分享开关（推送类型）自动进行分发：推送分享还是视频全权交由SDK去处理，开发者只需要传入成功/失败回调函数，成功回调函数处理发放领取奖励、n倍奖励、成功复活等操作，失败回调函数处理参数传递的msg信息。 #### **疑惑解答** 1. 为什么要引入这个模块？ > 游戏中很多n倍奖励、复活、额外奖励等功能点通常需要分享或者视频才能额外获得，游戏上线后，运营很有可能会对某些功能点有额外的需求修改：a功能点获取由分享改成视频方式获取、b功能点由视频改成分享方式获取、c功能点需要在前面n次看视频获得后全是分享获得、为某某功能的分享图想换一个、拉取视频不成功自动切换分享等等；为了应对这些不同情形，我们把分享和视频点包装成一个模块，a功能点也不在局限于只是简单的分享、b功能只是视频，而是通过后台分享开关去灵活切换。所有功能点入口调用都是使用dispatch，每个功能点都是转化为一个分享视频key在后台管理。 2. 什么是分享视频key？ > 分享视频key是一个功能点的英文名称，这个key配置在后台中，关联分享文案、分享图、分享开关（推送类型）、视频uid等等信息。某个功能点（不论是分享还是视频方式）调用dispatch传入这个key，SDK会读取这个key关联的信息，根据分享开关（推送类型）来推送分享（需要分享文案、分享图）还是推送视频（需要视频uid）。 3. 什么是分享视频分发？ > 调用dispatch api传入分享视频key，SDK会查找这个key在后台配置的数据，SDK读取数据中分享开关（推送类型）的字段信息，通过这个开关类型来判断推给用户是分享还是视频，这个根据类型来推送的操作就是分发操作。 4. 游戏中之前是玩家分享n次后变成看视频或者是看视频n次后全是分享，dispatch能满足吗？ > 上面的问题dispatch也同样支持，还是同样的调用方式，不需要做其他额外处理，dispatch是怎么做到的了：分享开关（推送类型）有一个分享积分选择项，这个选项就是通过积分策略实现了上面问题。 > #### **后台使用** 配置分享视频配置，登录后台->头部tab切换到【游戏数据】->【配置相关】->【分享/视频配置】可新增、编辑修改分享/视频内容： ![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_023.png "🔍点击查看大图") ![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_024.png "🔍点击查看大图") 接入分享视频模块后，后台已经对分享和视频数据分别进行整理统计了，游戏接入方可实时查看分享/视频的各项数据: 查看分享分析，登录后台->头部tab切换到【游戏数据】->【产品分析】->【分享分析】可阅览游戏分享数据的各项统计： ![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_025.png "🔍点击查看大图") 查看视频广告详情，登录后台->头部tab切换到【游戏数据】->【配置相关】->【视频广告详情】可阅览游戏各个功能点视频数据统计： ![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_026.png "🔍点击查看大图") #### **接入必读** - 接入此模块前，请[**前往sdk/config.js文件中配置【IsUseShareModule: true 】开启分享视频模块功能**](install.md#config_env)，此参数配置为true，才能正常使用此模块的功能，SDK启动时会自动拉取后台配置所有功能点的分享/视频配置列表。 - 微信小游戏开发者接入此模块，如果游戏有很多分享点，提审时避免触犯微信平台的[滥用分享行为](https://developers.weixin.qq.com/minigame/product/#_5-1-滥用分享行为)，在后台【配置参数】中配置了一个SDK内部使用的[配置参数](online.md)share_unlock，进行分享开关切换：1（开启）0（关闭），提审时设置为0，审核通过后设为1。share_unlock设置为0，所有的功能点不会分享完成、拉起看完视频后发放奖励，而是直接发放奖励，这样就能避免审核时，如果是推送分享拉起分享，被微信认为是诱导分享，被拒的可能性。 - sdk/config.js的配置参数ShareRightKey，表示右上角分享的分享视频key，请配置到后台【分享/视频配置】中。如果ShareRightKey配置不为空，SDK会自动调用微信的右上角分享接口(wx.onShareAppMessage)，实现右上角分享功能，注意的是开发者在游戏中已经有注册wx.onShareAppMessage需要删除掉，不然游戏中onShareAppMessage的注册事件会把SDK中的注册事件处理函数覆盖掉，导致还是使用的是开发者注册的右上角分享功能。 - sdk/config.js的配置参数ShareData表示默认分享视频配置，此条配置应用在两种情况下： > 1、请求功能点的分享/视频配置列表出错，使用key去查找对应的分享配置肯定是查找不到的，会读取此条默认数据。 > > > > 2、请求功能点的分享/视频配置列表成功了，但是这个key没有配置到后台，也会读取此条默认数据 #### **接入**API： | **名称** | **功能说明** | | ------------------------------- | ------------------------------------------------------------ | | PCSDK.shareVideo.share | 普通分享，不需要处理回调的场景，例如分享到群、分享到好友，这些普通的分享，而不用处理成功/失败回调函数。 | | PCSDK.shareVideo.dispatch | 分享视频分发入口，传入功能点英文命名的分享/视频key | | PCSDK.shareVideo.getShareVideoType | 根据功能点在后台配置的分享/视频key，得到此功能点分享开关（推送类型）SDK计算得到最终推送类型：-1(无视频无分享)、0(分享）、1(异步分享）、5(分享积分)、2(视频)、3(无视频则分享)、4(视频和分享)(控制分享和视频两个按钮的显示) | 1. ##### **share** ```javascript PCSDK.shareVideo.share(key:sring, params?: any, opts?: any): void ``` 定义：普通分享，不需要处理回调的场景，例如分享到群、分享到好友，这些普通的分享，而不用处理成功/失败回调函数。 参数： ```javascript key: string 必传 功能点的分享/视频key（后台 ->【游戏数据】 ->【配置相关】->【分享/视频配置】配置的key） params: object 选传 扩展参数：分享链接query携带自定义参数,{ key: value }对象形式，该对象传递的参数会与SDK内部query参数一起组成query（查询参数, key1=val1&key2=val2的格式）的值，SDK内部参数key有：channel_id、user_invite_uid、share_id、share_key。 提示：params传递的对象中如果含有传递SDK内部query参数key，会被SDK内部参数值覆盖，所以开发者避免传递这些key。 opts: object 选传 可不传递 ``` 返回值： ```javascript void ``` 示例：游戏首页分享到群的功能，假如config.js配置的ChannelId: 20024；后台配置的分享视频key: home_share2group、此分享key的id：512；用户id：100000。 ```javascript // 示例1： // 分享后生成的query：share_id=512&share_key=home_share2group&channel_id=20024&user_invite_uid=100000 PCSDK.shareVideo.share( 'home_share2group' ); // 示例2：第二个参数是分享生成的query携带的参数 // 分享后生成的query：type=99&share_id=512&share_key=home_share2group&channel_id=20024&user_invite_uid=100000 PCSDK.shareVideo.share( 'home_share2group', { type:99 }); // 示例3：第二个参数是分享生成的query携带的参数，传递SDK内部query参数：channel_id // 分享后生成的query：type=99&share_id=512&share_key=home_share2group&channel_id=20024&user_invite_uid=100000 PCSDK.shareVideo.share( 'home_share2group', { type:99, channel_id:10000 }); ``` 2. ##### **dispatch** ```javascript PCSDK.shareVideo.dispatch( key: string, params?: { success: Function, fail: Function, context?: any} ): void ``` 定义：普通分享，不需要处理回调的场景，例如分享到群、分享到好友，这些普通的分享，而不用处理成功/失败回调函数。 参数： ```javascript key: string 必传 功能点的分享/视频key（后台 ->【游戏数据】 ->【配置相关】->【分享/视频配置】配置的key） params: object 选传 扩展参数：success分享视频成功回调处理函数，fail分享视频失败回调处理函数，contex函数执行上下文 { success: ( from:number, ret: any | null ) => void, error: ( from:number, error: object | null ) => void, context: any } from：此次分发成功推送类型 from返回枚举值为： 0：无视频无分享（后台配置分享开关（推送类型）or 应对审核分享关闭：配置参数share_unlock设置为0） 1：推送同步分享 2：推送异步分享 3：推送视频 error：此次分发失败的错误消息 error返回枚举值为： { code: 1000, msg: '要看完视频哦!' }, { code: 1001, msg: '视频加载失败!' }, { code: 999, msg: '视频UID不存在!' }, { code: 1002, msg: '视频组件未开放!' }, { code: 1003, msg: '正在观看视频中...' }, { code: 1004, msg: '分享失败，请尝试发送至不同群！' }, { code: 1005, msg: '别总骚扰这个群，换个群分享吧!' }, { code: 1006, msg: '请分享到群哦!' }, { code: 1007, msg: '分享到群才能领取更多~' }, { code: 1008, msg: '分享失败，请尝试发送至不同群！' }, { code: 1009, msg: '今日已达分享上限次数，请明日再来' } ``` 返回值： ```javascript void ``` 示例：下面只是api的简单演示，详细案例，请戳[详细使用示例](share.md#detail)。 演示 ```javascript // DiamondDoublePopwin.ts文件 export default class DiamondDoublePopwin extends BaseView{ protected addEvent() { super.addEvent(); // 免费领取双倍（应对微信审核，审核分享不能开放时候使用） this.btnFree.on(Laya.Event.CLICK, this, this.onReward); // 分享双倍 this.btnShare.on(Laya.Event.CLICK, this, this.onReward); // 视频双倍 this.btnVideo.on(Laya.Event.CLICK, this, this.onReward); } protected removeEvent() { super.removeEvent(); this.btnFree.off(Laya.Event.CLICK, this, this.onReward); this.btnShare.off(Laya.Event.CLICK, this, this.onReward); this.btnVideo.off(Laya.Event.CLICK, this, this.onReward); } // 领取奖励操作 private onReward(){ PCSDK.shareVideo.dispatch( ShareVideoKeys.DiamondDouble.toString(), { success: this.handleReward, fail: this.handleError, context: this } ); } // 分享/视频成功后回调处理函数：发奖励 private handleReward(from: ShareVideoFrom, ret: any | null){ // 分享成功、视频成功、无视频无分享 } // 分享/视频失败后回调处理函数：弹出提示 private handleError(from: ShareVideoFrom, error: any | null){ // 返回错误，处理错误msg信息，自定义处理 if( error ){ wx.showToast({ title: error.msg }); } } } // Enums.ts文件 // 分享视频key枚举，每个key表示一个功能点 enum ShareVideoKeys { // 钻石双倍获取 DiamondDouble = 'diamond_double', // 失败获得双倍奖励 FailRewardDouble = 'fail_reward_double' } // 分享视频功能点最终处理方式 enum ShareVideoFrom{ None = 0, // 无视频无分享 Share = 1, // 分享 ShareAsync = 2, // 异步分享 Video = 3, // 看视频 } ``` 3. ##### **getShareVideoType** ```javascript PCSDK.shareVideo.getShareVideoType( key: string ): number ``` 定义：根据分享视频key获取此次shareVideo模块推送的分享视频类型值：-1（无视频无分享：提审时返回）、0（推送同步分享）、1（推送异步分享）、2（推送看视频）、3（无视频则分享）、4（视频和分享）、5（分享积分）；此api用于通过得到的类型值处理页面的ui状态（微信和QQ平台对按钮的icon有强制限制）：显示视频icon、显示分享icon、既没有分享icon，也没有视频icon。 参数： ```javascript key: string 必传 功能点的分享/视频key（后台 ->【游戏数据】 ->【配置相关】->【分享/视频配置】配置的key） ``` 返回值： ```javascript number 返回值此次点击功能按钮触发的推送类型：-1（无视频无分享：提审时返回）、0（推送同步分享）、1（推送异步分享）、2（推送看视频）、3（无视频则分享）、4（视频和分享）、5（分享积分） 分享视频类型枚举值如下： // 推送类型：分享视频类型枚举 enum ShareVideoType { None = -1, // -1无分享无视频 Share = 0, // 0分享 ShareAysnc = 1, // 1异步分享 ShareIntegral = 5, // 5分享积分 Video = 2, // 2看视频 VideoToShare = 3, // 3无视频则分享 VideoAndShare = 4 // 4视频和分享(控制分享和视频两个按钮的显示) ， } ``` 示例：下面只是api的简单演示，详细案例，请戳[详细使用示例](share.md#detail)。 ```javascript // DiamondDoublePopwin.ts文件 export default class DiamondDoublePopwin extends BaseView{ protected addEvent() { super.addEvent(); // 免费领取双倍（应对微信审核，审核分享不能开放时候使用） this.btnFree.on(Laya.Event.CLICK, this, this.onReward); // 分享双倍 this.btnShare.on(Laya.Event.CLICK, this, this.onReward); // 视频双倍 this.btnVideo.on(Laya.Event.CLICK, this, this.onReward); } protected removeEvent() { super.removeEvent(); this.btnFree.off(Laya.Event.CLICK, this, this.onReward); this.btnShare.off(Laya.Event.CLICK, this, this.onReward); this.btnVideo.off(Laya.Event.CLICK, this, this.onReward); } // 每次打开此popwin执行onOpen protected onOpen(){ super.onOpen(); this.iniitRewardUI(); } // 初始化/更新获得奖励按钮ui private initRewardUI() { let shareVideoType: ShareVideoType = PCSDK.shareVideo.getShareVideoType(ShareVideoKeys.DiamondDouble.toString()); switch (shareVideoType) { case ShareVideoType.Share: // 同步分享 case ShareVideoType.ShareAysnc: // 异步分享 case ShareVideoType.ShareIntegral: // 分享积分 this.btnFree.visible = false; this.btnShare.visible = true; this.btnVideo.visible = false; break; case ShareVideoType.Video: // 推送视频 case ShareVideoType.VideoToShare: // 无视频则分享 // 视频ui状态 this.btnFree.visible = false; this.btnShare.visible = false; this.btnVideo.visible = true; break; default: // 无视频和无分享 // 既不显示分享ui又不显示视频ui，直接领奖ui状态 this.btnFree.visible = true; this.btnShare.visible = false; this.btnVideo.visible = false; break; } } // 领取奖励操作 private onReward(){ PCSDK.shareVideo.dispatch( ShareVideoKeys.DiamondDouble.toString(), { success: this.handleReward, fail: this.handleError, context: this } ); } // 分享/视频成功后回调处理函数：发奖励 private handleReward(from: ShareVideoFrom, ret: any | null){ // 分享成功、视频成功、无视频无分享 } // 分享/视频失败后回调处理函数：弹出提示 private handleError(from: ShareVideoFrom, error: any | null){ // 返回错误，处理错误msg信息，自定义处理 if( error ){ wx.showToast({ title: error.msg }); } } } // Enums.ts文件 // 分享视频类型（与后台一一对应） export enum ShareVideoType { None = -1, // -1无分享无视频 Share = 0, // 0同步分享 ShareAysnc = 1, // 1异步分享 ShareIntegral = 5, // 5分享积分 Video = 2, // 2看视频 VideoToShare = 3, // 3无视频则分享 VideoAndShare = 4, // 4视频和分享(控制分享和视频两个按钮的显示) } // 分享视频key枚举，每个key表示一个功能点 enum ShareVideoKeys { // 钻石双倍获取 DiamondDouble = 'diamond_double', // 失败获得双倍奖励 FailRewardDouble = 'fail_reward_double' } // 分享视频功能点最终推送类型 enum ShareVideoFrom{ None = 0, // 无视频无分享 Share = 1, // 分享 ShareAsync = 2, // 异步分享 Video = 3, // 看视频 } ```
下面演示dispatch和getShareVideoType两个api的完整使用，Laya引擎开发： 页面功能点按钮做三个状态： 1、看视频状态（显示视频icon） 2、分享状态（显示分享icon） 3、直接领奖（没有icon，审核状态） ![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_027_1.png "🔍点击查看大图") ![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_027_2.png "🔍点击查看大图") ![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_027_3.png "🔍点击查看大图") ![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_027_4.png "🔍点击查看大图") 例如，一个领取钻石双倍，页面的按钮ui通过下面的方式进行切换 1、页面做三个按钮：视频icon按钮、分享icon按钮、直接领取按钮 2、进入页面根据配置的key获取类型，显示对应类型ui：调用下面的initRewardUI(可随意命名) 3、分享或者视频后，SDK会发送一个tactic.update的消息过来，使用PCSDK.event.add注册监听，PCSDK.event.remove移除监听（PCSDK.event详细了解请查看[事件模块](event.md)），监听事件处理下一次推送显示ui状态：执行一下initRewardUI。 4、给三个按钮都注册事件：onReward ```javascript // DiamondDoublePopwin.ts文件 export default class DiamondDoublePopwin extends BaseView { protected addEvent() { super.addEvent(); // 免费领取双倍（应对微信审核，审核分享不能开放时候使用） this.btnFree.on(Laya.Event.CLICK, this, this.onReward); // 分享双倍 this.btnShare.on(Laya.Event.CLICK, this, this.onReward); // 视频双倍 this.btnVideo.on(Laya.Event.CLICK, this, this.onReward); // PCSDK.event.add注册监听SDK发送的消息：tactic.update，更新获得奖励按钮ui PCSDK.event.add('tactic.update', this.initRewardUI, this); } protected removeEvent() { super.removeEvent(); this.btnFree.off(Laya.Event.CLICK, this, this.onReward); this.btnShare.off(Laya.Event.CLICK, this, this.onReward); this.btnVideo.off(Laya.Event.CLICK, this, this.onReward); // PCSDK.event.remove移除监听SDK发送的消息：tactic.update PCSDK.event.remove('tactic.update', this.initRewardUI, this); } // 每次打开此popwin执行onOpen protected onOpen(){ super.onOpen(); // 界面打开 this.initRewardUI(); } // 领取奖励操作 private onReward(){ PCSDK.shareVideo.dispatch( ShareVideoKeys.DiamondDouble.toString(), { success: this.handleReward, context: this } ); } // 分享/视频成功后回调处理函数：发奖励 private handleReward(from: ShareVideoFrom, ret: any | null){ // 分享成功、视频成功、无视频无分享 } // 分享/视频失败后回调处理函数：弹出提示 private handleError(from: ShareVideoFrom, error: any | null){ // 返回错误，处理错误msg信息，自定义处理 if( error ){ wx.showToast({ title: error.msg }); } } // 初始化/更新获得奖励按钮ui private initRewardUI() { let shareVideoType: ShareType = PCSDK.shareVideo.getShareVideoType(ShareVideoKeys.DiamondDouble.toString()); switch (shareVideoType) { case ShareVideoType.Share: // 同步分享 case ShareVideoType.ShareAysnc: // 异步分享 case ShareVideoType.ShareIntegral: // 分享积分 // 分享ui状态 this.stat_share.play(0,false); // 等同于 // this.btnFree.visible = false; // this.btnShare.visible = true; // this.btnVideo.visible = false; break; case ShareVideoType.Video: // 视频 case ShareVideoType.VideoToShare: // 无视频则分享 // 视频ui状态 this.stat_video.play(0,false); // 等同于 // this.btnFree.visible = false; // this.btnShare.visible = false; // this.btnVideo.visible = true; break; default: // 无视频和无分享 // 既不显示分享ui又不显示视频ui，直接领奖ui状态 this.stat_free.play(0,false); // 等同于 // this.btnFree.visible = true; // this.btnShare.visible = false; // this.btnVideo.visible = false; break; } } } // Enums.ts文件 // 分享视频类型（与后台一一对应） export enum ShareVideoType { None = -1, // -1无分享无视频 Share = 0, // 0同步分享 ShareAysnc = 1, // 1异步分享 ShareIntegral = 5, // 5分享积分 Video = 2, // 2看视频 VideoToShare = 3, // 3无视频则分享 VideoAndShare = 4, // 4视频和分享(控制分享和视频两个按钮的显示) } // 分享视频key枚举，每个key表示一个功能点 enum ShareVideoKeys { // 钻石双倍获取 DiamondDouble = 'diamond_double', // 失败获得双倍奖励 FailRewardDouble = 'fail_reward_double' } // 分享视频功能点最终推送类型 enum ShareVideoFrom{ None = 0, // 无视频无分享 Share = 1, // 分享 ShareAsync = 2, // 异步分享 Video = 3, // 看视频 } ``` #### **终章：** 这个模块的内容点比较多，接入的注意事项也比较多，望接入者细度使用说明和理解示例意图。 噗嗤游戏的小伙伴在开发公司内部游戏中使用此模块，简单封装了SDK分享视频模块的几个通用方法，提供开发者参考，**[点击下载](https://dep.miso-lab.com/sdkword/tools/sdk-share-tools-1.0.0.zip)**。