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

厂商支持

快应用联盟支持广告接口的厂商，当前一共有四家，如果你的快应用确定在下面的厂商上架，则可以接入广告，为你带来收益。

接入广告接口时，调试测试接口需要在调试器中选择这几家厂商引擎平台（例如 vivo 需要选择 com.vivo.hybrid 平台），预览版是不支持广告接口的。

广告类型

快应用目前支持四种类型的广告，你可以根据业务需求选择接入。

接口开发

接口声明

{ "name": "service.ad" }

导入模块

import ad from '@service.ad' 或 const ad = require('@service.ad')

接口详情

ad.getProvider()

获取服务提供商。

banner 广告

ad.createBannerAd(object)

创建 banner 广告组件，如果已经创建过 banner 广告组件，则返回已创建的广告组件

object 参数说明

style 参数说明

返回值

返回一个 BannerAd 对象，通过 BannerAd 可加载及展现广告。

代码示例

<template>
  <div class="wrap">
    <text class="btn" onclick="showAd">点击显示广告</div>
  </div>
</template>
<script>
  import device from "@system.device";
  export default {
    data() {
      return {
        adUnitId: "",
        ad: null
      };
    },
    onInit() {
      this.switchAdUnitIdByBrand();
    },
    async switchAdUnitIdByBrand() {
      // 这个方法的作用是适配不同厂商的adUnitId
      const res = await device.getInfo();
      const brand = res.data.brand;
      switch (brand) {
        case "vivo":
          this.adUnitId = "278eae7418b04abbb5926847ed42271e"; // 这个id是vivo的com.quickapp.center创建的，需要修改manifest的package才能预览出效果
          break;
        case "oppo":
          this.adUnitId = "oppo-adUnitId";
          break;
        case "xiaomi":
          this.adUnitId = "xiaomi-adUnitId";
          break;
        case "huawei":
          this.adUnitId = "huawei-adUnitId";
          break;
        default:
          console.warn("此设备不支持广告组件！");
      }
    },
    initAd() {
      try {
        this.ad = require('@service.ad').createBannerAd({  // 使用require方式避免在不支持的广告接口的厂商运行是报错
          adUnitId: this.adUnitId,
          style:{
            left: 0,
            top: 800,
            width: 1080
          }
        })
      } catch (e) {
        console.log(e)
      }
    },
    showAd() {
      if(this.ad) {
        this.ad.show();
      } else {
        this.initAd();
      }
    }
  };
</script>
<style lang="less">
  .wrap {
    background-color: #cccccc;
    flex-direction: column;
    .btn {
      height: 50px;
      width: 200px;
      border-radius: 25px;
      color: #FFFFFF;
      background-color: #456fff;
      text-align: center;
    }
  }
</style>

bannerAd 对象

插屏广告

ad.createInterstitialAd(object)

创建插屏广告组件，同一个 adUnitId，如果已经创建，并且未 destroy，会复用之前的对象，创建后会加载广告素材，素材创建后会自动拉取

object 参数说明

返回值

返回一个 InterstitialAd 对象，通过 InterstitialAd 可加载及展现广告。

代码示例

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

interstitialAd 对象

原生广告

ad.createNativeAd(object)

创建原生广告组件，如果已经创建过原生广告组件，则返回已创建的广告组件。

如果你想快速接入原生广告，可以使用现有的apex-ui组件库中封装好的 ad 组件完成，

object 参数说明

返回值

返回一个 nativeAd 对象，通过 nativeAd 可获取到广告的素材资源，自行设置渲染加载样式及展现广告。

代码示例

<script>
  import device from '@system.device'
  export default {
    data() {
      return {
        adUnitId: '9d66217c88614253bd68a291c273f8d5', // 这个id是vivo的com.quickapp.center创建的，需要修改manifest的package才能预览出效果
        ad: null
      }
    },
    onInit() {
      this.initAd()
    },
    initAd() {
      try {
        this.ad = require('@service.ad').createNativeAd({
          // 使用require方式避免在不支持的广告接口的厂商运行是报错
          adUnitId: this.adUnitId
        })
        this.ad.onLoad(data => {
          console.log('Native ad resources!', data) // 广告加载成功，返回原生广告资源，根据但是资源自行渲染展现
        })
        this.ad.load()
      } catch (e) {
        console.log(e)
      }
    }
  }
</script>

nativeAd 对象

onLoad 方法监听到返回的广告数据 adList 是一个 Array 对象，其中 item 数据格式为：

激励视频广告

ad.createRewardedVideoAd(object)

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

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

object 参数说明

返回值

返回一个 rewardedVideoAd 对象，通过 rewardedVideoAd 可加载及展现广告。

代码示例

<script>
  import device from '@system.device'
  export default {
    data() {
      return {
        adUnitId: '236d05c1e2564e85bf289f63c1e42c29', // 这个id是vivo的com.quickapp.center创建的，需要修改manifest的package才能预览出效果
        ad: null
      }
    },
    onInit() {
      this.initAd()
    },
    initAd() {
      try {
        this.ad = require('@service.ad').createRewardedVideoAd({
          // 使用require方式避免在不支持的广告接口的厂商运行是报错
          adUnitId: this.adUnitId
        })
        this.ad.onLoad(() => {
          this.ad.show()
        })
        this.ad.onClose(res => {
          if (res && res.isEnded) {
            console.log('正常播放结束，可以下发奖励')
          } else {
            console.log('播放中途退出，不下发奖励')
          }
        })
        this.ad.load()
      } catch (e) {
        console.log(e)
      }
    }
  }
</script>

rewardedVideoAd 对象

Tips:

• 开发者不可控制视频广告的关闭，只有用户主动点击关闭按钮才会关闭广告；
• 每条广告只能播放一次，播放完成后即失效，需要调用 rewardedVideoAd.load()加载新广告才能继续播放

错误码

由于错误码基于厂商的广告 SDK 进行了封装和映射，所以不同厂商可能存在同一错误码，实际原因不明的情况，遇到这种情况，请联系对应厂商的技术人员解决。

Q&A

Q1、原生广告 nativeAd.reportAdClick()方法无响应，怎么办？

A：调用 nativeAd.reportAdClick()前，需要确保广告逻辑先调用 nativeAd.reportAdShow()方法，否则无法响应点击跳转。

Q2、原生广告的返回物料问题

A：vivo 的原生广告返回的物料 adlist 只有一项，可以使用返回的数据列表中的第一项作为物料，进行渲染。

Q3、刚从联盟申请到广告位 poiId，一直提示“no ad”错误，怎么办？

A：刚申请的广告位，可能由于填充率等，会出现暂时的没有广告等问题，可以多请求几次广告，或者申请到广告位后，第二天再执行测试。如果多次尝试还有此问题，可联系厂商技术人员寻求帮助。

其他资源

技术弟微信

完整 sample 代码

点击在快应用 IDE 中查看

您可能感兴趣的文章

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