更新记录

1.0.5 （2026-08-17） 下载此版本

更新日志内容

• 修复激励视频等原生广告异常时的 Toast 弹窗
• 使用 Handler 切主线程展示广告，避免 CalledFromWrongThreadException
• 生成完整 JS 桥接，避免 method not found
• 支持开屏、插屏、激励、全屏、Banner、信息流六种广告类型

平台兼容性

uni-app(3.8.2)

uni-app x(3.8.2)

yunsuan-ads 使用说明

云算广告 SDK 的 UTS 插件，当前支持 Android 平台。插件已预编译，集成时无需重新编译 UTS SDK。

一、支持平台

二、环境要求

• HBuilderX 3.6.8 及以上版本
• 使用自定义基座出包（标准基座无法运行）
• 目标 Android 工程需集成插件附带的 aar / jar / res / AndroidManifest 片段

三、快速开始

3.1 引入插件

将插件目录 uni_modules/yunsuan-ads 复制到 uni-app 项目的 uni_modules/ 下。

3.2 页面调用

<template>
  <view class="container">
    <button @click="onInit">初始化 SDK</button>
    <button @click="onSplash">开屏广告</button>
    <button @click="onInterstitial">插屏广告</button>
    <button @click="onReward">激励视频</button>
    <button @click="onBanner">Banner 广告</button>
    <button @click="onNative">信息流广告</button>
  </view>
</template>

<script>
import {
  initAds,
  showSplashAd,
  showInterstitialAd,
  showRewardAd,
  showBannerAd,
  showNativeExpressAd
} from '@/uni_modules/yunsuan-ads'

export default {
  methods: {
    onInit() {
      initAds({ appId: '你的 Mercury 媒体 ID', debug: true })
    },
    onSplash() {
      showSplashAd({ adspotId: '你的开屏广告位' })
    },
    onInterstitial() {
      showInterstitialAd({ adspotId: '你的插屏广告位' })
    },
    onReward() {
      showRewardAd({ adspotId: '你的激励广告位', userId: 'u001', extra: 'ext' })
    },
    onBanner() {
      showBannerAd({ adspotId: '你的Banner广告位', position: 'bottom', height: 160 })
    },
    onNative() {
      showNativeExpressAd({ adspotId: '你的信息流广告位', position: 'bottom', height: 300 })
    }
  }
}
</script>

3.3 基座集成

插件需配合自定义基座使用。请将插件套件中的以下内容集成到 Android 基座工程：

1. android/yunsuan-ads-uts.jar → app/libs/
2. android/libs/*.aar → app/libs/
3. android/res/xml/* → app/src/main/res/xml/
4. 按 android/MANIFEST_SNIPPET.xml 合并权限与 Provider 到 AndroidManifest.xml
5. 按 android/BUILD_GRADLE_SNIPPET.txt 修改 app/build.gradle
6. 在 gradle.properties 中添加 android.overridePathCheck=true
7. 在 AndroidManifest.xml 中配置 dcloud_appkey

详细步骤请参考插件包内的 INTEGRATION_AI.md（AI 快速清单）或 INTEGRATION_MANUAL.md（手动集成文档）。

四、接口说明

initAds(options)

初始化广告 SDK。建议在应用启动后尽早调用。

initAds({
  appId: '你的 Mercury 媒体 ID',
  debug: true,
  success: (res) => console.log('init success', res),
  fail: (err) => console.error('init fail', err)
})

showSplashAd(options)

展示开屏广告。未传 adspotId 时使用默认测试 ID 10000184。

showSplashAd({
  adspotId: '你的开屏广告位',
  skipText: '跳过 %d',
  success: (res) => console.log('splash finish', res),
  fail: (err) => console.error('splash error', err)
})

showInterstitialAd(options)

展示插屏广告。未传 adspotId 时使用默认测试 ID 10000187。

showInterstitialAd({
  adspotId: '你的插屏广告位',
  success: (res) => console.log('interstitial show', res),
  fail: (err) => console.error('interstitial error', err)
})

showRewardAd(options)

展示激励视频广告。未传 adspotId 时使用默认测试 ID 10000188。

showRewardAd({
  adspotId: '你的激励广告位',
  userId: 'u001',
  extra: 'ext',
  success: (res) => console.log('reward finish', res),
  fail: (err) => console.error('reward error', err)
})

showFullScreenAd(options)

展示全屏视频广告。未传 adspotId 时使用默认测试 ID 10000187。

showFullScreenAd({
  adspotId: '你的全屏视频广告位',
  success: (res) => console.log('fullscreen finish', res),
  fail: (err) => console.error('fullscreen error', err)
})

showBannerAd(options)

展示 Banner 滚动横幅广告。

showBannerAd({
  adspotId: '你的Banner广告位',
  position: 'bottom', // top | bottom | center，默认 bottom
  height: 120,        // 容器高度 dp，默认 120
  success: (res) => console.log('banner loaded', res),
  fail: (err) => console.error('banner error', err)
})

showNativeExpressAd(options)

展示信息流滚动广告。

showNativeExpressAd({
  adspotId: '你的信息流广告位',
  position: 'center', // top | bottom | center，默认 center
  height: 300,        // 容器高度 dp，默认 300
  success: (res) => console.log('native loaded', res),
  fail: (err) => console.error('native error', err)
})

destroyAd(adspotId, adType)

手动释放指定广告位实例。

destroyAd('你的广告位', 'reward')

五、默认测试广告位

正式上线前，请务必替换为商务提供的正式广告位 ID。

六、常见问题

Q1：method not found:[uts.sdk.modules.yunsuanAds.IndexKt-xxxByJs]

• 原因：jar 缺少 JS 桥接。
• 解决：使用本插件套件中的 android/yunsuan-ads-uts.jar。

Q2：CalledFromWrongThreadException

• 原因：广告相关 UI 操作未在主线程执行。
• 解决：使用本插件最新版 jar。

Q3：Your project path contains non-ASCII characters

• 原因：Windows 路径含中文。
• 解决：在基座 gradle.properties 中添加 android.overridePathCheck=true。

Q4：appkey 没有配置

• 原因：dcloud_appkey 与包名不匹配或未配置。
• 解决：检查基座 AndroidManifest.xml，并确认 DCloud 后台包名一致。

Q5：广告位 ID 未生效

• 原因：JS 调用时未传 adspotId。
• 解决：调用时显式传入，或修改插件默认测试 ID。

七、版本说明

• 当前版本：1.0.5
• 更新内容：修复原生广告异常时弹出的系统 Toast；统一主线程展示广告；生成完整 JS 桥接；对齐广告位 ID 配置。