菜单

SDK接入常见问题

1、在多个page.ux引入sdk广告组件打包后包体变大

解决方案

在app.ux引入sdk广告组件
在page.ux直接使用组件

2、相同页面可否嵌入多个相同广告位？

不能，相同页面嵌入多个相同广告位会导致数据相互影响

若非必要场景，不建议销毁topon-ad组件
快应用生态系统中，组件销毁，将会中断组件vm方法，若在不适宜的时机销毁组件，将可能接收不到相应的回调
若是您的广告是模板渲染，销毁组件将会将广告一并销毁
若是您的广告位自渲染广告，也无销毁topon-ad组件的必要，他并不会占据空间

4、相同页面嵌入多个广告位，组件ID能否重用？

不能，相同页面的广告位组件ID需要确保唯一，否则在使用广告位组件实例时会出现异常

代码示例

<topon-ad
    id="topon-ad-TopOn广告位ID"
    placement-id="TopOn广告位ID"
    @ad-load="handleAdLoad"
    @ad-show="handleAdShow"
    @ad-close="handleAdClose"
    @ad-click="handleAdClick"
    @ad-error="handleAdError"
>
</topon-ad>

5、错误码如何分辨是SDK侧错误还是广告平台侧错误？

可以通过错误码万位来区分，1 代表SDK侧错误，2 代表广告平台侧错误

错误码示例

19004 SDK侧接口服务错误（请检查appKey、appId、placementId是否配置正确）
21009 对应广告平台侧1009错误码，广告加载超时

6、华为IDE编译时报错

可直接参考HW SDK Demo来处理华为IDE编译错误问题

根目录quickapp.config.js文件增加以下配置

module.exports = { lintOnBuild: false }

将npm包中的绝对路径替换为相对路径

找到node_modules下的@topon/quick-app-sdk-hw
找到@topon/quick-app-sdk-hw/Adapter/Baidu/**.ux目录下的文件
将各个文件中的
统一替换为

若是添加配置并替换组件后依然报错

检查是否替换成功
检查是否由于npm版本对于不同版本的npm包处理的版本管理机制引发问题: union-quick-app-ad是在项目根目录的node_modules 还是@topon/quick-app-sdk-hw包目录下的node_modules
卸载掉@topon/quick-app-sdk-hw 在重新安装
若是依然错误，请检查是否因为@topon/quick-app-sdk 包的影响，若是，则将@topon/quick-app-sdk 卸载掉

说明：华为快应用IDE中.ux文件通过绝对路径import三方库或者组件存在问题，问题已向华为开发反馈，等待华为更新IDE

参考文档：https://developer.huawei.com/consumer/cn/doc/development/quickApp-Guides/quickapp-topic-npm-0000001159156227

使用引入npm 包中的自定义组件，注意设置为组件文件的相对路径。以 npm 包为 quick-app-kit-demo 为例

<import name="comp" src="<relative path to node_modules>/node_modules/quick-app-kit-demo/src/component/index.ux"></import>

替换路径示例脚本：

/**
 * 处理华为IDE三方库绝对路径引用报错
 * 替换./node_modules/@topon/quick-app-sdk-hw/Adapter/Baidu/下引用union-quick-app-ad的路径为相对路径
 */
 const fs = require('fs')
 const reg = /src="union-quick-app-ad\/components\/mobadsAd"/gm;
 const value = 'src="../../../../../node_modules/union-quick-app-ad/components/mobadsAd"' // FIXME: 注意此处的目录层级，若替换有误，请检擦此处层级，替换后开发者需在自己开发项目中验证是否替换正确
 
 /**
  * 替换指定目录下的文件的指定内容
  * reg: 正则表达式
  * src：源文件目录
  * dest： 目标目录
  * value：替换后的值
  * @param {*} param0 
  */
 function replaceFile({ reg, src, dest, value }) {
   const source = fs.readFileSync(src, 'utf8')
   const target = source.replace(reg, value)
   fs.writeFileSync(dest, target);
 }
 
 const entrys = './node_modules/@topon/quick-app-sdk-hw/Adapter/Baidu'
 
 function run() {
   fs.readdir(entrys, (err, files) => {
     if (err) {
       return
     }
     if (files?.length) {
       files.forEach(item => {
         const path = `${entrys}/${item}`
         replaceFile({
           reg,
           src: path,
           dest: path,
           value
         })
       })
     }
   })
 }
 
 
 run()

7、oppo原生信息流广告2.0需要平台版本1112+支持

Taku集成的oppo原生信息流广告2.0基于最新API实现：https://open.oppomobile.com/new/developmentDoc/info?id=11962

如果用户设备的快应用平台版本在1112之下，则不会填充

结合目前oppo设备平台版本分布情况来看，1112+占比在95%以上

因此我们建议，在瀑布流中增加其他广告平台（目前支持Taku ADX、百度）来接收这部份流量

8、当前厂商XXX不支持XXX广告错误 OR 不支持Bid广告？

1、请确认快应用调试器是否使用了"快应用预览版", 该模式不支持广告服务，注：IDE下没有广告服务，也会报这个错误

2、请确认是否使用了正确的设备请求广告，如vivo广告仅支持在vivo设备上请求并展示，其他厂商广告同样（百度、Taku ADX、优量汇则不受设备限制）

3、竞价广告可能会有版本限制，请检查是否为最新版本的快应用调试器

4、请确保该广告类型是否支持竞价广告（ex: oppo不支持banner竞价广告）

9、在Taku后台修改了配置未生效？

1、配置生效有时间延迟，大约5到10分钟生效

2、尝试清空快应用调试器的localStorage本地缓存后再刷新 or 重新请求

10、“refuse to use this interfaces in backgroumd: service.ad”

获取广告服务便已经失败，厂商拒绝了在快应用切换至后台时使用广告接口

11、关于策略预请求（config.preload.placementStrategy）

1、在初始化阶段传入config.preload.placementStrategy配置，SDK将会在初始化阶段并行地请求广告策略配置并缓存策略数据

2、预获取配置会尽可能早的获取配置，此方式可以在进入广告页面前就去获取配置，理论上可以节约一定的时间开销（这与场景也会有关系，如由于请求是异步的，初始化SDK立刻进入广告页面时，可能预请求策略尚未完成等）

3、广告位策略预请求：指的是在进入广告页前预请求配置的广告位策略数据，这与厂商的“广告预加载”是所有区别的，不会有回调

12、关于华为原生模板广告注意事项

注意：华为原生模板广告具有一些特殊性，在使用前请首先了解华为原生模板广告的特性，以免影响您的正常使用，华为原生模板广告文档

1. 创建华为原生模板广告【creativeType为99】时，会有一定概率加载到非模板广告，这是华为侧原因
2. TopOn SDK支持原生自渲染、原生模板广告两种类型
3. 选择模板广告后，可选择渲染方式： Topon模板渲染【TopOn SDK完成渲染华为ad-template模板标签】、开发者模板渲染【开发者getAd后获取adId自行实现ad-template模板标签渲染】
4. TopOn SDK新增 renderType 【"1"：原生自渲染，"2"：原生模板 "3"：开发者自渲染】字段用以区分渲染方式
5. 原有的isSelfRendering用于区分自渲染广告和模板广告字段可正常使用
6. 当选择"模板广告"类型 + "TopOn模板自渲染"渲染方式时（isSelfRendering可区分，也可以用新的字段renderType区分，renderType: "2"），与ViVO、OPPO模板广告使用方式一致【调用show()方法渲染广告】
7. 当选择"模板广告"类型 + "TopOn模板自渲染"渲染方式时可通过<topon-ad config="{{style: styleObject}}" />传入华为ad-template支持的style样式
8. 当选择"模板广告"类型 + "开发者自渲染"渲染方式时，则必须通过renderType区分、确定如何渲染，
9. 当选择"模板广告"类型 + "开发者自渲染"渲染方式时（renderType: '3'），getAd获取到的creativeType为99，可直接用ad-template渲染，
10. 当选择"模板广告"类型 + "开发者自渲染"渲染方式时（renderType: '3'），getAd获取到的creativeType不是99，即说明不是模板广告，则不能使用ad-template渲染广告，否则无法渲染成功，应按原生自渲染实现，
11. 当选择"模板广告"类型 + "开发者自渲染"渲染方式时，需调用TopOn SDK reportShow\reportClick上报展示点击

最近修改: 2025-05-30Powered by

大纲