游戏开发示例
本页供小游戏开发者将广告接到场景、按钮和游戏流程中。先完成双端 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 处理。
每个全屏实例只展示一次;关闭或失败后会清理,需要下一次广告时重新创建。场景退出函数由游戏引擎的实际生命周期调用,不要在创建实例后立即调用。
Banner:场景展示与隐藏
对应接口:sud.createBannerAd。
onResize 只接收实际尺寸,不触发展示,也不代替 onLoad。
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 的实际宽高也无需再换算。
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()。
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()。
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(),加载完成本身不会触发展示。
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 还需检查加载中隐藏、恢复显示、尺寸回调及展示位置;激励视频检查满足和未满足奖励条件两种关闭结果,并确认同一次展示只发放一次奖励。
