鸿蒙接入指南

本指南说明 HarmonyOS App（ArkTS）如何接入 KeyPuff SDK：安装依赖、初始化，以及各广告格式的接入代码。示例 API 与类名均取自 SDK 源码与示例工程。

环境要求

• DevEco Studio（HarmonyOS NEXT / API 12+）；
• 使用 ohpm 管理依赖。

隐私与初始化时机

必须在用户同意 App 隐私政策之后再调用 SDK 初始化。详见 SDK 合规接入指引。

安装（ohpm）

核心 SDK 由 KeyPuff 自建制品仓库分发（.har 制品 + sha256 校验和）。ohpm 私有 registry（ohpm-repo 服务端）暂未部署，请先把 .har 下载到工程 libs/ 再以 file: 引入：

# 从制品仓库下载（地址与版本以控制台「SDK 中心」给出的为准），并校验完整性
curl -fL -o libs/advancesdk-5.2.2-kp1.har \
  https://repo.creative.zadervice.com/ohpm/advancesdk/5.2.2-kp1/advancesdk-5.2.2-kp1.har
shasum -a 256 -c <<<"$(curl -sf https://repo.creative.zadervice.com/ohpm/advancesdk/5.2.2-kp1/advancesdk-5.2.2-kp1.har.sha256)"

{
  "dependencies": {
    // 核心 SDK（必须，KeyPuff 补丁版：服务基址与密钥已在出包时写入）
    "advancesdk": "file:./libs/advancesdk-5.2.2-kp1.har",
    // 渠道 adapter（按需，示例）：
    // "mercury_adapter": "file:./libs/mercury_adapter",  // 倍业
    // "csj_adapter": "file:./libs/csj_adapter",          // 穿山甲
    // "gdt_adapter": "file:./libs/gdt_adapter",          // 优量汇
    // "ks_adapter": "file:./libs/ks_adapter",            // 快手
    // "huawei_adapter": "file:./libs/huawei_adapter",    // 华为
    // …
  }
}

确切的下载地址、校验和与版本号以控制台「SDK 中心」按您的应用生成的列表为准（该列表已排除 App 自接的渠道），复制后执行 ohpm install --all。

初始化

在 EntryAbility.onCreate 中用 appid（应用 id） 初始化，appid 在控制台「应用与广告位」查看：

// EntryAbility.ets
import { AdvanceSDK } from 'advancesdk'

onCreate(): void {
  AdvanceSDK.initSDK(this.context, '100001')   // 替换为控制台分配的应用 id（appid）
  // AdvanceSDK.debug()                        // 可选：调试日志（仅联调时开启）
}

开屏

import { AdvanceSplash, AdvanceAdLoadConfig, AdvanceSplashListener } from 'advancesdk'

let config: AdvanceAdLoadConfig = { placementId: '10000001' }  // 替换为您的 adspotid
this.splashAd = new AdvanceSplash(config)
this.splashAd.setAdListener({
  onAdLoaded: (adInfo) => {
    if (this.splashAd?.isAdValid()) this.splashAd?.showAd()
  },
  onAdLoadFailed: (err) => {},
  onAdShow: () => {},
  onAdShowFailed: (err) => {},
  onAdClick: () => {},
  onAdClose: () => {},
} as AdvanceSplashListener)
this.splashAd.loadAd()

横幅

import { AdvanceBanner, AdvanceAdLoadConfig, AdvanceBannerListener } from 'advancesdk'

let config: AdvanceAdLoadConfig = { placementId: '10000002', adWidth: 375, adHeight: 120 }
this.bannerAd = new AdvanceBanner(config)
this.bannerAd.setAdListener({
  onAdLoaded: (adInfo) => { this.isShowAd = true },
  onAdLoadFailed: (err) => { this.bannerAd = undefined },
  onAdShow: () => {},
  onAdShowFailed: (err) => {},
  onAdClick: () => {},
  onAdClose: () => {},
} as AdvanceBannerListener)
this.bannerAd.loadAd()

// 展示：用 NodeContainer 挂载广告组件
if (this.isShowAd && this.bannerAd?.isAdValid()) {
  NodeContainer(this.bannerAd.getAdComponent())
    .width(this.bannerAd.getAcceptWidth())
    .height(this.bannerAd.getAcceptHeight())
}

插屏

import { AdvanceInterstitial, AdvanceAdLoadConfig, AdvanceInterstitialListener } from 'advancesdk'

let config: AdvanceAdLoadConfig = { placementId: '10000003' }
this.interstitialAd = new AdvanceInterstitial(config)
this.interstitialAd.setAdListener({
  onAdLoaded: (adInfo) => {},
  onAdLoadFailed: (err) => { this.interstitialAd = undefined },
  onAdShow: () => {},
  onAdShowFailed: (err) => {},
  onAdClick: () => {},
  onAdClose: () => {},
} as AdvanceInterstitialListener)
this.interstitialAd.loadAd()

// 需要展示时：
if (this.interstitialAd?.isAdValid()) this.interstitialAd.showAd()

激励视频

激励视频支持服务端回调验签，如需服务端发奖请先在控制台配置激励回调：

import { AdvanceRewardVideo, AdvanceAdLoadConfig, AdvanceRewardVideoListener,
  AdvRewardVideoModel, AdvRewardCallbackInfo } from 'advancesdk'

// 奖励设置（服务端验证需要，配合控制台「激励回调」）
const model: AdvRewardVideoModel = {
  userId: '123456',                  // 服务端验证必须
  rewardAmount: 1,                   // 激励数量
  rewardName: '金币',                 // 激励名称
  extra: JSON.stringify({ k: 'v' })  // 透传参数
}
let config: AdvanceAdLoadConfig = { placementId: '10000004', rewardVideoModel: model }
this.rewardVideoAd = new AdvanceRewardVideo(config)
this.rewardVideoAd.setAdListener({
  onAdLoaded: (adInfo) => {},
  onAdLoadFailed: (err) => { this.rewardVideoAd = undefined },
  onAdShow: () => {},
  onAdClick: () => {},
  onAdClose: () => {},
  onAdRewardSuccess: (rewardInfo: AdvRewardCallbackInfo) => {},
  onAdServerRewardFail: (err) => {},
  onVideoPlayEnd: () => {},
} as AdvanceRewardVideoListener)
this.rewardVideoAd.loadAd()

// 需要展示时：
if (this.rewardVideoAd?.isAdValid()) this.rewardVideoAd.showAd()

信息流（模板渲染）

import { AdvanceNativeExpress, AdvanceAdLoadConfig, AdvanceNativeExpressListener } from 'advancesdk'

let config: AdvanceAdLoadConfig = { placementId: '10000005', adWidth: 390, adHeight: 0 }
this.nativeExpressAd = new AdvanceNativeExpress(config)
this.nativeExpressAd.setAdListener({
  onAdLoaded: (adInfo) => {},
  onAdLoadFailed: (err) => { this.nativeExpressAd = undefined },
  onRenderSuccess: () => {
    // 渲染成功后把广告插入信息流位置
  },
  onRenderFail: (err) => { this.nativeExpressAd = undefined },
  onAdShow: () => {},
  onAdClick: () => {},
  onAdClose: () => {},
  onVideoPlayEnd: () => {},
} as AdvanceNativeExpressListener)
this.nativeExpressAd.loadAd()

// 列表中展示广告：
NodeContainer(this.nativeExpressAd.getAdComponent())
  .width('100%')

信息流（自渲染）

自渲染由 AdvanceRenderFeedAdWrapper 提供素材与点击处理，开发者自行组装布局：

import { AdvanceRenderFeed, AdvanceAdLoadConfig, AdvanceRenderFeedListener,
  AdvanceRenderFeedAdWrapper } from 'advancesdk'

let config: AdvanceAdLoadConfig = { placementId: '10000006' }
this.renderFeedAd = new AdvanceRenderFeed(config)
this.renderFeedAd.setAdListener({
  onAdLoaded: (adInfo) => {},
  onAdLoadFailed: (err) => { this.renderFeedAd = undefined },
  onRenderSuccess: (wrapper: AdvanceRenderFeedAdWrapper) => {
    // 用 wrapper 自行组装布局：wrapper.getIconUrl() / getTitle() / getDescription() 等
    // 点击组件需要绑定计费点击：.onClick(event => wrapper.getClickHandler()(event))
  },
  onRenderFail: (err) => { this.renderFeedAd = undefined },
  onAdShow: () => {},
  onAdClick: () => {},
  onVideoPlayEnd: () => {},
} as AdvanceRenderFeedListener)
this.renderFeedAd.loadAd()

全屏视频

暂不支持

鸿蒙 SDK 暂未提供全屏视频广告类型（SDK 模块未导出对应广告类，可关注 更新日志 后续版本）。

Draw 视频

暂不支持

鸿蒙 SDK 暂未提供竖版视频（Draw）广告类型（SDK 模块未导出对应广告类，可关注 更新日志 后续版本）。如需 Draw 变现，请使用 Android 端。

下一步

• 集成各渠道 adapter：Adapter 集成
• 激励视频服务端验签：激励视频服务端回调
• 遇到问题：常见问题