广告接入

一. 引入联盟广告 Javascript 文件

<script type="text/javascript" src="https://adsfs.oppomobile.com/mp/app/union/h5/index.js"><script>

注：目前只支持OPPO浏览器（版本号4.3及以上版本）和OPPO游戏大厅（Android4.4及以上）场景。另外，不允许将广告JS文件存放在本地。

二. Banner 广告

Banner 广告组件是由纯图片或图文混合组成的。开发者可以调用opUnion.createBannerAd(Object object)创建 Banner 广告组件。Banner 广告组件在创建后会自动拉取广告数据并进行渲染。

注：横屏情况下不会展现Banner广告

使用示例

创建广告

var bannerAd = opUnion.createBannerAd({
    containerId: 'xxxx',
    posId: 'xxxx',
    mediaId: 'xxxx'
});

广告拉取成功与失败

Banner广告在创建后会自动拉取广告并渲染。

如果拉取成功，BannerAd.onLoad()注册的回调函数会执行。它的回调函数中没有参数传递。

bannerAd.onLoad(function () {
    console.log('Banner广告加载成功');
})

如果拉取失败，BannerAd.onError()注册的回调函数会执行。回调函数的参数是一个包含错误信息的对象。错误信息详见附录

bannerAd.onError(function (err) {
    console.log(err);
})

销毁

每个 BannerAd 实例在创建后会去拉取一次广告数据并进行渲染，并会定时更新。如果想要废弃现有的BannerAd，需进行销毁。如果不对废弃的 BannerAd 进行销毁，则会导致其上的事件监听器无法释放。当没有释放的 BannerAd 积累过多时，将会产生性能问题。

注：调用销毁方法，会将展示广告的DOM元素一并销毁，而后重新创建 BannerAd 时需要重新创建展示广告的DOM元素。

oldBannerAd.destroy();
var el = document.createElement('div');
el.id = 'banner';
el.style.position = ...;
var newBannerAd = opUnion.createBannerAd({
  // ...
});

Banner广告方法

opUnion.createBannerAd(Object object)

创建Banner广告

参数

Object object

返回值

BannerAd广告组件

BannerAd.onload(function callback)

监听Banner广告加载事件

参数

callback

监听事件的回调函数

BannerAd.offLoad()

取消监听Banner广告加载事件

BannerAd.onError(function callback)

监听Banner广告错误事件

参数

callback

监听事件的回调函数

callback回调函数

res

BannerAd.offError()

取消监听Banner广告错误事件

BannerAd.destroy()

销毁 banner 广告

三. 插屏广告

插屏广告组件是由纯图片或图文混合组成的。开发者可以调用opUnion.createInterstitialAd(Object object)创建插屏广告组件。插屏广告组件在创建后会自动拉取广告数据。

使用示例

创建广告

var interstitialAd = opUnion.createInterstitialAd({
    posId: 'xxxx',
    mediaId: 'xxxx'
})

显示/隐藏

插屏广告组件默认是隐藏的，需要调用InterstitialAd.show()进行展示

interstitialAd.show()

只有在用户点击插屏广告组件上的关闭按钮，广告才会关闭，开发者不可控制插屏广告组件的隐藏

广告拉取成功与失败

插屏广告组件在创建后会自动拉取广告，用户点击关闭按钮后会去拉取下一条广告。

如果拉取成功，InterstitialAd.onLoad()会执行，InterstitialAd.show()返回的 Promise 也是一个 resolved Promise。两者的回调函数中都没有参数传递。

interstitialAd.onLoad(function () {
    console.log('插屏广告加载成功')
})

interstitialAd.show().then(function () {
    console.log('插屏广告显示')
})

如果拉取失败，通过InterstitialAd.onError()注册的回调函数会执行，回调函数的参数是一个包含错误信息的对象。错误信息详见附录

interstitialAd.onError(function (err) {
    console.log(err);
})

InterstitialAd.show()返回的 Promise 也是一个 rejected Promise

interstitialAd.show().catch(function (err) {
    console.log(err)
})

拉取失败，重新拉取

如果组件的某次自动拉取失败，那么之后调用的 show() 将会被 reject。此时可以调用InterstitialAd.load()手动重新拉取广告。

interstitialAd.show().catch(function (err) {
    interstitialAd.load().then(function () {
        interstitialAd.show()
    })
})

如果组件的自动拉取是成功的，那么调用 load() 方法会直接返回一个 resolved Promise，而不会去拉取广告。

interstitialAd.load().then(function () {
    interstitialAd.show()
})

监听用户关闭广告

只有在用户点击激励视频广告组件上的关闭按钮时，广告才会关闭。这个事件可以通过 InterstitialAd.onClose()监听。

interstitialAd.onClose(function () {
    console.log('插屏广告关闭');
})

插屏广告方法

opUnion.createInterstitialAd(Object object)

创建插屏广告

参数

Object object

返回值

InterstitialAd

插屏广告组件

Promise InterstitialAd.load()

加载插屏广告

返回值

Promise

插屏广告加载数据的结果

Promise InterstitialAd.show()

显示插屏广告

返回值

Promise

插屏广告显示操作的结果

InterstitialAd.onload(function callback)

监听插屏广告加载事件

参数

callback

监听事件的回调函数

InterstitialAd.offLoad()

取消监听插屏广告加载事件

InterstitialAd.onError(function callback)

监听插屏广告错误事件

参数

callback

监听事件的回调函数

callback回调函数

res

InterstitialAd.offError()

取消监听插屏广告错误事件

InterstitialAd.onClose(function callback)

监听插屏广告关闭事件

参数

callback

监听事件的回调函数

InterstitialAd.offClose()

取消监听插屏广告关闭事件

四. 激励视频广告

激励视频广告组件是由图文和视频混合组成的。开发者可以调用opUnion.createVideoAd(Object object)创建激励视频广告组件。激励视频广告组件在创建后会自动拉取广告数据。

注：当无广告返回时，不展现激励视频广告入口。

使用示例

创建广告

var videoAd = opUnion.createVideoAd({
    posId: 'xxxx',
    mediaId: 'xxxx'
})

显示/隐藏

激励视频广告组件默认是隐藏的，需要调用VideoAd.show()进行展示

videoAd.show()

只有在用户点击激励视频广告组件上的关闭按钮，广告才会关闭，开发者不可控制激励视频广告组件的隐藏

广告拉取成功与失败

激励视频广告组件在创建后会自动拉取广告，用户点击关闭按钮后会去拉取下一条广告。

如果拉取成功，VideoAd.onLoad()会执行，VideoAd.show()返回的 Promise 也是一个 resolved Promise。两者的回调函数中都没有参数传递。

videoAd.onLoad(function () {
    console.log('激励视频广告加载成功')
})

videoAd.show().then(function () {
    console.log('激励视频广告显示')
})

如果拉取失败，通过VideoAd.onError()注册的回调函数会执行，回调函数的参数是一个包含错误信息的对象。错误信息详见附录

videoAd.onError(function (err) {
    console.log(err);
})

VideoAd.show()返回的 Promise 也是一个 rejected Promise

videoAd.show().catch(function (err) {
    console.log(err)
})

拉取失败，重新拉取

如果组件的某次自动拉取失败，那么之后调用的 show() 将会被 reject。此时可以调用VideoAd.load()手动重新拉取广告。

videoAd.show().catch(function (err) {
    videoAd.load().then(function () {
        videoAd.show()
    })
})

如果组件的自动拉取是成功的，那么调用 load() 方法会直接返回一个 resolved Promise，而不会去拉取广告。

videoAd.load().then(function () {
    videoAd.show()
})

监听用户关闭广告

只有在用户点击激励视频广告组件上的关闭按钮时，广告才会关闭。这个事件可以通过 VideoAd.onClose()监听。其的回调函数会传入一个参数 res， res.isEnded描述广告被关闭时的状态

开发者可以根据res.isEnded判断视频是否播放结束，可以向用户下发奖励

videoAd.onClose(function (res) {
    if (res && res.isEnded) {
        // 正常播放结束，可以下发奖励
    } else {
        // 播放中途退出，不下发奖励
    }
})

激励视频广告方法

opUnion.createVideoAd(Object object)

创建激励视频广告

参数

Object object

返回值

VideoAd

激励视频广告组件

Promise VideoAd.load()

加载激励视频广告

返回值

Promise

激励视频广告加载数据的结果

Promise VideoAd.show()

显示激励视频广告

返回值

Promise

激励视频广告显示操作的结果

VideoAd.onload(function callback)

监听激励视频广告加载事件

参数

callback

监听事件的回调函数

VideoAd.offLoad()

取消监听激励视频广告加载事件

VideoAd.onError(function callback)

监听激励视频广告错误事件

参数

callback

监听事件的回调函数

callback回调函数

res

VideoAd.offError()

取消监听激励视频广告错误事件

VideoAd.onClose(function callback)

监听激励视频广告关闭事件

参数

callback

监听事件的回调函数

callback回调函数

res

VideoAd.offClose()

取消监听激励视频广告关闭事件

五. 原生广告

原生广告组件是由图文混合组成的。开发者可以调用opUnion.createNativeAd(Object object)创建原生广告组件。

注：提供素材给开发者，由开发者进行样式的渲染。

使用示例

创建广告

var nativeAd = opUnion.createNativeAd({
    posId: 'xxxx',
    mediaId: 'xxxx'
})

加载广告

原生广告组件需要调用NativeAd.load()手动加载广告

nativeAd.load()

原生广告会将广告数据暴露给用户，让用户自己渲染广告

广告拉取成功与失败

原生广告如果拉取成功，NativeAd.onLoad()会执行，NativeAd.load()返回的 Promise 也是一个 resolved Promise。两者的回调函数的参数是一个包含广告信息的对象。

object.list 的结构

开发者可以根据广告信息自由渲染

nativeAd.onLoad(function (res) {
    console.log('原生广告数据： ', res)
})

nativeAd.load().then(function (res) {
    console.log('原生广告数据： ', res)
})

如果拉取失败，通过NativeAd.onError()注册的回调函数会执行，回调函数的参数是一个包含错误信息的对象。错误信息详见附录

nativeAd.onError(function (err) {
    console.log(err);
})

NativeAd.load()返回的 Promise 也是一个 rejected Promise

nativeAd.load().catch(function (err) {
    console.log(err)
})

曝光上报

广告全部展示在可见区域，则满足有效曝光条件。当开发者判断当前广告满足有效曝光的上报条件时，需要调用nativeAd.doExpose()进行曝光上报。广告列表返回为一个数组，需传递曝光的索引。

nativeAd.doExpose({
    index: 0, // 曝光的为广告列表的第N个
    containerId: 'xxxx'
})

点击上报

当广告被有效点击后，需要调用nativeAd.doClick()，进行点击上报。

注意：点击上报中的各项参数请如实填写，如果不进行广告的点击上报或者上报错误，则将会影响此原生广告位的收入。广告列表返回为一个数组，需传递曝光的索引。

nativeAd.doClick({
    index: 1,
    containerId: 'xxxx',
    mouse: { // 点击时按下横纵坐标，弹起横纵坐标
        downX: 'xx',
        downY: 'xx',
        upX: 'xx',
        upY: 'xx'
    }
})

原生广告方法

opUnion.createNativeAd(Object object)

创建原生广告

参数

Object object

返回值

NativeAd

原生广告组件

Promise NativeAd.load()

加载原生广告

返回值

Promise

原生广告加载数据的结果

NativeAd.doExpose(Object object)

原生广告曝光上报

参数

Object object

NativeAd.doClick(Object object)

原生广告点击上报

参数

Object object

object.mouse的结构

NativeAd.onload(function callback)

监听原生广告加载事件

参数

callback

监听事件的回调函数

callback回调函数

res

NativeAd.offLoad()

取消监听原生广告加载事件

NativeAd.onError(function callback)

监听原生广告错误事件

参数

callback

监听事件的回调函数

callback回调函数

res

NativeAd.offError()

取消监听原生广告错误事件

六. 附录

创意类型

错误码

七. FAQ

广告是否支持除了OPPO小游戏之外的环境调试？

解决方法：

需要在OPPO小游戏环境进行测试。

引入JS SDK后报错 Cannot read property 'appendChild' of null

解决方法：

将广告的script标签放在body标签后面可以解决问题。

请求广告时出现1003？

解决方法：

1. 先尝试多请求几次；

2. 如果一直提示1003，可以联系小游戏运营人员反馈。

插屏或BANNER广告点击后游戏无反应

解决方法：

1. 尝试在游戏中创建一个iframe标签，设置src属性，如https://www.oppo.com，并尝试点击；
2. 若点击后仍出现相同情况，需检测游戏逻辑是否问题；
3. 白鹭引擎尝试手动触发egret.ticker.resume；
4. 如果以上步骤未解决问题，可以联系小游戏运营人员反馈。

创建广告时提示opUnion不存在

解决方法：

1. 检查运行环境。目前仅允许在OPPO小游戏下运行JS SDK，且需要保证Android系统在4.4及以上版本；
2. 尝试输出window.android.getAppVersion()。如有报错，请下载最新的调试包，https://cdofs.oppomobile.com/cdo-activity/static/201809/30/gamehall/book/not_battle/readme.html；
3. 若使用的仍旧是测试环境JS SDK，请改成正式：<script type="text/javascript" src="https://adsfs.oppomobile.com/mp/app/union/h5/index.js"></script>；
4. 尝试把script标签放到body标签后面；
5. 尝试动态加载JS SDK，并检测是否加载成功；
6. 如果以上步骤未解决问题，可以联系小游戏运营人员反馈。

containerId是什么？

解决方法：

1. DOM(https://developer.mozilla.org/en-US/docs/Glossary/DOM)，是由开发者通过HTML或者Javascript生成的，containerId即为开发者生成的DOM的id属性(https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id)；
2. 开发者生成的广告想置于哪一个DOM中，则将该DOM的id传递；
3. 若是原生广告，由webgl渲染生成的广告，请传递游戏的canvas的id。

例： 创建banner的DOM

        var id = '_' + Math.random().toString(36).slice(2);

        el = document.createElement('div');

        el.id = id;

        el.style.position = 'absolute';

        el.style.zIndex = 999;

        el.style.bottom = 0;

        el.style.width = '100%';

        el.style.fontSize = 0;

        document.body.appendChild(el);

Webgl渲染图片跨域

解决方法：

1. 若图片为本地渲染，则不会出现跨域的错误；
2. 若非本地渲染，可以使用游戏内元素代替图片素材进行渲染。

出现Uncaught in promise

解决方法：

1. 详见官方文档： https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise；
2. 需要加上catch捕获错误。

收到日志报"Mixed Content: The page at ...... was loaded over HTTPS, but requested an insecure image ...... This content should also be served over HTTPS."

解决方法：

对接入无影响，可以直接忽略。

Banner广告未出现

解决方法：

1. 检查containerId是否填写正确，通过输出document.getElementById(containerId)校验；
2. 使用 getBoundingClientRect查看位置；
3. 设置 css属性，例如：z-index，postion，top，width等；css属性参考文档：http://css.doyoe.com/；
4. 如果以上步骤未解决问题，可以联系小游戏运营人员反馈。

视频广告展示时会跳转到其他页面

解决方法：

需要改动触发展示的事件为click。

插屏/视频广告加载成功但未展现

解决方法：

create方法后无法直接调用show方法，需要在触发展现广告前创建广告

错误例子：

var ad = opUnion.createInterstitialAd({
    ...
});
ad.show(); // 错误，create之后直接调用show

正确例子

var ad = opUnion.createInterstitialAd({
    ...
});
xx.onclick = function () {
    ad.show(); // 正确，在调用show之前已经create
};

Banner广告距离底部有一段距离

解决方法：

设置渲染Banner的DOM节点样式的fontSize为0。

插屏广告反复出现关闭后弹出现象

解决方法：

需要检查代码逻辑，插屏广告在关闭后会自动加载广告。

Banner广告如何控制显示/隐藏

解决方法：

可以通过控制展示广告的DOM元素的样式控制，如控制DOM的 display 为 block/none 显示隐藏。