广告

接口声明

在manifest.json文件的 features属性中增加如下配置。

{"name": "service.ad"}

导入模块

在调用接口页面的<script>部分增加如下配置。

import ad from '@service.ad'

或

var ad = require("@service.ad")

使用限制

接口定义

[h2]ad.getProvider()（1075+）

描述

获取服务提供商，如厂商的英文品牌名称。

返回值

字符串，服务提供商的代号，如厂商的英文品牌名称，如果无此服务则返回空字符串。返回空字符串时，请勿调用该服务其他接口，否则将抛出异常。

示例代码

ad.getProvider();

[h2]ad.requestConsentUpdate(object)（1077+）

描述

请求用户意见更新状态。

参数

success回调参数

AdProvider说明

示例代码

ad.requestConsentUpdate({
  success: function(data) {
    console.log('requestConsentUpdate success data ' + JSON.stringify(data))
  },
  fail: function(data) {
    console.log('requestConsentUpdate fail data ' + JSON.stringify(data))
  },
  complete: function() {},
})

[h2]ad.setUnderAgeOfPromise(boolean underAgeOfPromise)（1077+）

描述

设置未达到法定承诺年龄用户的标记。

参数

示例代码

ad.setUnderAgeOfPromise(true)

[h2]ad.setConsentStatus(number consentStatus)（1077+）

描述

设置用户意见。

参数

示例代码

ad.setConsentStatus(1)

[h2]ad.setTagForChildProtection(number childProtection) (1078+)

描述

设置儿童保护标签。

参数

示例代码

ad.setTagForChildProtection(1)

[h2]ad.setTagForUnderAgeOfPromise(number underAgeOfPromiseStr) (1078+)

描述

设置面向未达到法定承诺年龄用户。

参数

示例代码

ad.setTagForUnderAgeOfPromise(1)

[h2]ad.setAdContentClassification(string adContentClassification) (1078+)

描述

设置广告内容分级上限。

参数

示例代码

ad.setAdContentClassification('W')

[h2]ad.setNonPersonalizedAd(number personalizedAd) (1078+)

描述

设置是否请求非个性化广告。

参数

示例代码

ad.setNonPersonalizedAd(1)

[h2]ad.createNativeAd(object)（1075+）

描述

创建 native 广告，如果已经创建过 native 广告，则返回已创建的广告。

参数

返回值

原生广告。

示例代码

let nativeAd = ad.createNativeAd({ 
   adUnitId: 'xxx',
   channel:'xxx'
})

[h2]nativeAd.load()（1075+）

描述

拉取广告数据，成功回调 onLoad，失败回调 onError。

华为目前每次调用返回一条广告数据。

参数

为保证版本兼容，请判断当前引擎版本号，低于1111版本时请使用不带参数方法请求。

nativeAd.load({
  supportTemplate:true,
  extra:{
    // adUnitId
    "testy63txaom86":
    {
      "key1":"value1",
      "key2":"value2",
      "customerChannel":24
    }
  }
})

[h2]nativeAd.reportAdShow()（1075+）

描述

上报广告曝光，一个广告只有一次上报有效，adId 为 load 方法获取的广告数据的 adId 字段。

参数

示例代码

nativeAd.reportAdShow({
    adId: "xxx"
})

[h2]nativeAd.reportAdClick()（1075+）

描述

上报广告点击，一个广告只有一次上报有效，adId 为 load 方法获取的广告数据的 adId 字段。

参数

clickInfo说明

creativeSize说明（1106+）

示例代码

nativeAd.reportAdClick({ adId: "xxx",
      clickInfo: {
          clickX:750,
          clickY:200,
          upX:740,
          upY:202,
          sld:0,
          density:3.0,
          creativeSize:{
            width:1500,
            height:750
          }
      }
})

[h2]nativeAd.showAppDetailPage()（1106+）

描述

跳转应用详情页，adId 为 load 方法获取的广告数据的 adId 字段。

参数

示例代码

nativeAd.showAppDetailPage({ adId: "xxx" })

[h2]nativeAd.onRewardActive(function callback)（1106+）

描述

监听原生广告激励产生事件，仅AGD类广告返回。

参数

示例代码

nativeAd.onRewardActive((data) => {
    console.log('onRewardActive data = ', data)
})

[h2]nativeAd.offRewardActive()（1106+）

描述

移除原生广告激励产生监听。

示例代码

nativeAd.offRewardActive()

[h2]nativeAd.onLoad(function callback)（1075+）

描述

设置广告加载成功回调。

参数

广告item说明

示例代码

nativeAd.onLoad((data) => {
 console.info('ad data loaded: ' + JSON.stringify(data))
 this.adItemData = data.adList[0]
})

[h2]nativeAd.offLoad(function callback)（1075+）

描述

移除原生广告加载成功监听。

参数

[h2]nativeAd.onError(function callback)（1075+）

描述

监听原生广告错误事件。

参数

callback回调对象

错误码说明：

示例代码

nativeAd.onError((e) => {
  console.error('load ad error:' + JSON.stringify(e));
  const errCode = e.errCode
  const errMsg = e.errMsg
})

[h2]nativeAd.offError(function callback)（1075+）

描述

移除原生广告加载错误监听。

参数

[h2]nativeAd.setTagForChildProtection(number childProtection)（1077+）

描述

设置儿童保护标签。建议使用 ad.setTagForChildProtection(number childProtection) 代替此接口。

参数

示例代码

nativeAd.setTagForChildProtection(1)

[h2]nativeAd.setTagForUnderAgeOfPromise(number underAgeOfPromiseStr)（1077+）

描述

设置面向未达到法定承诺年龄用户。建议使用 ad.setTagForUnderAgeOfPromise(number underAgeOfPromiseStr) 代替此接口。

参数

示例代码

nativeAd.setTagForUnderAgeOfPromise(1)

[h2]nativeAd.setAdContentClassification(string adContentClassification)（1077+）

描述

设置广告内容分级上限。建议使用 ad.setAdContentClassification(string adContentClassification) 代替此接口。

参数

示例代码

nativeAd.setAdContentClassification('W')

[h2]nativeAd.setNonPersonalizedAd(number personalizedAd)（1077+）

描述

设置是否请求非个性化广告。建议使用 ad.setNonPersonalizedAd(number personalizedAd) 代替此接口。

参数

示例代码

nativeAd.setNonPersonalizedAd(1)

[h2]nativeAd.getDownloadProgress(OBJECT) (1078+)

描述

获取下载进度。

参数

返回值

应用下载进度，Number类型，取值范围：0 ~ 100。

示例代码

const progress = nativeAd.getDownloadProgress({
    adId: "xxx"
})
console.log('getDownloadProgress progress = ' + progress);

[h2]nativeAd.getAppStatus(OBJECT) (1078+)

描述

获取下载状态。

参数

返回值

应用下载状态，string类型，数值含义如下。

示例代码

const status = nativeAd.getAppStatus({
    adId: "xxx"
})
console.log('getAppStatus status = ' + status );

[h2]nativeAd.onStatusChanged(function) (1078+)

描述

监听下载状态变化。

请在广告加载接口nativeAd.onLoad中调用，否则无法监听到下载状态。

参数

示例代码

nativeAd.onStatusChanged((data) => {
    console.log('onStatusChanged data = ', data)
})

[h2]nativeAd.offStatusChanged() (1078+)

描述

取消监听下载状态变化。

示例代码

nativeAd.offStatusChanged()

[h2]nativeAd.onDownloadProgress(function) (1078+)

描述

监听下载进度变化。

请在广告加载接口nativeAd.onLoad中调用，否则无法监听到下载进度。

参数

示例代码

nativeAd.onDownloadProgress((data) => {
    console.log('onDownloadProgress data = ', data)
})

[h2]nativeAd.offDownloadProgress() (1078+)

描述

取消监听下载进度变化。

示例代码

nativeAd.offDownloadProgress()

[h2]nativeAd.destroy()（1075+）

描述

销毁原生广告。

[h2]ad.createRewardedVideoAd(object)（1075+）

描述

创建激励视频广告，同一个 adUnitId，如果已经创建，会复用之前的对象，创建后会加载广告素材，该方法返回的是一个单例，该实例仅对当前页面有效，不允许跨页面使用。

参数

返回值

激励视频广告。

示例代码

let rewardedVideoAd = ad.createRewardedVideoAd({
    adUnitId: 'xxx'
})

[h2]rewardedVideoAd.load()（1075+）

描述

手动拉取广告，用于刷新广告，成功回调 resolved Promise，失败回调 onError。

请求广告频率太高可能回调onError。

参数

示例代码

rewardedVideoAd.load({
  extra:{
    // adUnitId
    "testx9dtjwj8hp":
    {
      "key1":"value1",
      "key2":"value2"
    }
  }
})

[h2]rewardedVideoAd.show()（1075+）

描述

激励视频广告默认是隐藏的，调用 show 方法展示广告，失败回调 onError。

[h2]rewardedVideoAd.onLoad(function callback)（1075+）

描述

设置广告加载成功回调。

参数

示例代码

rewardedVideoAd.onLoad(() => {
  console.log('ad loaded.')
})

[h2]rewardedVideoAd.offLoad(function callback)（1075+）

描述

移除激励视频广告加载成功监听。

参数

示例代码

rewardedVideoAd.offLoad(() => {
  console.log('ad off loaded.')
})

[h2]rewardedVideoAd.onClose(function callback)（1075+）

描述

监听激励视频广告关闭事件。只有在用户主动关闭激励视频广告时，广告才会关闭。

参数

示例代码

rewardedVideoAd.onClose((res) => {
  console.log('ad onClose: ' + res.isEnded)
})

[h2]rewardedVideoAd.offClose(function callback)（1075+）

描述

移除激励视频广告关闭监听。

参数

[h2]rewardedVideoAd.onError(function callback)（1075+）

描述

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

参数

callback回调对象

示例代码

rewardedVideoAd.onError((e) => {
  console.error('load ad error:' + JSON.stringify(e));
  const errCode = e.errCode
  const errMsg = e.errMsg
})

[h2]rewardedVideoAd.offError(function callback)（1075+）

描述

移除激励视频广告加载错误监听。

参数

[h2]rewardedVideoAd.setTagForChildProtection(number childProtection)（1077+）

描述

设置儿童保护标签。

参数

示例代码

rewardedVideoAd.setTagForChildProtection(1)

[h2]rewardedVideoAd.setTagForUnderAgeOfPromise(number underAgeOfPromiseStr)（1077+）

描述

设置面向未达到法定承诺年龄用户。

参数

示例代码

rewardedVideoAd.setTagForUnderAgeOfPromise(1)

[h2]rewardedVideoAd.setAdContentClassification(string adContentClassification)（1077+）

描述

设置广告内容分级上限。

参数

示例代码

rewardedVideoAd.setAdContentClassification('W')

[h2]rewardedVideoAd.setNonPersonalizedAd(number personalizedAd)（1077+）

描述

设置是否请求非个性化广告。

参数

示例代码

rewardedVideoAd.setNonPersonalizedAd(1)

[h2]rewardedVideoAd.destroy()（1075+）

描述

销毁激励视频广告。

[h2]ad.createBannerAd(OBJECT)（1078+）

描述

创建 Banner 广告，如果已经创建过 Banner 广告，则返回已创建的广告。

参数

style说明

广告宽高设置值限制如下表所示。

返回值

Banner广告 bannerAd。通过bannerAd.style可以获取广告的真实宽高，其返回值如下表所示。

示例代码

let bannerAd = ad.createBannerAd({
    adUnitId: 'testw6vs28auh3',
    style:{
        top:20,
        left:20,
        height:57,
        width:360
    }
})

[h2]bannerAd.show() （1078+）

描述

加载展示banner广告，出错的时候回调 onError，分为加载和展示两个阶段，加载成功回调onLoad。

参数

示例代码

bannerAd.show({
  extra:{
    // adUnitId
    "testw6vs28auh3":
    {
      "key1":"value1",
      "key2":"value2"
    }
  }
})

[h2]bannerAd.hide() （1078+）

描述

隐藏 banner 广告。

[h2]bannerAd.onError(function callback)（1078+）

描述

监听 banner 广告错误事件。

返回值

Object类型。

示例代码

bannerAd.onError((err)=>{
    console.log(err)
})

[h2]bannerAd.offError() （1078+）

描述

移除 banner 广告错误监听。

[h2]bannerAd.onLoad() （1078+）

描述

监听 banner 广告加载事件。

[h2]bannerAd.offLoad() （1078+）

描述

移除 banner 广告加载事件。

[h2]bannerAd.onClose() （1078+）

描述

监听 banner 广告关闭事件。

[h2]bannerAd.offClose() （1078+）

描述

移除 banner 广告关闭事件。

[h2]bannerAd.onResize() （1078+）

描述

监听 banner 广告尺寸变化事件（华为暂未实现功能）。

[h2]bannerAd.offResize() （1078+）

描述

移除 banner 广告尺寸变化事件 （华为暂未实现功能）。

[h2]bannerAd.destroy() （1078+）

描述

销毁 banner 广告。

[h2]ad.createInterstitialAd(OBJECT)（1078+）

描述

创建 Interstitial 广告，如果已经创建过 Interstitial 广告，则返回已创建的广告。

参数

示例代码

let interstitialAd = ad.createInterstitialAd({
    adUnitId: 'xxxx'
})

[h2]interstitialAd.load()（1078+）

描述

拉起插屏广告数据，成功回调 onLoad，失败回调 onError。

参数

示例代码

interstitialAd.load({
  extra:{
    // adUnitId
    "testb4znbuh3n2":
    {
      "key1":"value1",
      "key2":"value2"
    }
  }
})

[h2]interstitialAd.show()（1078+）

描述

显示插屏视频广告。

返回值

Promise，插屏广告显示操作的结果。

示例代码

interstitialAd.show().then(
    () => { console.log('插屏广告show成功') },
    () => { console.log('插屏广告show失败') }
)

[h2]interstitialAd.onLoad(function callback)（1078+）

描述

设置插屏广告加载成功回调。

示例代码

interstitialAd.onLoad(function (data) {
    console.log('onLoad data ' + JSON.stringify(data));
});

[h2]interstitialAd.offLoad()（1078+）

描述

移除插屏广告加载事件。

示例代码

interstitialAd.offLoad();

[h2]interstitialAd.onError(function callback)（1078+）

描述

监听插屏广告错误事件。

返回值

object类型。

示例代码

interstitialAd.onError((err)=>{
    console.log(err)
})

[h2]interstitialAd.offError()（1078+）

描述

移除插屏广告错误监听。

示例代码

interstitialAd.offError();

[h2]interstitialAd.onClose(function callback)（1078+）

描述

监听插屏广告关闭事件。

示例代码

interstitialAd.onClose(()=>{
    console.log('interstitialAd closed');
})

[h2]interstitialAd.offClose()（1078+）

描述

移除插屏广告关闭事件。

示例代码

interstitialAd.offClose();

[h2]interstitialAd.onClick(function callback)（1078+）

描述

监听插屏广告点击事件。

示例代码

interstitialAd.onClick(()=>{
    console.log('interstitialAd clicked');
})

[h2]interstitialAd.offClick()（1078+）

描述

移除插屏广告点击监听。

示例代码

interstitialAd.offClick();

[h2]interstitialAd.destroy() （1078+）

描述

销毁插屏广告。

示例代码

interstitialAd.destroy()

[h2]ad.createTemplateAd(OBJECT)（1101+）

描述

创建 Template 广告，如果已经创建过 Template 广告，则返回已创建的广告。

参数

广告的宽高建议值

返回值

模板广告。

示例代码

let templateAd = ad.createTemplateAd({
    adUnitId: 'xxx',
    type:'infoCard',
    channel:'xxx',
    darkMode:0,
    width:1200,
    height:800,
    personalizedAd:0
})

[h2]templateAd.load(OBJECT)（1101+）

描述

加载模板广告。

OBJECT参数

fail返回错误代码

示例代码

templateAd.load({
    success:function(data){
        console.log('load success = ' + data );
    },
     fail: function(data, code) {
        console.log("load fail, code=" + code);
    }
})

load成功后可创建ad-view组件。

[h2]templateAd.destroy()（1101+）

描述

销毁模板广告。

示例代码

templateAd.destroy()

[h2]ad.createAppBoxAd (OBJECT)（1101+）

描述

创建互推盒子广告，如果已经创建过互推盒子广告，则返回已创建的广告。

参数

示例代码

let appBoxAd = ad.createAppBoxAd({
    adUnitId: 'xxxx',
    channel:'xxx',
    darkMode: 0,
    personalize: 0
})

[h2]appBoxAd.load()（1101+）

描述

加载互推盒子广告。

示例代码

appBoxAd.load();

[h2]appBoxAd.show()（1101+）

描述

显示互推盒子广告。

示例代码

appBoxAd.show();

[h2]appBoxAd.onLoad(function callback)（1101+）

描述

监听互推盒子广告加载事件。

示例代码

appBoxAd.onLoad(()=> {
  console.log('onLoad success');
});

[h2]appBoxAd.offLoad()（1101+）

描述

移除互推盒子广告加载事件。

示例代码

appBoxAd.offLoad();

[h2]appBoxAd.onError(function callback)（1101+）

描述

监听互推盒子广告错误事件。

返回值

object类型。

示例代码

appBoxAd.onError((err)=>{
    console.log(err)
})

[h2]appBoxAd.offError()（1101+）

描述

移除互推盒子广告错误监听。

示例代码

appBoxAd.offError();

[h2]appBoxAd.onClose(function callback)（1101+）

描述

监听互推盒子广告关闭事件。

示例代码

appBoxAd.onClose(()=>{
console.log('appBoxAd closed');
})

[h2]appBoxAd.offClose()（1101+）

描述

移除互推盒子广告关闭事件。

示例代码

appBoxAd.offClose();

[h2]appBoxAd.onClick(function callback)（1101+）

描述

监听互推盒子广告点击事件。

示例代码

appBoxAd.onClick(()=>{
console.log(' appBoxAd clicked');
})

[h2]appBoxAd.offClick()（1101+）

描述

移除互推盒子广告点击监听。

示例代码

appBoxAd.offClick();

[h2]appBoxAd.destroy()（1101+）

描述

销毁互推盒子广告。

示例代码

appBoxAd.destroy()

[h2]ad.createAppBoxBannerAd (OBJECT)（1101+）

描述

创建互推盒子横划榜单广告，如果已经创建过互推盒子横划榜单广告，则返回已创建的广告。

参数

style说明

返回值

互推盒子横划榜单广告组件为bannerBoxAd，通过bannerBoxAd.style可以获取广告的真实宽高，其返回值如下表所示：

示例代码

let bannerBoxAd = ad.createAppBoxBannerAd({
        adUnitId: “CdwQHgNKip8”,
        channel:'xxx',
        darkMode: 0,
        personalizedAd: 0
        style: {
          top: 20,
          left: 200,
          width: 360,
          height: 111,
          orientation: “horizontal”
     },
})

[h2]bannerBoxAd.show()（1101+）

描述

加载并显示互推盒子横划榜单广告。

出错时回调onError，加载成功回调onLoad。

示例代码

bannerBoxAd.show();

[h2]bannerBoxAd.hide()（1101+）

描述

隐藏互推盒子横划榜单广告。

示例代码

bannerBoxAd.hide();

[h2]bannerBoxAd.onLoad(function callback)（1101+）

描述

监听互推盒子横划榜单广告加载事件。

示例代码

bannerBoxAd.onLoad(()=> {
  console.log('onLoad success');
});

[h2]bannerBoxAd.offLoad()（1101+）

描述

移除互推盒子横划榜单广告加载事件。

示例代码

bannerBoxAd.offLoad();

[h2]bannerBoxAd.onError(function callback)（1101+）

描述

监听互推盒子横划榜单广告错误事件。

返回值

object类型。

示例代码

bannerBoxAd.onError((err)=>{
    console.log(err)
})

[h2]bannerBoxAd.offError()（1101+）

描述

移除互推盒子横划榜单广告错误监听。

示例代码

appBoxAd.offError();

[h2]bannerBoxAd.onClose(function callback)（1101+）

描述

监听互推盒子横划榜单广告关闭事件。

示例代码

bannerBoxAd.onClose(()=>{
console.log('bannerBoxAd closed');
})

[h2]appBoxAd.offClose()（1101+）

描述

移除互推盒子横划榜单广告关闭事件。

示例代码

bannerBoxAd.offClose();

[h2]bannerBoxAd.onClick(function callback)（1101+）

描述

监听互推盒子横划榜单广告点击事件。

示例代码

bannerBoxAd.onClick(()=>{
console.log('bannerBoxAd clicked');
})

[h2]bannerBoxAd.offClick()（1101+）

描述

移除互推盒子横划榜单广告点击监听。

示例代码

bannerBoxAd.offClick();

[h2]bannerBoxAd.destroy()（1101+）

描述

销毁互推盒子横划榜单广告。

示例代码

bannerBoxAd.destroy()

错误码

错误码为通过onError获取的错误信息。

注意事项

提交验收前请参考如下规则对广告进行自检：

1. 请勿设置定时器循环请求广告。
2. 请勿失败后频繁重复请求广告。

   【错误做法】失败后在onError中重新请求广告。如果每次都回调onError，会进入“请求广告—>失败—>请求广告”的恶性循环。

   【推荐做法】正常情况下不管是成功还是失败都不要再次发起请求。如果业务希望请求失败后重试，只有激励视频可以再发起1次，其他类型广告都不要再次发起请求。

3. 每次请求的广告不能重复展示，展示完成后需要重新实时获取后，再次展示。

   【错误做法】在多个页面使用同一个全局的广告去展示广告。

   【推荐做法】每个页面的广告对象是独立的，需要使用createXX的方法去创建广告、注册回调等。

4. 预缓存的广告如激励视频插屏广告，请注意load和show接口调用的时间间隔，超过一个小时需重新请求新的广告来展示，否则计为无效展示，将不计费结算。
5. 激励视频调用show接口前，建议先预加载，加载失败的时候，不要显示广告入口。否则从广告入口进入后，可能因为视频数据没有加载完成，导致空白。

   【推荐做法】建议在onLoad回调中延时几秒或者几分钟调用show接口。

   

   延时时长不要超过1个小时，否则广告计为无效展示，将不计费结算。

6. 没有任何内容或不以内容为主的屏幕上应避免展示广告。
7. 广告必须有关闭按钮，特别是由开发者自行定义布局的原生广告，一定要在广告界面上设计关闭能力。
8. 广告素材必须全尺寸等比例展示。展示广告时，要保证原有的宽高比，只能等比例缩放。
9. 请勿将广告背景设置为可点区域，只允许广告的图片、标题、按钮等素材区域可以点击跳转落地页。
10. 原生广告每次点击都需要调用reportAdClick接口上报点击事件。

    【错误做法】原生广告多次点击只上报一次点击事件。

11. 原生广告每次展示都需要上报曝光事件。

    【错误做法】原生广告多次展示只上报一次曝光事件。 例如：在首次展示广告的时候调用reportAdShow接口上报，但当从其他页面返回到广告页面时，仍然显示了广告，但是没有上报曝光事件。

    【推荐做法】当页面可见时，如果还显示原生广告，需要再次上报曝光事件。一般在页面生命周期onShow中处理。

12. 点击原生广告图片区域应调用reportAdClick接口实现落地页跳转。
13. 原生广告的广告来源、广告标题、广告标识、关闭按钮、查看或者下载安装按钮，都不能有缺失。
14. 除了需要预加载的激励视频和插屏广告，其他类型广告都需要实时请求成功后再实时展示。

    【错误做法】请求了原生广告却没有展示。

15. 必须用户同意了用户隐私协议才能展示广告，不同意请勿请求和展示广告。
16. 建议优先选择test开头的测试广告位ID。

FAQ

• 如何获取自测sdk的日志？
• 如何获取广告测试id？
• 如何查看广告存在多余请求的问题？
• 如何查看广告曝光日志并处理曝光问题？
• 原生广告展示时缺少必要要素，如何处理？
• 激励视频广告播放按钮快速多次点击时，会出现多个广告覆盖播放问题，如何处理？

版本更新说明