小游戏：旋灯残响

活动页底下已经放了「去每日挑战」「活动规则」「我的礼物」，现在还想加一条广告。把横幅往窗口底部一贴，最下面的入口就可能被盖住。等广告加载好才把按钮往上挪，玩家点到一半，按钮还会突然换位置。

《旋灯残响》的做法是**进活动页时先留一块位置，微信回传广告的宽高后再展示**。下面从后台创建广告位开始，给一份能接进 Cocos Creator 3.8 的精简示例，再说明项目里是怎么把它接到活动页的。


*图 1　使用 11 月 12 日已有 Web 构建，在 390 × 844 浏览器视口重拍。两张图使用同一组演示活动数据，右图切换到预留布局，可以看到主按钮和底部链接怎么重新排布。微信广告的实际填充和展示要用手机验证。*

## 一 在微信后台创建广告位

1. 登录自己小游戏的微信公众平台，进入「流量主 → 广告管理」。
2. 新建广告位，选择**原生模板广告**，在模板编辑器中选择横幅样式。
3. 保存模板，从广告位管理复制 `adUnitId`。真机预览时，微信开发者工具的 AppID 和广告位所属小游戏要对应上。

后台展示的选项和广告位状态以当前账号为准。这里用的接口是 `wx.createCustomAd()`。微信提供的 `onResize` 只覆盖部分横幅模板，选定样式后，真机上要先确认它能在调用 `show()` 前回传尺寸。本文按这个顺序接入，超时仍拿不到尺寸就跳过该次展示。[腾讯广告小游戏接入资料](https://training.tencentads.com/uploads/202406/nTROJ2vg_hpC4C1.pdf) · [微信官方小游戏 API 定义](https://github.com/wechat-miniprogram/minigame-api-typings/blob/master/types/wx/lib.wx.api.d.ts)

## 二 先划出按钮和广告各自能用的区域

原生模板广告由微信在游戏画布上方显示。Cocos 的按钮和横幅可能占用同一块屏幕，单改按钮在场景里的节点顺序解决不了遮挡。先把活动内容的底线定下来，再算广告能不能放进底下的区域。[微信原生模板广告说明](https://developers.weixin.qq.com/minigame/dev/api/ad/CustomAd.html)

在《旋灯残响》里，满足广告配置和宿主条件时，活动页进场就保留窗口底部的 **24%**。按钮、活动规则和礼物入口排在这条线以上，活动主图可以等比收小。24% 是本项目的布局预算，用在自己的项目时，可以根据短屏上的按钮高度和横幅尺寸重新选值。


*图 2　以 390 × 844 的示例窗口计算横幅位置。图中尺寸用于演示计算。*

这里用微信窗口坐标算原生广告的位置。左上角是原点，`top` 向下增大。假设窗口宽 390、高 844，`safeArea.bottom` 是 810，广告实际宽 350、高 84。

- 底部安全区的高度是 `844 - 810 = 34`。
- 横幅居中的 `left` 是 `(390 - 350) / 2 = 20`。
- 横幅底边贴着安全区下边界，`top` 是 `844 - 34 - 84 = 726`。
- 加上按钮与广告之间至少 8 单位的间隔，总共需要 `84 + 34 + 8 = 126`。它能放进 `844 × 24% ≈ 203` 的底部预留区域。

初始的 `style.width` 只对支持设置宽度的模板生效。显示前还要用 `onResize` 回传的实际宽度检查能不能放下、重新计算居中位置。[微信官方小游戏 API 定义](https://github.com/wechat-miniprogram/minigame-api-typings/blob/master/types/wx/lib.wx.api.d.ts)

## 三 创建广告，尺寸通过后再展示

下面的 `activity-banner.ts` 可以放进自己的 Cocos 脚本目录。它只负责一个竖屏活动页的原生广告。调用方传入广告位 ID 和一个排版回调，得到一个退出时要调用的清理函数。

```ts
export const BOTTOM_SLOT_RATIO = 0.24;
const BUTTON_GAP = 8;

type AdSize = { width: number; height: number };
type WindowInfo = {
    windowWidth: number;
    windowHeight: number;
    safeArea?: { bottom: number };
};

interface NativeCustomAd {
    style: { left: number; top: number };
    show(): Promise<unknown>;
    destroy(): void;
    onResize(listener: (size: AdSize) => void): void;
    onError(listener: (error: unknown) => void): void;
    onClose?(listener: () => void): void;
}

interface WxAdHost {
    getWindowInfo?(): WindowInfo;
    getSystemInfoSync?(): WindowInfo;
    canIUse?(name: string): boolean;
    createCustomAd?(options: {
        adUnitId: string;
        adIntervals: number;
        style: { left: number; top: number; width: number };
    }): NativeCustomAd;
}

function readWindow(wx: WxAdHost): WindowInfo | undefined {
    const info = wx.getWindowInfo?.() ?? wx.getSystemInfoSync?.();
    if (
        info
        && Number.isFinite(info.windowWidth) && info.windowWidth > 0
        && Number.isFinite(info.windowHeight) && info.windowHeight > 0
    ) {
        return info;
    }
    return undefined;
}

function placeBanner(info: WindowInfo, size: AdSize) {
    const { windowWidth, windowHeight, safeArea } = info;
    const bottom = safeArea?.bottom ?? windowHeight;
    const safeBottom = Math.max(0, windowHeight - bottom);
    const needed = size.height + safeBottom + BUTTON_GAP;

    if (
        !Number.isFinite(needed)
        || !Number.isFinite(size.width)
        || size.width <= 0 || size.width > windowWidth
        || size.height <= 0
        || needed > windowHeight * BOTTOM_SLOT_RATIO
    ) {
        return undefined;
    }

    return {
        left: (windowWidth - size.width) / 2,
        top: windowHeight - safeBottom - size.height,
    };
}

export function mountActivityBanner(
    adUnitId: string,
    reserveBottom: (reserved: boolean) => void,
): () => void {
    const wx = (globalThis as typeof globalThis & { wx?: WxAdHost }).wx;
    const id = adUnitId.trim();
    let current: NativeCustomAd | undefined;
    let timeout: ReturnType<typeof setTimeout> | undefined;

    const clearTimeoutIfSet = () => {
        if (timeout !== undefined) clearTimeout(timeout);
        timeout = undefined;
    };
    const destroyAd = () => {
        clearTimeoutIfSet();
        const ad = current;
        current = undefined;
        try {
            ad?.destroy();
        } catch (error) {
            console.warn('[活动页广告] 销毁失败', error);
        }
    };
    const leavePage = () => {
        destroyAd();
        reserveBottom(false);
    };

    try {
        if (
            !id
            || !wx?.createCustomAd
            || wx.canIUse?.('createCustomAd') === false
        ) {
            reserveBottom(false);
            return leavePage;
        }

        const initial = readWindow(wx);
        if (!initial) {
            reserveBottom(false);
            return leavePage;
        }

        reserveBottom(true);
        const ad = wx.createCustomAd({
            adUnitId: id,
            adIntervals: 60,
            style: {
                left: 0,
                top: initial.windowHeight,
                width: Math.min(initial.windowWidth, 600),
            },
        });

        current = ad;
        let showRequested = false;

        const fail = (error: unknown) => {
            if (current !== ad) return;
            console.warn('[活动页广告] 跳过本次展示', error);
            destroyAd();
        };

        timeout = setTimeout(() => fail('等待尺寸或展示超时'), 5000);
        ad.onError(fail);
        ad.onClose?.(() => {
            if (current === ad) destroyAd();
        });
        ad.onResize((size) => {
            if (current !== ad) return;

            try {
                const info = readWindow(wx);
                const position = info && placeBanner(info, size);
                if (!position) {
                    fail('实际尺寸超出底部预留区域');
                    return;
                }

                ad.style.left = position.left;
                ad.style.top = position.top;

                if (showRequested) return;
                showRequested = true;
                void ad.show().then(() => {
                    if (current === ad) clearTimeoutIfSet();
                }).catch(fail);
            } catch (error) {
                fail(error);
            }
        });
    } catch (error) {
        console.warn('[活动页广告] 无法创建广告组件', error);
        destroyAd();
    }

    return leavePage;
}
```

这份示例在尺寸校验通过后才调用 `show()`。广告过大、未填充或展示失败时会销毁实例，活动内容照常显示。只要还在同一次进入活动页的过程中，就保持原先预留的布局，避免按钮位置来回变动。真正退出活动页时，再清掉占位。5 秒是示例等待时间，`adIntervals: 60` 是传给支持自动刷新模板的刷新间隔。


*图 3　Cocos 先排好活动内容，微信回传尺寸后才决定展示。离开页面后，晚到的回调也会被忽略。*

## 四 把广告接到 Cocos 活动页

如果自己的项目还没有活动页的布局代码，可以用两个容器接起来。

1. 活动页根节点铺满可见窗口，背景留在根节点下。
2. 创建一个 `ActivityContent` 容器，挂 `Widget`，对齐根节点四边。底部对齐用绝对值。
3. 把操作按钮和底部链接放在 `ActivityContent` 下，让它们的 `Widget` 对齐**内容容器**底部，`Align Mode` 设为 `ALWAYS`。容器底线抬高时，按钮位置和点击区域会跟着上移。内容较长的页面可以让中段滚动。[Cocos Widget 组件参考](https://docs.cocos.com/creator/3.8/manual/zh/ui-system/components/editor/widget.html)

在同一目录创建 `ActivityBannerView.ts`，把下面的组件挂到活动页根节点。将 `ActivityContent` 的 `Widget` 拖到组件的 `Content Widget` 字段，再填自己的 `Ad Unit Id`。用节点的启用和停用控制活动页进出时，组件会随页面创建和销毁广告。

```ts
import { _decorator, Component, view, Widget } from 'cc';
import { BOTTOM_SLOT_RATIO, mountActivityBanner } from './activity-banner';

const { ccclass, property } = _decorator;

@ccclass('ActivityBannerView')
export class ActivityBannerView extends Component {
    @property(Widget)
    contentWidget: Widget | null = null;

    @property
    adUnitId = '';

    private disposeAd?: () => void;

    onEnable(): void {
        const widget = this.contentWidget;
        if (!widget) return;

        const normalBottom = widget.bottom;
        this.disposeAd = mountActivityBanner(this.adUnitId, (reserved) => {
            const slotHeight = view.getVisibleSize().height * BOTTOM_SLOT_RATIO;
            widget.bottom = reserved
                ? Math.max(normalBottom, slotHeight)
                : normalBottom;
            widget.updateAlignment();
        });
    }

    onDisable(): void {
        this.disposeAd?.();
        this.disposeAd = undefined;
    }
}
```

原生横幅用微信窗口的 `left`、`top`，Cocos 容器用自己的逻辑尺寸，两边用**同一个 24% 比例**对齐这条边界。上面的换算假设活动页根节点与微信可见窗口覆盖同一块屏幕。如果游戏只占窗口的一部分，就要先把边界转换到那个视口。

《旋灯残响》的活动页用的是预制体。进页时控制器设置 `bannerSlotReserved`，布局代码随即重排已有的主图、按钮和链接。后续 `onResize` 用于校验及定位原生广告，页面布局早已确定。项目还会在活动规则弹窗盖住页面、切到后台或离页时销毁广告，窗口尺寸变化时重新判断何时创建。项目里的等待和展示间隔也由广告管理层处理。自己的活动页如果始终挂在场景里，需把创建和清理接到页面显示、隐藏事件。打开规则弹窗、离开前台时也要让原生广告退场。

在这个项目里，广告位 ID 从 `.env.local` 的 `CIRCUIT_WECHAT_CUSTOM_AD_UNIT_ID` 读取，构建微信目标时写入 `game.js`。下面是项目配置示例，值要换成自己后台创建的广告位。使用上面独立示例时，在组件里填写即可。

```bash
# .env.local
CIRCUIT_WECHAT_CUSTOM_AD_UNIT_ID=adunit-your-id
```

## 五 真机上测这五件事

| 怎么测 | 应该看到什么 |
| --- | --- |
| 正常进入活动页 | 主按钮和两个链接先排到预留线以上。横幅出现后，按钮位置和大小保持稳定 |
| 窄屏或带底部手势条的手机 | 横幅避开手势区，按钮和规则入口都点得到 |
| 使用空广告位配置 | 使用普通活动页布局，底部没有广告空位 |
| 触发无填充、尺寸不合适或超时 | 当前活动页可继续操作，本次广告跳过 |
| 广告还在准备时离页、打开规则弹窗或切到后台 | 广告不会在别的页面上突然出现，也不会盖到弹窗上 |

遇到广告始终不出现时，先查广告位归属和后台状态，再分辨 **`onError` 已报错**、**尺寸回调没到**、**尺寸超预算**、**`show()` 失败**。微信的错误码 `1002` 对应广告单元无效，`1004` 对应无合适广告，`1005` 对应广告组件审核中。开发者工具能运行活动页后，再扫码到手机检查实际展示、按钮点击和离页清理。[微信官方错误码定义](https://github.com/wechat-miniprogram/minigame-api-typings/blob/master/types/wx/lib.wx.api.d.ts)

这篇的项目截图展示了有无预留区域时的排版。本次运行的 17 项项目测试覆盖了尺寸检查、预留区域、离页清理、弹层遮挡等行为。实际广告填充与展示以对应广告位的微信真机验收为准。

项目代码可以从三个文件对照。原生广告在 `assets/scripts/platform/wechat-display-ads.ts`，活动页显示条件在 `assets/scripts/presentation/cocos-v2/game-controller-v2.ts`，按钮和主图的排版在 `assets/scripts/presentation/mk-ui/feature-page-layout.ts`。


活动页底下已经放了「去每日挑战」「活动规则」「我的礼物」，现在还想加一条广告。把横幅往窗口底部一贴，最下面的入口就可能被盖住。等广告加载好才把按钮往上挪，玩家点到一半，按钮还会突然换位置。

微信小游戏原生模板广告接入教程｜在活动页底部放广告，避开按钮

人工智能

在Cocos Creator 3.8中集成微信原生横幅广告时，预留24%底部空间并等待onResize回调，确保按钮稳定不遮挡。本文提供完整代码示例，涵盖创建广告位、尺寸校验、超时处理及真机测试要点，优化用户体验和广告展示效率。

代码解释

容器

腾讯云双十一大促

coding

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

微信小游戏原生模板广告接入教程｜在活动页底部放广告，避开按钮-腾讯云开发者社区-腾讯云

微信小游戏原生模板广告接入教程｜在活动页底部放广告，避开按钮

微信小游戏原生模板广告接入教程｜在活动页底部放广告，避开按钮

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐