静轩之别苑

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

快应用 Apr 1, 2021

开发者可以调用 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 广告关闭')
})

广告示例效果

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>

广告示例效果

原生广告

您可能感兴趣的文章

Tags

nicejade

轩帅，字琼璞，逍遥自在轩城主，晚晴幽草轩轩主，静轩之别苑阁主，悠然宜想亭主持。

Recommended for you

Great! You've successfully subscribed.
Great! Next, complete checkout for full access.
Welcome back! You've successfully signed in.
Success! Your account is fully activated, you now have access to all content.