请选择 进入手机版 | 继续访问电脑版
 找回密码
 立即注册
搜索

技术分享 快应用接入广告开发指引

1
回复
146
查看
[复制链接]

11

主题

87

帖子

795

积分

 楼主| 2021-3-31 16:59:02 显示全部楼层 |阅读模式

厂商支持

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

厂商最低支持引擎版本说明
vivo1052+激励视频广告1061+ vivo 流量联盟平台
OPPO1044+激励视频广告1060+ OPPO 营销平台
华为1075+华为广告接入服务
小米1062+暂不支持原生广告 小米移动广告联盟

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

广告类型

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

类型接口说明效果示例
banner广告Promise ad.createBannerAd(object)样式部分自定义,可控制广告的位置和宽高
插屏广告Promise ad.createInterstitialAd(object)样式完全不可自定义
原生广告Promise ad.createNativeAd(object)样式自定义程度最高的广告,返回广告物料自行渲染
激励视频广告Promise ad.createRewardedVideoAd(object)样式完全不可自定义

接口开发

接口声明

{"name":"service.ad"}


导入模块

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


接口详情

ad.getProvider()

获取服务提供商。

ad.createBannerAd(object)

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

object参数说明
参数类型是否必填说明
adUnitIdstringbanner 广告位标识
styleobjectbanner 广告组件的样式

style参数说明

属性类型是否必填说明
leftnumberbanner 广告组件的左上角横坐标
topnumberbanner 广告组件的左上角纵坐标
widthnumberbanner 广告组件的宽度
heightnumberbanner 广告组件的高度
返回值

返回一个 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.show()-加载展示banner广告,出错的时候回调 onError,分为加载和展示两个阶段,加载成功回调onLoad
bannerAd.hide()-隐藏 banner 广告
bannerAd.onError()function callback监听 banner 广告错误事件
bannerAd.offError()function callback移除 banner 广告错误监听
bannerAd.onLoad()function callback监听 banner 广告加载事件,多个素材,每次加载新素材,都会进入这个回调
bannerAd.offLoad()function callback移除 banner 广告展示监听
bannerAd.onClose()function callback监听 banner 广告关闭事件
bannerAd.offClose()function callback移除 banner 广告关闭事件
bannerAd.onResize()function callback监听 banner 广告尺寸变化事件
bannerAd.offResize()function callback取消监听 banner 广告尺寸变化事件
bannerAd.destroy()-销毁 banner 广告

插屏广告

ad.createInterstitialAd(object)

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

object参数说明
参数类型是否必填说明
adUnitIdstring插屏广告位标识
返回值

返回一个 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对象
方法参数描述
interstitialAd.show()-插屏广告组件默认是隐藏的,调用 show 方法展示广告。
interstitialAd.hide()-隐藏插屏广告
interstitialAd.onError()function callback监听插屏广告出错事件
interstitialAd.offError()function callback移除插屏广告出错监听
interstitialAd.onLoad()function callback监听插屏广告加载成功事件
interstitialAd.offLoad()function callback移除插屏广告加载成功监听
interstitialAd.onClose()function callback监听插屏广告隐藏事件
interstitialAd.offClose()function callback移除插屏广告隐藏监听
interstitialAd.destroy()-销毁插屏广告

原生广告

ad.createNativeAd(object)

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

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

object参数说明
参数类型是否必填说明
adUnitIdstring原生广告位标识
返回值

返回一个 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对象
方法参数描述
nativeAd.load()-拉取广告数据,成功回调 onLoad,失败回调 onError
nativeAd.reportAdShow(){addId: ''}上报广告曝光,一个广告只有一次上报有效,adId 为 load 方法获取的广告数据的 adId 字段
nativeAd.reportAdClick(){addId: ''}上报广告点击,一个广告只有一次上报有效,adId 为 load 方法获取的广告数据的 adId 字段
nativeAd.onError()function callback监听原生广告错误事件
nativeAd.offError()function callback移除原生广告错误监听
nativeAd.onLoad()function callback设置广告加载成功回调
nativeAd.offLoad()function callback移除原生广告加载成功监听
nativeAd.destroy()-销毁原生广告

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

参数类型说明
adIdstring广告标识,用来上报曝光与点击
titlestring广告标题
descstring广告描述
iconstring推广应用的Icon图标
imgUrlListArray< string >广告图片
logoUrlstring“广告”标签图片
clickBtnTxtstring点击按钮文本描述
creativeTypenumber获取广告类型,取值说明:0:无 1:纯文字 2:图片 3:图文混合 4:视频
interactionTypenumber获取广告点击之后的交互类型,取值说明: 0:无 1:浏览类 2:下载类 3:浏览器(下载中间页广告) 4:打开应用首页 5:打开应用详情页

激励视频广告

ad.createRewardedVideoAd(object)

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

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

object参数说明
参数类型是否必填说明
adUnitIdstring激励视频广告位标识
返回值

返回一个 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对象
方法参数描述
rewardedVideoAd.show()-激励视频广告组件默认是隐藏的,调用 show 方法展示广告,失败回调 onError
rewardedVideoAd.load()-手动拉取广告,用于刷新广告,成功回调 resolved Promise,失败回调 onError
rewardedVideoAd.onError()function callback监听激励视频广告出错事件
rewardedVideoAd.offError()function callback移除激励视频广告出错监听
rewardedVideoAd.onLoad()function callback监听激励视频广告加载成功事件
rewardedVideoAd.offLoad()function callback移除激励视频广告加载监听
rewardedVideoAd.onClose()function callback监听激励视频广告关闭事件。只有在用户主动关闭激励视频广告时,广告才会关闭。
rewardedVideoAd.offClose()function callback移除激励视频广告关闭监听
rewardedVideoAd.destroy()-销毁激励视频广告组件

Tips:

  • 开发者不可控制视频广告的关闭,只有用户主动点击关闭按钮才会关闭广告;

  • 每条广告只能播放一次,播放完成后即失效,需要调用 rewardedVideoAd.load()加载新广告才能继续播放

错误码

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

代码异常情况
1000后端错误,调用失败
1001参数错误
1002广告单元无效
1003内部错误
1004无合适的广告
1005广告组件审核中
1006广告组件被驳回
1007广告能力被封禁
1008广告位的广告能力已关闭
1009广告加载超时
1100过于频繁调用相关的API
1101广告在加载后,长时间没有展示,广告信息已过期
1102调用了不支持的方法
1103环境监测失败,如应用无权限等
1104网络错误
1105广告未加载成功
1106广告展示失败
2000未知错误

其他资源

技术弟微信

完整sample代码

点击在快应用IDE中查看


回复

使用道具 举报

11

主题

87

帖子

795

积分

 楼主| 2021-4-14 15:34:52 显示全部楼层
回复

使用道具 举报

您需要登录后才可以回帖 登录 | 立即注册