快应用广告开发指南

dadong -

开发者可以调用 ad.createBannerAd 创建Banner广告组件。

广告创建

Banner广告组件默认是隐藏的，因此可以提前创建，以提前初始化组件。开发者可以在快应用页面的 onInit 事件回调中创建广告实例，并在该页面的生命周期内重复调用该广告实例。

export default {
  data() {
    return {
      adUnitId: "278eae7418b04abbb5926847ed42271e", // 这个id是vivo的com.quickapp.center创建的，需要修改manifest的package才能预览出效果
      bannerAd: null
    };
  },
  onInit() {
		this.initAd();
  },
  initAd() {
    try {
      this.bannerAd = require('@service.ad').createBannerAd({  // 使用require方式避免在不支持广告接口的厂商运行时报错
        adUnitId: this.adUnitId
      })
      this.bannerAd.onLoad(() => { // 监听广告加载
        console.log('onLoad event emit')
        this.bannerAd.show()
      })
      this.bannerAd.onError((err) => { // 监听广告出错
        console.log('onError event emit', err)
      })
      this.bannerAd.onClose((res) => { // 监听广告关闭
        console.log('onClose event emit', res)
      })
    } catch (e) {
      console.log(e)
    }
  }
};

广告尺寸设置

Banner广告通过在 ad.createBannerAd 参数中增加style属性来控制创建的广告尺寸和位置。

const bannerAd = require('@service.ad').createBannerAd({
  adUnitId: this.adUnitId,
  style: {
    left: 0, // banner 广告组件的左上角横坐标
    top: 800, // banner 广告组件的左上角纵坐标
    width: 1080, // banner 广告组件的宽度
    Height: 300 // banner 广告组件的高度
  }
})

如果不传入style属性，广告默认在页面底部居中展示。

显示/隐藏

Banner广告组件默认是隐藏的，开发者需要调用 BannerAd.show() 进行显示。如果广告拉取失败或触发频率限制，BannerAd.show() 方法会返回一个rejected Promise，开发者可自行监听错误信息。

bannerAd.show().catch((err) => {
  console.error(err)
})

用户可以主动关闭Banner广告。开发者也可以通过 BannerAd.hide() 控制Banner广告组件的隐藏, BannerAd.hide()方法会返回一个Promise告知banner广告隐藏操作的结果。

bannerAd.hide();

广告拉取成功与失败

Banner广告组件是自动拉取广告并进行更新的。

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

bannerAd.onLoad(() => {
  console.log('onLoad event emit')
})

如果拉取失败，通过 BannerAd.onError() 注册的回调函数会执行，回调函数的参数是一个包含错误信息的对象。常见异常错误参考文档

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

监听用户关闭广告

如果广告被关闭，通过 BannerAd.onClose() 注册的回调函数会执行，回调函数没有参数传递。

bannerAd.onClose(res => {
    console.log('Banner 广告关闭')
})

广告示例效果

插屏广告

插屏广告组件是由客户端原生的图片、文本、视频控件组成的，层级最高，会覆盖在普通组件上。

开发者可以调用 ad.createInterstitialAd 创建插屏广告组件。

广告创建

插屏广告组件默认是隐藏的，因此可以提前创建，以提前初始化组件。开发者可以在快应用页面的 onInit 事件回调中创建广告实例，并在该页面的生命周期内重复调用该广告实例。

export default {
  data() {
    return {
      adUnitId: "fc7c15870c7740da94d88c650c939be4", // 这个id是vivo的com.quickapp.center创建的，需要修改manifest的package才能预览出效果
      interstitialAd: null
    };
  },
  onInit() {
		this.initAd();
  },
  initAd() {
    try {
      this.interstitialAd = require('@service.ad').createBannerAd({  // 使用require方式避免在不支持广告接口的厂商运行时报错
        adUnitId: this.adUnitId
      })
      this.interstitialAd.onLoad(() => { // 监听广告加载
        console.log('onLoad event emit')
        this.interstitialAd.show()
      })
      this.interstitialAd.onError((err) => { // 监听广告出错
        console.log('onError event emit', err)
      })
      this.interstitialAd.onClose((res) => { // 监听广告关闭
        console.log('onClose event emit', res)
      })
    } catch (e) {
      console.log(e)
    }
  }
};

显示/隐藏

插屏广告组件默认是隐藏的，开发者需要调用 InterstitialAd.show() 进行显示。如果广告拉取失败或触发频率限制，InterstitialAd.show() 方法会返回一个rejected Promise，开发者可自行监听错误信息。

interstitialAd.show().catch((err) => {
  console.error(err)
})

用户可以主动关闭插屏广告。开发者不可控制插屏广告组件的隐藏。

广告拉取成功与失败

插屏广告组件是自动拉取广告并进行更新的。

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

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

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

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

监听用户关闭广告

如果广告被关闭，通过 InterstitialAd.onClose() 注册的回调函数会执行，回调函数没有参数传递。

interstitialAd.onClose(res => {
    console.log('插屏 广告关闭')
})

用户关闭广告后，开发者可以调用 InterstitialAd.show()来重新展示广告，同时会触发组件重新拉取广告且不再触发onLoad事件。

广告示例效果

激励视频广告

激励视频广告组件是由客户端原生的图片、文本、视频控件组成的，层级最高，会覆盖在普通组件上。创建后返回的是一个单例，该实例仅对当前页面有效，不允许跨页面使用。

开发者可以调用 ad.createRewardedVideoAd 创建激励视频广告组件，同一个 adUnitId，如果已经创建，会复用之前的对象，创建后会加载广告素材

广告创建

激励视频广告组件默认是隐藏的，因此可以提前创建，以提前初始化组件。开发者可以在快应用页面的 onInit 事件回调中创建广告实例，并在该页面的生命周期内重复调用该广告实例。

export default {
  data() {
    return {
      adUnitId: "236d05c1e2564e85bf289f63c1e42c29", // 这个id是vivo的com.quickapp.center创建的，需要修改manifest的package才能预览出效果
      rewardedVideoAd: null
    };
  },
  onInit() {
		this.initAd();
  },
  initAd() {
    try {
      this.rewardedVideoAd = require('@service.ad').createRewardedVideoAd({  // 使用require方式避免在不支持广告接口的厂商运行时报错
        adUnitId: this.adUnitId
      })
      this.rewardedVideoAd.onLoad(() => { // 监听广告加载
        console.log('onLoad event emit')
        this.rewardedVideoAd.show()
      })
      this.rewardedVideoAd.onError((err) => { // 监听广告出错
        console.log('onError event emit', err)
      })
      this.rewardedVideoAd.onClose((res) => { // 监听广告关闭
        console.log('onClose event emit', res)
      })
      this.rewardedVideoAd.load()
    } catch (e) {
      console.log(e)
    }
  }
};

显示/隐藏

激励视频广告组件默认是隐藏的，在用户主动触发广告后，开发者需要调用 RewardedVideoAd.show() 进行显示。

rewardedVideoAd.show();

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

广告拉取成功与失败

激励视频广告组件是自动拉取广告并进行更新的。在组件创建后会拉取一次广告，用户点击 关闭广告 后，如果需要重新播放广告开发者需要手动调用 RewardedVideoAd.load() 去拉取下一条广告。

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

rewardedVideoAd.onLoad(() => {
  console.log('激励视频 广告加载成功')
})

rewardedVideoAd.show()
.then(() => console.log('激励视频 广告显示'))

如果拉取失败，通过 RewardedVideoAd.onError() 注册的回调函数会执行，回调函数的参数是一个包含错误信息的对象。常见异常错误参考文档。

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

RewardedVideoAd.show() 返回的 Promise 也会是一个 rejected Promise。

rewardedVideoAd.show().catch(err => console.log(err))

拉取失败，重新拉取

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

rewardedVideoAd.show()
.catch(() => {
    rewardedVideoAd.load()
    .then(() => rewardedVideoAd.show())
    .catch(err => {
      console.log('激励视频 广告显示失败')
    })
})

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

rewardedVideoAd.load()
.then(() => rewardedVideoAd.show())

监听用户关闭广告

只有在用户主动关闭激励视频广告时，广告才会关闭。开发者可以通过RewardedVideoAd.onClose()来监听这个事件。

RewardedVideoAd.onClose() 的回调函数会传入一个参数 res，res.isEnded 描述广告被关闭时的状态。

属性 类型 说明
isEnded boolean 视频是否是在用户完整观看的情况下被关闭的，true 表示用户是在视频播放完以后关闭的视频，false 表示用户在视频播放过程中关闭了视频

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

rewardedVideoAd.onClose(res => {
    // 用户点击了【关闭广告】按钮
    if (res && res.isEnded) {
      // 正常播放结束，可以下发游戏奖励
    } else {
      // 播放中途退出，不下发游戏奖励
    }
})

广告示例效果

原生广告

这里推荐使用APEX-UI封装好的ad组件。

原生广告是自定义程度最高了一种广告，创建加载完成后，会返回广告对应的物料信息，开发者可以根据返回的物料自行决定渲染的样式。

开发者可以调用 ad.createNativeAd 创建原生广告组件，同一个 adUnitId，如果已经创建，会复用之前的对象，创建后会需要手动调用NativeAd.load()方法加载广告，可以在NativeAd.onLoad()的回调方法中获取到拉取到的广告物料。

广告创建

调用 ad.createNativeAd 创建原生广告组件，如果已经创建过原生广告组件，则返回已创建的广告组件

export default {
  data() {
    return {
      adUnitId: "9d66217c88614253bd68a291c273f8d5", // 这个id是vivo的com.quickapp.center创建的，需要修改manifest的package才能预览出效果
      nativeAd: null
    };
  },
  onInit() {
		this.initAd();
  },
  initAd() {
    try {
      this.nativeAd = require('@service.ad').createNativeAdAd({  // 使用require方式避免在不支持广告接口的厂商运行时报错
        adUnitId: this.adUnitId
      })
    } catch (e) {
      console.log(e)
    }
  }
};

获取广告物料

创建原生广告组建后，需要手动调用NativeAd.load()方法加载广告，可以在NativeAd.onLoad()的回调方法中获取到拉取到的广告物料。

NativeAd.onLoad()的回调函数会传入一个参数 res，res.adList 包含了所有广告物料信息。

参数 类型 是否必填 说明
adList Array 是 广告详细信息

adList 是一个 Array 对象，其中 item 数据格式为：

参数 类型 说明
adId string 广告标识，用来上报曝光与点击
title string 广告标题
desc string 广告描述
icon string 推广应用的Icon图标
imgUrlList Array< string > 广告图片
logoUrl string “广告”标签图片
clickBtnTxt string 点击按钮文本描述
creativeType number 获取广告类型，取值说明：0：无 1：纯文字 2：图片 3：图文混合 4：视频
interactionType number 获取广告点击之后的交互类型，取值说明： 0：无 1：浏览类 2：下载类 3：浏览器（下载中间页广告） 4：打开应用首页 5：打开应用详情页 
export default {
  data() {
    return {
      adUnitId: "9d66217c88614253bd68a291c273f8d5", // 这个id是vivo的com.quickapp.center创建的，需要修改manifest的package才能预览出效果
      nativeAd: null,
      adList: [] // 广告物料数据
    };
  },
  onInit() {
		this.initAd();
  },
  initAd() {
    try {
      this.nativeAd = require('@service.ad').createNativeAdAd({  // 使用require方式避免在不支持广告接口的厂商运行时报错
        adUnitId: this.adUnitId
      })
      this.nativeAd.onLoad((res) => { // 监听广告加载
        console.log('onLoad event emit', res)
        this.adList = res.adList
      })
      this.nativeAd.load() // 加载获取广告
    } catch (e) {
      console.log(e)
    }
  }
};

广告显示和点击

获取到广告物料后，在自行渲染后，需要先调用NativeAd.reportAdShow()上报广告曝光，否则NativeAd.reportAdClick()方法不会生效。

NativeAd.reportAdShow()和NativeAd.reportAdClick()方法参数一致，都是adId，这个数值可以在获取到的广告物料中拿到。

参数 类型 是否必填 说明
adId string 是 广告信息标识，由 load 接口返回 
<template>
	<div class="ad">
    <image onclick="reportAdClick(adList[0].adId)" oncomplete="reportAdShow(adList[0].adId)" src="{{adList[0].imgUrlList[0]}}"></image>
  </div>
</template>
<script>
	export default {
    data() {
      return {
        adUnitId: "9d66217c88614253bd68a291c273f8d5", // 这个id是vivo的com.quickapp.center创建的，需要修改manifest的package才能预览出效果
        nativeAd: null,
        adList: []
      };
    },
    onInit() {
      this.initAd();
    },
    initAd() {
      try {
        this.nativeAd = require('@service.ad').createNativeAdAd({  // 使用require方式避免在不支持广告接口的厂商运行时报错
          adUnitId: this.adUnitId
        })
        this.nativeAd.onLoad((res) => { // 监听广告加载
          console.log('onLoad event emit', res)
          this.adList = res.adList
        })
        this.nativeAd.load()
      } catch (e) {
        console.log(e)
      }
    },
    reportAdClick(adId) {
      this.ad.reportAdClick({ adId })
    },
    reportAdShow(adId) {
      this.ad.reportAdShow({ adId })
    }
  }
</script>

广告示例效果