SDK对接文档

主题

更新时间：2026/07/01

1. 直玩模式概览 ​

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

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

直玩结束页面示例：

1.1 直玩的 3 个阶段 ​

阶段 1阶段 2阶段 3

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

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

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

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

  • 如果戳得过早，游戏还没加载好，则还需等待游戏进入场景才能玩

  • 如果戳得刚好，游戏已经加载完毕，则可以直接开始玩

  • 如果戳得很晚，游戏虽然已经加载完毕，但可玩时间会被压缩

1.1.3 阶段 3 - 直玩结束 ​

直玩有 3 种结束状态：

  1. 【正常结束 + 继续玩】微信的直玩倒计时结束后，微信弹出结束蒙层。玩家选择继续玩当前直玩的游戏。

  2. 【正常结束 + 返回】微信的直玩倒计时结束后，微信弹出结束蒙层。玩家选择返回原游戏，但后续通过热启动返回本次直玩游戏，游戏仍在微信后台留存。

  3. 【异常结束】直玩模式因其他操作异常退出，但热启动返回本次游戏，游戏仍在微信后台留存。常见场景包括中途切后台、结束页切后台、结束页点返回、点击右上角的 ×。

请注意：对于直玩游戏来说，仅当玩家点击《继续玩》按钮，或者结束页消失后回到游戏时，直玩状态才会改变。不是倒计时结束就立刻改变。如果玩家一直停在结束蒙层，状态就一直不会改变。

1.2 用户属性 ​

对于通过直玩进入的用户，SDK 会自动处理用户属性 wxfeed，它的取值有 1、3、4，具体逻辑如下图。

2. 业务设计 ​

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

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

  • 【特殊直玩分包或关卡，跟主玩法完全隔离】：将游戏的某个关卡或模式单独抽出来，启动时独立加载，与普通模式完全隔离。一般会抽取为独立小游戏分包或独立场景。玩法时长需要至少持续 30 秒以上，直玩模式的进程不可被游戏元素打断。

  • 【普通玩法的某一关】：跟普通用户一样共享玩法，但根据策划要求，或者根据投放配置的关卡参数，直接跳转到指定关卡开始。游玩期间需要屏蔽广告、支付、退出场景点位，且玩法时长需要至少持续 30 秒以上，直玩模式的进程不可被游戏元素打断。

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

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

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

  • 【特殊直玩分包或关卡，跟主玩法完全隔离，回到大厅】：由于是单独关卡，通常无法继续游玩，需要弹出回到首页的引导 UI，让玩家回到大厅。注意处理好统计的玩法退出逻辑，不要自动将玩家踢回大厅。

  • 【普通玩法的某一关】

    • 【方式 1 - 继续顺着玩下一关】先恢复游戏功能到普通模式，立即将之前屏蔽的广告、支付、退出等 UI 全部还原。让玩家正常结束当前关卡，后续按正常关卡逻辑继续。

    • 【方式 2 - 玩完当前关，引导回首页】玩家正常结束当前关卡后，弹出引导弹框，让玩家回到首页从头开始。再恢复游戏功能到普通模式，将之前屏蔽的 UI 全部还原。

    • 【方式 3 - 结束当前关，引导回首页】立刻结束当前关卡，弹出引导弹框，让玩家回到首页从头开始。再恢复游戏功能到普通模式，将之前屏蔽的 UI 全部还原。

2.3 统计专项说明 ​

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

直玩也是一个玩法游玩过程，需要有完整的内部玩法统计。

2.3.1 进入直玩 ​

  1. 【特殊直玩分包或关卡，跟主玩法完全隔离】：建议从 game_mode 层面将特殊玩法跟普通模式完全区分开，并接入完整玩法统计。

    示例：ReportManager.Instance.StartGameModel("WXFeedGameMode");

  2. 【普通玩法的某一关】：填写正常的 game_mode，再填入指定 game_level，走正常关卡统计。玩法名、模式名跟普通模式保持一致，不需要特殊处理。

2.3.2 退出直玩 ​

退出直玩回到普通模式后：

  1. 【特殊直玩分包或关卡，跟主玩法完全隔离】：如果结束后需要回主页，需要处理当前玩法退出统计，形成闭环。

  2. 【普通玩法的某一关】

    1. 【方式 1 - 继续顺着玩下一关】：确保玩法统计能正常续上即可。

    2. 【方式 2 - 玩完当前关，引导回首页】和【方式 3 - 结束当前关，引导回首页】：在当前关结束时处理好关卡结束统计，在回到首页时处理好玩法退出统计，形成闭环。

2.4 特殊注意点 ​

2.4.1 直玩进入 ​

  1. 【资质页】：玩法加载完毕后尽快跳转。

    1. 如原本有 DIY 隐私弹框策略，当次直玩启动不弹隐私弹框。如用户还未弹出过隐私弹框，首次非直玩启动时再弹出。

    2. 首页不用加额外的合规展示按钮。启动时的资质信息已经顺带在加载页显示过。

  2. 【屏蔽广告支付点位】：直玩场景下，不允许展示任何广告、支付点位，需要将相关 UI 全部隐藏，不得触发相关逻辑。

  3. 【屏蔽退出直玩场景点位】：不允许玩家通过任何方式离开直玩场景，需要将相关 UI 隐藏，例如回到首页按钮，否则会造成游戏逻辑混乱。

2.4.2 直玩退出 ​

  1. 【特殊直玩分包或关卡，跟主玩法完全隔离，回到大厅】：使用引导将玩家导回大厅，请勿自动把玩家踢回大厅。

  2. 【普通玩法的某一关】

    1. 【方式 1 - 继续顺着玩下一关】需要立刻恢复因直玩而屏蔽的所有元素。

    2. 【方式 2 - 玩完当前关，引导回首页】和【方式 3 - 结束当前关，引导回首页】：当前关卡结束前仍为直玩的游戏模式，例如道具隐藏、免费道具可用等。使用引导将玩家导回大厅，回到大厅后再将游戏玩法内容切换为普通模式。

3. Unity 研发接入 ​

3.1 接入链路 ​

3.1.1 STEP 1 - 判断是否直玩进入 ​

需要在 SDK 初始化之后检查是否为直玩进入。

c#
ZMYSDKManager.SDKInitOver_Event += OnSDKInitOver;

void OnSDKInitOver(object sender, System.EventArgs e)
{
    XYX.FeedPlay.CheckIsFeedEnter((data) =>
    {
        if (data.isFeedEnter)
        {
            // Feed 直玩进入：直接切直玩模式，不加其他判断
            EnterWxFeedMode();
        }
        else
        {
            // 普通模式进入游戏
            EnterNormalMode();
        }
    });
}

如果判断为直玩进入，游戏应直接进入直玩逻辑，不要再走普通启动流程中的弹窗、引导、广告、支付等逻辑。

3.1.2 STEP 2 - 获取启动参数 ​

在接入前，需要跟策划确认直玩的进入模式，对标 2.1：

  • 如果有关卡概念，要先跟策划确认默认跳第几关，不要研发自行决定。

  • 如果有多个玩法或模式，要先跟策划确认默认用哪个，不要研发自行决定。

如需根据启动参数切换到指定直玩关卡，可以通过 XYX.GetLaunchOption 获取本次启动信息，其中 query 即为微信传入的启动参数。若项目公共库已经提供 XYX.TryGetLaunchQuery_GetGameLevel，也可以直接使用该封装读取 game_level。

c#
public class XYXLaunchOption
{
    public string scene_str;
    public LaunchScene scene;
    public Dictionary<string, string> query;
}

示例代码：

c#
string levelId = null;
XYXLaunchOption option = XYX.GetLaunchOption();

if (option != null &&
    option.query != null &&
    option.query.TryGetValue("game_level", out levelId))
{
    // 根据投放配置切换到指定直玩关卡
}
else
{
    // 使用策划确认过的默认直玩关卡
}

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

判断为直玩进入后，应立即注册直玩状态处理回调。

c#
XYX.FeedPlay.OnFeedStatusChange((action) =>
{
    // action >= 3 表示直玩已经结束，游戏需要回归普通模式
    if (action >= 3)
    {
        ExitWxFeedMode(action);
    }
});

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

3.1.4 STEP 4 - 跳转直玩关卡 ​

完成直玩判断、启动参数读取、状态回调注册后，尽快跳转直玩关卡。直玩场景加载完毕后，如项目仍需主动上报游戏可交互状态，请按原有接入调用上报。

c#
XYX.FeedPlay.CheckIsFeedEnter((data) =>
{
    if (!data.isFeedEnter)
    {
        EnterNormalMode();
        return;
    }

    XYX.FeedPlay.OnFeedStatusChange(OnFeedStatusChange);

    string levelId = GetWxFeedLevelFromLaunchQuery();
    LoadScene("WxFeedPlayScene", () =>
    {
        if (!isReportGameInteractive)
        {
            isReportGameInteractive = true;
            BridgeManager.xyxFunc.ReportGameInteractive(info);
        }

        StartWxFeedLevel(levelId);
    });
});

3.2 直玩状态更新处理 ​

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

  1. 游戏应当回归普通模式。

  2. 如有隐私弹框机制，当次不可弹出。

  3. 根据游戏自身设计恢复或引导：

    1. 如直玩关卡为独立抽出的模式，与主玩法关卡无关联，不存在连续性，则应通过良好的过渡或引导 UI，将玩家导向普通模式主页。

    2. 如直玩关卡为主玩法关卡的一关，存在连续性，则可以停留在当前页面，恢复跳出当前关卡的 UI 组件，并恢复成普通模式形态。

  4. 恢复游戏的视频点位、支付点位、退出点位等普通模式元素。

3.3 API 摘要 ​

3.3.1 XYX.FeedPlay.CheckIsFeedEnter ​

用于检查本次启动是否为 Feed 直玩进入。建议在 SDK 初始化完成后立即调用。

c#
XYX.FeedPlay.CheckIsFeedEnter((data) =>
{
    if (data.isFeedEnter)
    {
        // 直玩进入
    }
});

3.3.2 XYX.GetLaunchOption ​

用于获取本次启动信息。直玩投放常用参数包括 game_level，如项目需要，也可扩展读取玩法、模式或自定义参数。

c#
XYXLaunchOption option = XYX.GetLaunchOption();

3.3.3 XYX.FeedPlay.OnFeedStatusChange ​

用于监听直玩状态变化。

c#
XYX.FeedPlay.OnFeedStatusChange(Action<int> callback);

常用判断：action >= 3 即可认为直玩已结束，需要回归普通模式。

4. 自测调试 ​

SDK 支持 微信全真模拟 和 在线参数假模拟 两种方式。建议优先使用微信全真模拟。

4.1 微信全真模拟 ​

使用本方式，可拉起真实的微信直玩界面，最为直观有效，建议使用该方法。

手机基础库需大于 3.14.2，iOS 微信客户端版本需大于 8.0.69。

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

4.1.1 体验版启动参数 ​

该界面要求权限较高，只有运营权限才能进入配置。

配置后，可以生成一个专属体验版二维码，必须通过这个二维码进入。

  1. 无需指定关卡：index?minigame_direct_debug=true

  2. 需要指定关卡：index?minigame_direct_debug=true&game_level=5

4.1.2 开发版启动参数 ​

  1. 点击左上角《普通编译》，选择《添加编译模式》，模式名称自选。

  2. 无需跳关：minigame_direct_debug=true

  3. 需要指定关卡：minigame_direct_debug=true&game_level=5

根据版本继续操作：

  1. 开发版：点击确认后，开发者工具会重新编译游戏，再点击预览即可。

  2. 体验版：直接启动即可。

4.2 在线参数假模拟 ​

该方式只能验证游戏内跳转、点位屏蔽、状态恢复等业务逻辑，无法真正从广告入口启动。最后上线的包一定要关闭模拟开关。

5. 测试点位 ​

建议使用开发版工具预览调试。

5.1 业务测试点位 ​

5.1.1 进入游戏 ​

  1. 直玩模式

    1. 根据 2.1 正确处理玩法逻辑。

    2. 如游戏有在线跳玩法、模式、关卡配置，游戏表现正常。

    3. 根据 2.4.1 正确处理资质页、广告支付点位、退出点位。

    4. 游戏能正常启动，无缝跳到直玩模式，期间无需玩家额外操作。不允许在原正常流程上添加多余加载过渡页面。

    5. 进入过程不弹出除 SDK 登录失败弹框以外的任何弹框。游戏的 DIY 隐私弹框当次启动不可弹出。

    6. 直玩模式的进程不可被游戏元素打断，保证玩家一直停留在直玩模式里。例如需要屏蔽回到首页等按钮。

    7. 直玩模式需要屏蔽任何内购、广告相关元素，玩法为纯净游戏体验。

    8. 直玩模式的玩法内容，需要保证至少可玩 30 秒。

    9. 统计：进入直玩的统计正常，游玩过程统计正常，无遗漏、多报、误报。

  2. 普通模式

    1. 游戏能正常启动，体验跟普通保持一致。

    2. 如游戏有 DIY 隐私弹框逻辑，则需在首次非直玩启动时弹出。

  3. 通用

    1. 游戏可同时兼容直玩模式和普通模式。

5.1.2 直玩状态更新 ​

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

  1. 根据 2.2 正确处理玩法退出逻辑。如需让玩家回首页，需要提供引导界面。

  2. 根据 2.4.2 正确恢复普通模式元素。

  3. 统计：

    1. 退出直玩时或直玩关卡结束时统计正常，无遗漏、多报、误报。

    2. 回归普通模式后，一切统计正常，无遗漏、多报、误报。

5.2 SDK 测试点位 ​

对于线上包来说，仅当点击微信直玩结束页的《继续玩》回到游戏，或者通过任意方式让结束页消失后回到游戏，才算直玩结束。

停留在结束页并不算直玩结束。

6. 事件验收 ​

6.1 wx_feed_status_change ​

直玩广告过程会有专项事件 wx_feed_status_change，通过事件属性 action 区分 4 种情况。在 mode_level 适用时，也会附带作为事件属性一同上报。

action 值含义是否可一直统计到
1阶段 1：进入直玩广告，蒙层遮挡否。蒙层先于代码出现，可能无法统计
2阶段 2：戳破蒙层，正在玩否。如果玩家在游戏代码执行前即戳破蒙层，则监听不到
3阶段 3：直玩结束，点击继续玩是。只要点击了继续玩就能统计
4正常结束后返回，或直玩模式异常退出后热启动返回本次游戏否。如果玩家异常退出且杀掉游戏进程，则无法上报

6.2 is_wx_feed 基础属性验收 ​

通过直玩进入的游戏，游玩过程产生的所有事件都会附带 is_wx_feed 属性。

  • 在直玩点击继续玩之前，is_wx_feed 为 false。

  • 在直玩继续玩或异常退出后，也就是产生 wx_feed_status_change 且 action 为 3 或 4 之后，所有 is_wx_feed 均为 true。