1. 直玩模式概念理解

微信直玩，指的是微信在游戏A的视频广告中，将游戏B加载，并在特殊的广告界面下进行游玩的一种功能。通过该方式启动游戏时，微信会提供特殊的启动场景判断标识。目前微信将直玩的倒计时控制为30S。

在判断为直玩启动时，游戏需要切割出直玩关卡，或者专项直玩模式，以最快的速度自动跳转。直玩模式下，微信的广告/支付等功能都不可用，游戏实际以白包模式运行。

直玩模式下广告功能将失效，请务必屏蔽相关逻辑，请勿调用相关方法。

1.1 直玩的3个阶段(4种状态)

阶段1	阶段2	阶段3

1.1.1 阶段1 - 广告弹出、蒙层遮挡

以直玩模式启动游戏时，游戏上层会自动覆盖微信的蒙层。蒙层会自动覆盖在屏幕最上层，无需游戏手动处理。

1.1.2 阶段2 - 戳破蒙层、进入游戏

点击一下屏幕即可戳破蒙层，玩家可正式操作游戏：

如果戳的过早，游戏还没加载好，则还需等待游戏进入场景才能玩
如果戳的刚好，游戏已经加载完毕，则刚好可以开始玩
如果戳的很晚，则游戏已经加载完毕等了很久，则玩不了几秒钟

1.1.3 阶段3 - 直玩结束

直玩有3种结束状态

【正常结束+继续玩】微信的直玩倒计时结束(一般为30S)，微信弹出结束蒙层。玩家选择继续玩<当前直玩的游戏>，
【正常结束+返回】微信的直玩倒计时结束(一般为30S)，微信弹出结束蒙层。玩家选择返回原游戏，但后续通过热启动返回本次直玩游戏(游戏还在微信后台留存)
【异常结束】直玩模式因其他操作异常退出，但热启动返回本次游戏(游戏还在微信后台留存)
1. 中途切后台
2. 结束页切后台
3. 结束页点返回
4. 点击右上角的×

请注意，对于直玩游戏来说，仅当玩家点击《继续玩》按钮时，直玩状态才会改变！并不是倒计时到了就改变。如果玩家一直停在结束蒙层，状态就一直不会改！

2. 业务设计

2.1 直玩模式进入 - 玩法逻辑示例

当玩家通过直玩进入时，业务游戏需要考虑如何设计直玩的场景。以下提供几种标准模式作为参考，如有细化或特殊需求，请跟策划单独讨论。

【特殊直玩分包或关卡，跟主玩法完全隔离】：将游戏的某个关卡或者模式，单纯抽出来，启动时进行独立的加载，与普通模式完全隔离。一般会抽取为独立的小游戏分包。玩法时长需要至少持续30S以上。直玩模式的进程不可被游戏元素打断
【普通玩法的某一关】跟普通用户一样，共享玩法。但是根据策划的要求，或者根据投放配置的关卡参数，直接跳转到指定的关卡开始。只是这个玩法游玩时，需要屏蔽掉广告支付点位，屏蔽退出场景点位，且玩法时长需要至少持续30S以上。直玩模式的进程不可被游戏元素打断

2.2 直玩模式退出 - 玩法逻辑示例

以下仅给出通用的方案，如有特殊需求，请跟策划协商

当玩家处于栏目1.1.3的直玩结束阶段时，无论是【正常结束+继续玩】、【正常结束+返回】、【异常结束】，都必须将玩法重新设置为普通模式(玩家非直玩进入时一样)。

下面根据直玩模式进入的几种模式，给出几种示例，如有细化或特殊需求，请跟策划单独讨论。

【特殊直玩分包或关卡，跟主玩法完全隔离，回到大厅】：由于是单独的关卡，无法继续游玩，需要弹出回到首页的引导UI，让玩家回到大厅。注意处理好统计的玩法退出逻辑。不要自动将玩家踢到大厅
【普通玩法的某一关】
- 【方式1-继续顺着玩下一关】先恢复游戏功能到普通模式，立即将之前屏蔽的广告/支付/退出等一系列UI全部还原。让玩家正常结束当前关卡，后续正常的关卡逻辑走即可(比如直玩是第5关，那么下一关就是6)
- 【方式2-玩完当前关，引导回首页】玩家正常结束当前关卡后(此时仍为直玩的玩法状态，例如爽玩)，弹出引导弹框，让其回到首页从头开始。再恢复游戏功能到普通模式，将之前屏蔽的广告/支付/退出等一系列UI全部还原。
- 【方式3-结束当前关，引导回首页】立刻结束当前关卡(此时仍为直玩的玩法状态，例如爽玩)，弹出引导弹框，让其回到首页从头开始。再恢复游戏功能到普通模式，将之前屏蔽的广告/支付/退出等一系列UI全部还原。

2.3 统计专项说明<极其重要>

直玩的过程是用户行为分析的重点，务必处理好直玩期间和退出后的玩法统计逻辑，不能出现遗漏。

玩法的所有统计齐全！直玩也是一个玩法的游玩过程，那就必定要有全套的内部玩法统计

2.3.1 进入直玩

【特殊直玩分包或关卡，跟主玩法完全隔离，回到大厅】要从game_name、game_mode层面，将特殊玩法跟普通模式完全区分开来。可采取原名称_wxfeed的命名方式。例如原game_name叫sbx，现在就叫sbx_wxfeed。接入完整的玩法统计
【普通玩法的某一关】填写正常的game_name、game_mode，然后填入指定的game_level，正常关卡统计。玩法名/模式名跟普通模式的一样，不需要特殊处理

2.3.2 退出直玩

退出直玩回到普通模式后

【特殊直玩分包或关卡，跟主玩法完全隔离，回到大厅】因结束后需要回主页: 处理回到首页的当前玩法退出统计，形成闭环，别处理漏了
【普通玩法的某一关】
1. 【方式1-继续顺着玩下一关】：确保玩法统计能正常续上即可。
2. 【方式2-玩完当前关，引导回首页】&【方式3-结束当前关，引导回首页】：在当前关结束时，处理好关卡结束统计。在回到首页时处理好玩法退出统计，形成闭环，别处理漏了

2.4 特殊注意点

2.4.1 直玩进入

【资质页】玩法加载完毕后尽快跳转
1. 如原本有DIY隐私弹框的策略，当次启动不弹隐私弹框。如用户还未弹出过隐私弹框，首次非直玩的启动再弹出
2. 首页不用加额外的合规展示按钮。启动时的资质信息已经顺带在加载页显示过了
【屏蔽广告支付点位】直玩场景下，不允许展示任何广告/支付点位，需要将相关的UI全部隐藏，不得触发逻辑
【屏蔽退出直玩场景点位】不允许玩家通过任何方式离开直玩场景，将相关UI隐藏(例如回到首页按钮)，否则会造成游戏逻辑混乱

2.4.2 直玩退出

【特殊直玩分包或关卡，跟主玩法完全隔离，回到大厅】使用引导，将玩家导回大厅。请勿自动踢人回大厅。
【普通玩法的某一关】：
1. 【方式1-继续顺着玩下一关】需要立刻恢复因直玩而屏蔽的所有元素
2. 【方式2-玩完当前关，引导回首页】&【方式3-结束当前关，引导回首页】：当前关卡结束前，仍为直玩的游戏模式(比如各种道具隐藏，免费道具随便用等)。使用引导，将玩家导回大厅。回到大厅后，再将游戏玩法内容切换为普通。

3. 研发接入

3.1 链路

3.1.1 STEP1 - 直玩模式判断

当判断为微信渠道后，在业务层加载游戏玩法时，需要先判断GameHelper.WXFeed.isFeedEnter

如果为true，直接切直玩模式，不加其他判断。
如果为false，则走普通逻辑

游戏只要判断为直玩场景进入，

3.1.2 STEP2 - 判断是否有跳关逻辑

在接入是，就跟策划约定好，直玩的进入模式是怎么样的，对标栏目2.1。

如果有关卡的概念，要先跟策划商量默认跳第几关，不要研发自己定！！！

如果有多个玩法或者模式，要先跟策划商量默认用哪个，不要研发自己定！！！

在进入时，通过GameHelper.WXFeed.getGameLevel接口，判断是否有指定关卡。如果取到了值，就跳转对应关卡

3.1.3 STEP3 - 注册直玩状态改变回调

立即使用GameHelper.WXFeed.setListener注册直玩状态处理回调，玩法的状态方案，请参考栏目2.2.

必须同时处理GameHelper.WXFeed.STATUS.END_CONTINUE和GameHelper.WXFeed.STATUS.END_ABNORMAL，两者执行的代码一模一样

需要注意，玩法和统计两方面都要处理，详情见栏目2.2~2.4

3.1.4 STEP4 - 跳转直玩关卡

以上栏目完成后，尽快跳转直玩关卡。玩法的处理请参考栏目2.1

3.2 代码示例

以下逻辑仅供参考，请根据游戏实际情况操作。

typescript

this.SDKComp.loadSDK({
  suCallback: () => {
    GameHelper.init({
      // 省略其他初始化参数
      callback: () => {
        const isWXFeed =
          GameHelper.CCComFun.isPlatform(GameHelper.CCConst.PLATFORM.WEIXIN) &&
          GameHelper.WXFeed.isFeedEnter;

        if (!isWXFeed) {
          // 非微信直玩，继续普通隐私初始化流程
          GameHelper.AAP.startProcess((_isAgree) => {
            // 普通启动逻辑
          });
          return;
        }

        // 直玩进入：不弹业务自定义隐私框，并屏蔽广告、支付和退出点位
        let level = 1; // 默认关卡必须提前与策划确认
        const configuredLevel = GameHelper.WXFeed.getGameLevel();
        if (configuredLevel !== undefined) {
          level = configuredLevel;
        }

        const restoreNormalMode = () => {
          // 恢复广告、支付、退出等普通游戏能力，并按实际方案闭合统计链路
          GameHelper.GameStatistics.QuitGame(123);
          GameHelper.GameStatistics.ExitMode();
          GameHelper.GameStatistics.EnterHome();
        };

        // END_CONTINUE 与 END_ABNORMAL 必须执行相同的恢复逻辑
        GameHelper.WXFeed.setListener((status) => {
          if (
            status === GameHelper.WXFeed.STATUS.END_CONTINUE ||
            status === GameHelper.WXFeed.STATUS.END_ABNORMAL
          ) {
            restoreNormalMode();
          }
        });

        GameHelper.GameStatistics.EnterGame("mainGame");
        GameHelper.GameStatistics.EnterMode("dailyChallenge");
        GameHelper.GameStatistics.StartGame(level, "dailyChallenge");
        director.loadScene("DEMO_WXFeed");
      },
      failCallback(source: string) {
        GameHelper.CCComFun.showToast({
          title: `SDK 初始化失败：${source}`,
          duration: 3000,
        });
      },
    });
  },
  failCallback: () => {
    console.log("SDK 分包加载失败");
  },
});

3.1 自测调试

仅支持《微信全真模拟》的方式。

3.1.1 微信全真模拟(建议√)

使用本方式，可拉起真实的微信直玩界面，最为直观有效
手机基础库>3.14.2。IOS微信客户端版本>8.0.69

开发版只能下包使用开发者工具进行操作，无法在JAC直接预览。体验版有权限的同学，填好页面路径即可。

点击左上角的《普通编译》，选择《添加编译模式》
1. 模式名称自选
2. 体验版启动参数
  1. 无需指定：index?minigame_direct_debug=true
  2. 需要指定玩法和关卡(修改game_level后面的值)：index?minigame_direct_debug=true&game_level=5

开发版启动参数
1. 无需跳关：minigame_direct_debug=true
2. 需要指定玩法和关卡(修改game_level后面的值)：minigame_direct_debug=true&game_level=5

根据版本进行操作
1. 开发版：点击确认后，开发者工具会重新编译游戏。再点击预览即可
2. 体验版：直接启动即可

3.2 API

属性	类型	说明
STATUS	`STATUS`	直玩状态枚举
isFeedEnter	boolean	用户是否为直玩进入
setListener	(callback: function) =>{}	设置游戏业务的直玩状态变更处理回调
~~emitTestStatusChange~~	(status: STATUS) =>{}	旧测试接口，不再建议使用
getGameName	() => string \| undefined	获取直玩启动参数配置的玩法名(不一定有)。取的game_name参数。
getGameMode	() => string \| undefined	获取直玩启动参数配置的模式名(不一定有)。取的game_model参数。
getGameLevel	() => string \| undefined	获取直玩启动参数配置的关卡(不一定有)。取的game_level参数。
getCustomParam	(k: string) => string \| undefined	获取直玩启动参数配置的自定义参数(不一定有)

STATUS

object

属性	类型	说明
END_CONTINUE	`number`	【需关注！】直玩时间到，直玩模式结束，点击了继续玩。游戏恢复为普通模式
END_ABNORMAL	`number`	【需关注！】直玩模式异常退出。游戏恢复为普通模式

setListener

描述

设置业务层处理直玩状态改变的回调函数。当判断isFeedEnter为true时，应当立即注册。

请勿重复注册，业务回调只能注册一份，后面设置的会把之前设置的给盖掉。

参数

属性	类型	默认值	是否必填	说明
callback	（status: STATUS） => {}	/	否	直玩状态处理的业务回调

返回值

无

示例

getGameName

描述

获取直玩广告启动时，配置的玩法名参数。投放默认的配置key为game_name.

仅在游戏明确要在线控制直玩进入的玩法时才用，用不用请跟策划或投放确认
不一定有值，一定要判断非空再去用
要跟策划商量好，默认的玩法是什么

参数

无

返回值

配置的玩法名(string) 或者 undefined

示例

getGameMode

描述

获取直玩广告启动时，配置的游戏模式参数。投放默认的配置key为game_model

仅在游戏明确要在线控制直玩进入的游戏模式时才用，用不用请跟策划或投放确认
不一定有值，一定要判断非空再去用
要跟策划商量好，默认的游戏模式是什么

参数

无

返回值

配置的游戏模式(string) 或者 undefined

示例

getGameLevel

描述

获取直玩广告启动时，配置的游戏关卡参数。投放默认的配置key为game_level

仅在游戏明确要在线控制直玩进入的关卡时才用，用不用请跟策划或投放确认
不一定有值，一定要判断非空再去用
要跟策划商量好，默认的关卡是什么

参数

无

返回值

配置的关卡(number) 或者 undefined

示例

getCustomParam

描述

获取直玩广告启动时，配置的自定义参数

仅在游戏明确要在线控制时才用，用不用请跟策划或投放确认
不一定有值，一定要判断非空再去用

参数

属性	类型	默认值	是否必填	说明
k	`string`	/	是	要获取的参数key

返回值

配置的参数值(string) 或者 undefined

示例

4. 业务测试点位

4.1 进入游戏

直玩模式
1. 根据栏目2.1，正确处理了玩法逻辑
2. 如游戏有配置在线跳玩法/模式/关卡，游戏表现正常
3. 栏目2.4.1
4. 游戏能正常启动，无缝跳到直玩模式，期间无需玩家额外操作。不允许在原正常流程上添加多余的加载过渡页面。
5. 进入过程不弹出除SDK登录失败弹框以外的，任何打扰直玩过程的弹框(如果是SDK通用的综合信息页，这一块无需处理，因为这次不弹的话后续广告功能无法恢复)。特别说明：
  1. 游戏的DIY隐私弹框当次启动不可弹出
  2. 加载页会放置著作权人/健康忠告/备案的内容。加载好了就尽快跳游戏，此时不受2S的展示时长限制
6. 直玩模式的进程不可被游戏元素打断，保证玩家一直停留在直玩模式里。例如需要屏蔽回到首页等按钮
7. 直玩模式需要屏蔽任何设计内购、广告的元素，玩法为纯净游戏体验
8. 直玩模式的玩法内容，需要保证能被至少玩30秒
9. 统计：进入直玩的统计正常(栏目2.3.1)，游玩过程统计正常，无遗漏/多报/误报
普通模式
1. 游戏能正常启动，体验跟普通保持一致
2. 如游戏有DIY隐私弹框的逻辑，则需在首次非直玩启动时弹出
通用
1. 游戏可同时兼容两种启动模式

4.1.1 直玩状态更新

当《直玩时间结束，玩家点击继续玩》或《直玩异常退出》：

根据栏目2.2，正确处理了玩法退出逻辑。如需让玩家回首页，需要提供引导界面
栏目2.4.2
统计：
1. 退出直玩时或直玩关卡的统计正常(栏目2.3.2)，无遗漏/多报/误报
2. 回归普通模式后，一切统计正常，无遗漏/多报/误报

1. 直玩模式概念理解 ​

1.1 直玩的3个阶段(4种状态) ​

1.1.1 阶段1 - 广告弹出、蒙层遮挡 ​

1.1.2 阶段2 - 戳破蒙层、进入游戏 ​

1.1.3 阶段3 - 直玩结束 ​

2. 业务设计 ​

2.1 直玩模式进入 - 玩法逻辑示例 ​

2.2 直玩模式退出 - 玩法逻辑示例 ​

2.3 统计专项说明<极其重要> ​

2.3.1 进入直玩 ​

2.3.2 退出直玩 ​

2.4 特殊注意点 ​

2.4.1 直玩进入 ​

2.4.2 直玩退出 ​

3. 研发接入 ​

3.1 链路 ​

3.1.1 STEP1 - 直玩模式判断 ​

3.1.2 STEP2 - 判断是否有跳关逻辑 ​

3.1.3 STEP3 - 注册直玩状态改变回调 ​

3.1.4 STEP4 - 跳转直玩关卡 ​

3.2 代码示例 ​

3.1 自测调试 ​

3.1.1 微信全真模拟(建议√) ​

3.2 API ​

STATUS ​

setListener ​

描述 ​

参数 ​

返回值 ​

示例 ​

getGameName ​

描述 ​

参数 ​

返回值 ​

示例 ​

getGameMode ​

描述 ​

参数 ​

返回值 ​

示例 ​

getGameLevel ​

描述 ​

参数 ​

返回值 ​

示例 ​

getCustomParam ​

描述 ​

参数 ​

返回值 ​

示例 ​

4. 业务测试点位 ​

4.1 进入游戏 ​

4.1.1 直玩状态更新 ​

1. 直玩模式概念理解

1.1 直玩的3个阶段(4种状态)

1.1.1 阶段1 - 广告弹出、蒙层遮挡

1.1.2 阶段2 - 戳破蒙层、进入游戏

1.1.3 阶段3 - 直玩结束

2. 业务设计

2.1 直玩模式进入 - 玩法逻辑示例

2.2 直玩模式退出 - 玩法逻辑示例

2.3 统计专项说明<极其重要>

2.3.1 进入直玩

2.3.2 退出直玩

2.4 特殊注意点

2.4.1 直玩进入

2.4.2 直玩退出

3. 研发接入

3.1 链路

3.1.1 STEP1 - 直玩模式判断

3.1.2 STEP2 - 判断是否有跳关逻辑

3.1.3 STEP3 - 注册直玩状态改变回调

3.1.4 STEP4 - 跳转直玩关卡

3.2 代码示例

3.1 自测调试

3.1.1 微信全真模拟(建议√)

3.2 API

STATUS

setListener

描述

参数

返回值

示例

getGameName

描述

参数

返回值

示例

getGameMode

描述

参数

返回值

示例

getGameLevel

描述

参数

返回值

示例

getCustomParam

描述

参数

返回值

示例

4. 业务测试点位

4.1 进入游戏

4.1.1 直玩状态更新