HarmonyOS 广告 SDK 封装实战：从原生 Ads Kit 到可复用广告组件-平芜编程栈

在移动应用中，将广告能力封装成独立 SDK 是一种非常常见且实用的工程实践，这不仅能提升广告集成效率，还能统一管理广告逻辑、埋点、曝光统计等行为。

本文将介绍如何在HarmonyOS（JavaScript / ArkTS）中对广告服务（Ads Kit / 广告服务框架）进行封装，并提供一个清晰、可复用的广告 SDK 封装方案。(developer.huawei.com)

一、为什么要封装广告 SDK？

虽然 HarmonyOS 官方提供了ohos.advertising原生 API，但直接在业务逻辑里使用原生 API 会导致：

✔ 广告逻辑和应用业务耦合
✔ 广告位难统一管理
✔ 测试调试复杂
✔ 多种广告形式重复编码

封装广告 SDK 的目标：

✅ 统一管理各类广告广告位
✅ 提供易于调用的封装 API
✅ 兼容不同广告形式（如横幅 Banner、插页、激励视频等）
✅ 可适配未来业务扩展或更换广告平台

二、HarmonyOS 广告基本 API 简介

在最新的 HarmonyOS API 中：

👉ohos.advertising模块提供广告请求和展示能力
👉 该模块从 API 版本 11 开始受支持，可用于 JS/F A 项目中调用广告相关能力(developer.huawei.com)

常见广告形式包括：

📌 横幅广告 (Banner Ad)
📌 插屏广告 (Interstitial Ad)
📌 激励视频广告 (Rewarded Video Ad)
📌 开屏广告 (Splash Ad)
📌 信息流广告 (Native Ad)

不同形式广告对应不同展示场景，本质都是调用ohos.advertising提供的请求与展示 API。

三、广告 SDK 封装设计思想

我们把封装分成两个模块：

/ads ├── AdsSDK.ts # 核心 SDK 抽象封装 ├── BannerAd.ts # 横幅广告组件 ├── InterstitialAd.ts# 插屏广告 ├── RewardedAd.ts # 激励视频 ├── AdConfig.ts # 广告配置管理

其中：

🔹AdsSDK.ts负责底层统一广告调用逻辑
🔹BannerAd.ts/InterstitialAd.ts/RewardedAd.ts提供可复用组件封装
🔹AdConfig.ts管理广告位 ID 与全局配置

四、封装核心：AdsSDK.ts

// ads/AdsSDK.ts import advertising from 'ohos.advertising' export type AdEventCallback = (info?: any) => void export class AdsSDK { static loadBannerAd(adSlotId: string, onLoad: AdEventCallback, onError: AdEventCallback) { advertising.requestBannerAd({ adSlotId, success: (data) => onLoad(data), fail: (err) => onError(err), }) } static loadInterstitialAd(adSlotId: string, onLoad: AdEventCallback, onError: AdEventCallback) { advertising.requestInterstitialAd({ adSlotId, success: (info) => onLoad(info), fail: (err) => onError(err), }) } static loadRewardedAd(adSlotId: string, onReward: AdEventCallback, onError: AdEventCallback) { advertising.requestRewardedAd({ adSlotId, success: (info) => onReward(info), fail: (err) => onError(err), }) } }

上述代码是封装后的广告请求接口，调用时不需要再关心底层细节，只需传入广告位和回调即可。

五、广告配置管理：AdConfig.ts

建议将广告位统一管理：

// ads/AdConfig.ts export const AdConfig = { BANNER_AD_ID: 'test_banner_slot_id', INTERSTITIAL_AD_ID: 'test_interstitial_slot_id', REWARDED_AD_ID: 'test_rewarded_slot_id', }

通过统一配置，便于广告位统一维护、版本切换、A/B 测试等。

六、封装横幅广告组件：BannerAd.ts

可以封装成可复用组件：

// ads/BannerAd.ts import { AdsSDK } from './AdsSDK' import { AdConfig } from './AdConfig' export class BannerAd { static show(onSuccess?: any, onFail?: any) { AdsSDK.loadBannerAd( AdConfig.BANNER_AD_ID, (data) => { console.log('Banner Ad Loaded', data) onSuccess && onSuccess(data) }, (err) => { console.error('Banner Ad Error', err) onFail && onFail(err) } ) } }

业务层使用：

BannerAd.show()

七、激励视频广告封装示例

激励视频往往需要给予回调奖励：

// ads/RewardedAd.ts import { AdsSDK } from './AdsSDK' import { AdConfig } from './AdConfig' export class RewardedAd { static show(onReward: () => void, onError?: any) { AdsSDK.loadRewardedAd( AdConfig.REWARDED_AD_ID, (info) => { console.log('Rewarded Ad Success', info) onReward() }, (err) => { console.error('Rewarded Ad Error', err) onError && onError(err) } ) } }

如果奖励到达用户完成观看后，可在回调执行奖励逻辑。

八、使用封装后的广告 SDK

在你的HarmonyOS 页面或组件中：

import { BannerAd } from '../ads/BannerAd' import { RewardedAd } from '../ads/RewardedAd' // 横幅展示 BannerAd.show() // 激励视频 RewardedAd.show(() => { alert('观看完成，奖励发放！') })

封装后广告调用“一行搞定”，业务与广告逻辑彻底分离。

九、进阶：自动曝光 & 点击埋点

实际广告变现还需要统计曝光、点击数据。可以在 SDK 内部统一调用埋点服务（如 Analytics），实现自动曝光记录与广告效果分析。

十、注意事项与实践建议

📍 广告服务模块 API 从API version 11+ 开始支持，确保设备 SDK 版本兼容性(developer.huawei.com)
📍 生产环境需替换真实广告位 ID；
📍 记得在应用配置中声明广告相关权限（如获取 OAID 等）以提升个性化广告支持(developer.huawei.com);
📍 根据不同广告形式做好冷启动 & 异步加载策略以提升用户体验。