Skip to content

游戏开发示例 ​

本页供小游戏开发者将广告接到场景、按钮和游戏流程中。先完成双端 APP 广告接入,再在 SUD OpenPaaS Runtime 中运行游戏脚本;普通浏览器环境不会自动提供 sud 对象。

将示例中的 YOUR_*_AD_UNIT_ID 替换为对应广告类型的 SUD OpenPaaS 广告单元 ID。下面的 createBannerExample、createFullscreenExample 和场景函数均为游戏侧示例代码,不是 SDK 新增接口。把两个辅助函数复制到游戏脚本中,再选择需要的广告类型接入。

调用时机 ​

游戏时机游戏侧操作
进入需要广告的场景创建实例、注册监听;Banner 自动加载,其余类型调用 load()
收到 onLoad标记广告可用
关卡结束、用户点击激励按钮或进入启动展示时机调用示例对象的 show()
临时遮挡 Banner调用 setVisible(false);恢复时传 true
退出对应场景调用 dispose() 注销监听并销毁实例

load() 的 Promise 完成只表示加载调用已被接受,不能据此设置“加载成功”。全屏广告未就绪时,示例的 show() 返回 false,不会排队到之后突然展示。返回 true 只表示本次已发起展示调用,实际失败仍由 onError 处理。

每个全屏实例只展示一次;关闭或失败后会清理,需要下一次广告时重新创建。场景退出函数由游戏引擎的实际生命周期调用,不要在创建实例后立即调用。

对应接口:sud.createBannerAd。

onResize 只接收实际尺寸,不触发展示,也不代替 onLoad。

javascript
function createBannerExample(adUnitId, style, adIntervals) {
    // adIntervals 为可选参数,暂未生效
    const ad = sud.createBannerAd({ adUnitId, style, adIntervals });
    if (!ad) {
        throw new Error('Banner ad is unavailable in this runtime');
    }

    let active = true;
    let loaded = false;
    let visible = true;

    function dispose() {
        if (!active) return;
        active = false;
        ad.offLoad(onLoad);
        ad.offError(onError);
        ad.offResize(onResize);
        ad.destroy();
    }

    function onError(err) {
        if (!active) return;
        console.error('Banner ad failed', err);
        dispose();
    }

    function onLoad() {
        if (!active || loaded) return;
        loaded = true;
        if (visible) ad.show().catch(onError);
    }

    function onResize({ width, height }) {
        if (!active) return;
        console.log('Banner actual size', width, height);
    }

    function setVisible(value) {
        if (!active || visible === value) return;
        visible = value;
        if (!loaded) return;
        if (visible) {
            ad.show().catch(onError);
        } else {
            ad.hide().catch(onError);
        }
    }

    ad.onError(onError);
    ad.onLoad(onLoad);
    ad.onResize(onResize);
    return { setVisible, dispose };
}

进入场景时创建 Banner,传入最大可用逻辑宽高(Android 为 dp,iOS 为 pt)。广告在区域内水平居中、顶部对齐。第三个参数 adIntervals 为可选参数,暂未生效。

需要查询容器宽高和像素比时,使用 sud.getContainerInfo。根据游戏实际预留区域填写下面的 style,无需乘 pixelRatio;onResize 的实际宽高也无需再换算。

javascript
const banner = createBannerExample('YOUR_BANNER_AD_UNIT_ID', {
    left: 20,
    top: 100,
    width: 320,
    height: 100,
}, 30);

function onOverlayOpened() {
    banner.setVisible(false);
}

function onOverlayClosed() {
    banner.setVisible(true);
}

function onBannerSceneExit() {
    banner.dispose();
}

即使广告仍在加载,退出场景也应调用 onBannerSceneExit();迟到的加载回调不会再调用 show()。加载期间隐藏 Banner 会保存隐藏状态,加载成功后保持隐藏。

全屏广告的加载与清理 ​

插屏和激励视频共用以下辅助函数。将其复制到游戏脚本中,在展示时机调用 show(),退出场景时调用 dispose()。

javascript
function createFullscreenExample(ad, onClosed) {
    if (!ad) {
        throw new Error('Full-screen ad is unavailable in this runtime');
    }

    let active = true;
    let loaded = false;
    let showRequested = false;

    function dispose() {
        if (!active) return;
        active = false;
        ad.offLoad(onLoad);
        ad.offError(onError);
        ad.offClose(onClose);
        ad.destroy();
    }

    function onError(err) {
        if (!active) return;
        console.error('Full-screen ad failed', err);
        dispose();
    }

    function onLoad() {
        if (active) loaded = true;
    }

    function onClose(result) {
        if (!active) return;
        dispose();
        if (onClosed) onClosed(result);
    }

    function show() {
        if (!active || !loaded || showRequested) return false;
        showRequested = true;
        ad.show().catch(onError);
        return true;
    }

    ad.onError(onError);
    ad.onClose(onClose);
    ad.onLoad(onLoad);
    ad.load().catch(onError);
    return { show, dispose };
}

插屏:关卡结束时展示 ​

对应接口:sud.createInterstitialAd。进入关卡时创建并加载,在关卡结束回调中调用 onLevelFinished();退出场景时调用 onInterstitialSceneExit()。

javascript
const interstitial = createFullscreenExample(
    sud.createInterstitialAd({ adUnitId: 'YOUR_INTERSTITIAL_AD_UNIT_ID' }),
    () => console.log('Interstitial closed'),
);

function onLevelFinished() {
    if (!interstitial.show()) {
        console.log('Interstitial is not ready; continue the game');
    }
}

function onInterstitialSceneExit() {
    interstitial.dispose();
}

激励视频:用户主动选择后展示 ​

对应接口:sud.createRewardedVideoAd。进入奖励场景时创建并加载;只有用户点击“观看广告”按钮后才调用 onRewardButtonClick(),加载完成本身不会触发展示。

javascript
const rewarded = createFullscreenExample(
    sud.createRewardedVideoAd({
        adUnitId: 'YOUR_REWARDED_AD_UNIT_ID',
        // 以下为可选参数,暂未生效
        multiton: true,
        disableFallbackSharePage: false,
    }),
    (result) => {
        console.log('Reward result', result);
        if (result?.isEnded === true) {
            console.log('Reward condition met');
            // Apply the game's reward once here.
        }
    },
);

function onRewardButtonClick() {
    if (!rewarded.show()) {
        console.log('Rewarded ad is not ready; keep the user in the game');
    }
}

function onRewardSceneExit() {
    rewarded.dispose();
}

onClose 的 isEnded 表示本次广告是否满足奖励条件。仅当 isEnded === true 时发放奖励,同一次展示只发放一次。

接入检查 ​

在游戏中检查加载成功、加载失败、场景退出和重复点击。Banner 还需检查加载中隐藏、恢复显示、尺寸回调及展示位置;激励视频检查满足和未满足奖励条件两种关闭结果,并确认同一次展示只发放一次奖励。