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);

📍 根据不同广告形式做好冷启动 & 异步加载策略以提升用户体验。

总结

这篇文章讲解了：

✅ HarmonyOS 广告服务 (Ads Kit / ohos.advertising) 封装思路

✅ 如何设计一个广告 SDK 结构

✅ 核心 API 封装示例

✅ 如何实现横幅、激励视频等广告组件

通过这样的封装，你可以快速在项目中复用广告能力，减少业务代码和硬编码的侵入，让广告体系更健壮、更易维护。