快应用开发之广告接入指南

Banner 广告

开发者可以调用 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 描述广告被关闭时的状态。

开发者需要根据 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 对象，其中 item 数据格式为：

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，这个数值可以在获取到的广告物料中拿到。

<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>

广告示例效果

您可能感兴趣的文章

• 快应用开发之广告接入指引
• 如何高效开发高质量快应用（quickapp）？
• 2021，深入了解什么是「快应用」？
• 如何在 Windows、MacOS 上安装 adb