OSETSDK 外部接入文档

上海神蓍信息科技有限公司2026年4月20日大约 7 分钟

OSETSDK 外部接入文档

1. 接入总览

推荐优先级：

远程仓接入，首要推荐。
纯本地 HAR 接入，作为备选方案。

当前对外交付的核心包：

@shenshi/opensetsdk
@shenshi/gdt-adapter
@shenshi/csj-adapter
@shenshi/harmony-adapter
@shenshi/taku-adapter

当前版本：

@shenshi/opensetsdk: 1.0.12
@shenshi/gdt-adapter: 1.2.0-1
@shenshi/csj-adapter: 7.3.0-1
@shenshi/harmony-adapter: 1.0.0-1
@shenshi/taku-adapter: 6.0.19-1

正式仓地址：

http://ohpm-repo.shenshiads.com/repos/prod

2. 远程仓接入

这是推荐方式。

2.1 需要准备的本地 HAR

宿主工程根目录创建 libs/ 文件夹，并按实际接入渠道放入下面这些 HAR：

直连 GDT：GDTUnionSDK-default-release.har
直连 CSJ：openadsdk_7.3.0.har
Taku 基础：anythink_sdk.har
Taku -> CSJ 子渠道：anythink_network_csj.har + openadsdk_7.3.0.har
Taku -> GDT 子渠道：anythink_network_gdt.har + GDTUnionSDK-default-release.har
Taku -> Harmony 子渠道：anythink_network_huawei.har
Taku -> KS 子渠道：anythink_network_ks.har + KSAdSDK-3.0.5.har

说明：

@shenshi/opensetsdk 和各 adapter 走远程仓，不需要放到 libs/。
Harmony 直连适配器本身没有额外本地渠道 HAR。
KS 是 Taku 的子渠道，不存在独立的 @shenshi/ks-adapter。
如果宿主未接入 Taku，或者未启用某个 Taku 子渠道，可以省略对应的 anythink_network_* 和底层渠道 HAR。
为降低外部接入判断成本，标准归档包会默认把 Taku 相关子渠道 HAR 一并提供。
Taku 相关的 anythink_network_* HAR 已在归档阶段统一改成版本依赖语义，宿主工程只需要做包名映射即可。

2.2 配置项目根 `.ohpmrc`

registry=https://ohpm.openharmony.cn/ohpm/,http://ohpm-repo.shenshiads.com/repos/prod
@shenshi:registry=http://ohpm-repo.shenshiads.com/repos/prod

2.3 配置项目根 `oh-package.json5`

{
  "modelVersion": "5.0.5",
  "overrides": {
    "@gdt/gdt-union-sdk": "file:./libs/GDTUnionSDK-default-release.har",
    "@csj/openadsdk": "file:./libs/openadsdk_7.3.0.har",
    "anythink_sdk": "file:./libs/anythink_sdk.har",
    "anythink_network_csj": "file:./libs/anythink_network_csj.har",
    "anythink_network_gdt": "file:./libs/anythink_network_gdt.har",
    "anythink_network_huawei": "file:./libs/anythink_network_huawei.har",
    "anythink_network_ks": "file:./libs/anythink_network_ks.har",
    "ksadsdk": "file:./libs/KSAdSDK-3.0.5.har"
  },
  "dependencies": {},
  "devDependencies": {
    "@ohos/hypium": "1.0.21",
    "@ohos/hamock": "1.0.0"
  }
}

2.4 配置 `entry/oh-package.json5`

{
  "dependencies": {
    "@shenshi/opensetsdk": "^1.0.12",
    "@shenshi/gdt-adapter": "^1.2.0-1",
    "@shenshi/csj-adapter": "^7.3.0-1",
    "@shenshi/harmony-adapter": "^1.0.0-1",
    "@shenshi/taku-adapter": "^6.0.19-1"
  },
  "dynamicDependencies": {
    "anythink_network_csj": "^6.0.19",
    "anythink_network_gdt": "^6.0.19",
    "anythink_network_huawei": "^6.0.19",
    "anythink_network_ks": "^6.0.19"
  }
}

2.5 配置 `entry/build-profile.json5`

{
  "apiType": "stageMode",
  "buildOption": {
    "arkOptions": {
      "runtimeOnly": {
        "sources": [],
        "packages": [
          "@shenshi/gdt-adapter",
          "@shenshi/csj-adapter",
          "@shenshi/harmony-adapter",
          "@shenshi/taku-adapter",
          "anythink_network_csj",
          "anythink_network_gdt",
          "anythink_network_huawei",
          "anythink_network_ks"
        ]
      }
    }
  }
}

2.6 安装依赖

ohpm install

3. 本地 HAR 接入

这种方式不走远程仓，@shenshi 包也统一放到宿主工程根目录 libs/。

如果项目只走本地 HAR 接入，通常不需要再额外配置 .ohpmrc。

3.1 需要准备的本地 HAR

除了第 2.1 节中按实际接入渠道准备的 HAR，还要额外放入下面这些 SDK HAR：

shenshi-opensetsdk-1.0.12.har
shenshi-gdt-adapter-1.2.0-1.har
shenshi-csj-adapter-7.3.0-1.har
shenshi-harmony-adapter-1.0.0-1.har
shenshi-taku-adapter-6.0.19-1.har

说明：

如果宿主使用 Taku -> KS，本地 libs/ 中仍然需要额外包含 anythink_network_ks.har 和 KSAdSDK-3.0.5.har。
如果宿主没有启用某个 Taku 子渠道，可以不放该子渠道对应的 HAR。

3.2 配置项目根 `oh-package.json5`

{
  "modelVersion": "5.0.5",
  "overrides": {
    "@shenshi/opensetsdk": "file:./libs/shenshi-opensetsdk-1.0.12.har",
    "@shenshi/gdt-adapter": "file:./libs/shenshi-gdt-adapter-1.2.0-1.har",
    "@shenshi/csj-adapter": "file:./libs/shenshi-csj-adapter-7.3.0-1.har",
    "@shenshi/harmony-adapter": "file:./libs/shenshi-harmony-adapter-1.0.0-1.har",
    "@shenshi/taku-adapter": "file:./libs/shenshi-taku-adapter-6.0.19-1.har",
    "@gdt/gdt-union-sdk": "file:./libs/GDTUnionSDK-default-release.har",
    "@csj/openadsdk": "file:./libs/openadsdk_7.3.0.har",
    "anythink_sdk": "file:./libs/anythink_sdk.har",
    "anythink_network_csj": "file:./libs/anythink_network_csj.har",
    "anythink_network_gdt": "file:./libs/anythink_network_gdt.har",
    "anythink_network_huawei": "file:./libs/anythink_network_huawei.har",
    "anythink_network_ks": "file:./libs/anythink_network_ks.har",
    "ksadsdk": "file:./libs/KSAdSDK-3.0.5.har"
  },
  "dependencies": {},
  "devDependencies": {
    "@ohos/hypium": "1.0.21",
    "@ohos/hamock": "1.0.0"
  }
}

3.3 配置 `entry/oh-package.json5`

本地 HAR 接入时，entry/oh-package.json5 与远程仓接入保持一致：

{
  "dependencies": {
    "@shenshi/opensetsdk": "^1.0.12",
    "@shenshi/gdt-adapter": "^1.2.0-1",
    "@shenshi/csj-adapter": "^7.3.0-1",
    "@shenshi/harmony-adapter": "^1.0.0-1",
    "@shenshi/taku-adapter": "^6.0.19-1"
  },
  "dynamicDependencies": {
    "anythink_network_csj": "^6.0.19",
    "anythink_network_gdt": "^6.0.19",
    "anythink_network_huawei": "^6.0.19",
    "anythink_network_ks": "^6.0.19"
  }
}

3.4 配置 `entry/build-profile.json5`

本地 HAR 接入时，entry/build-profile.json5 与远程仓接入保持一致：

{
  "apiType": "stageMode",
  "buildOption": {
    "arkOptions": {
      "runtimeOnly": {
        "sources": [],
        "packages": [
          "@shenshi/gdt-adapter",
          "@shenshi/csj-adapter",
          "@shenshi/harmony-adapter",
          "@shenshi/taku-adapter",
          "anythink_network_csj",
          "anythink_network_gdt",
          "anythink_network_huawei",
          "anythink_network_ks"
        ]
      }
    }
  }
}

3.5 安装依赖

ohpm install

4. 宿主工程权限

宿主工程至少需要声明以下权限：

ohos.permission.INTERNET
ohos.permission.APP_TRACKING_CONSENT

示例：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.APP_TRACKING_CONSENT",
        "reason": "$string:request_track",
        "usedScene": {
          "abilities": [
            "EntryFormAbility"
          ],
          "when": "always"
        }
      }
    ]
  }
}

说明：

APP_TRACKING_CONSENT 用于获取 OAID。
如果宿主未声明该权限，或用户拒绝授权，SDK 会自动降级为 ODID / UUID，不会阻塞广告流程，但会影响转化和广告收益。

5. 初始化

建议在 EntryAbility.onWindowStageCreate() 中初始化 SDK，并缓存 windowStage。

import { OSETSDK } from '@shenshi/opensetsdk'
import { window } from '@kit.ArkUI'

class SdkEnv {
  static windowStage: window.WindowStage
}

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    SdkEnv.windowStage = windowStage

    OSETSDK.init('你的AppKey', this.context, {
      onSuccess: () => {
        console.info('OSETSDK init success')
      },
      onFail: (errorCode: number, errorMessage: string) => {
        console.error(`OSETSDK init fail: ${errorCode}, ${errorMessage}`)
      }
    })
  }
}

可选接口：

OSETSDK.setDebug(true)
const sdkVersion = OSETSDK.getSdkVersion()
const initialized = OSETSDK.isInitialized()

联调时可直接使用第 6 节中的测试 AppKey。

6. 测试 AppKey 与广告位 ID

以下测试参数来自 SDK 工程内的 demo 配置，可用于外部项目联调验证。

仅建议用于测试环境，正式上线前请替换为正式的 AppKey 和广告位 ID。

类型	测试值
`AppKey`	`EE048F6DDE8C8D08`
开屏 `posId`	`AB2A00DCD68A4B790BA27A5437A6C130`
Banner `posId`	`D2FDD696D3D364D1DBFAF6C07A2488C2`
插屏 `posId`	`CE2F46A28FF2C299F1535EB44B10775D`
激励视频 `posId`	`55242FD9034BBE21E5C6CD8E0C02030D`
信息流模版 `posId`	`3AC0961330E985CB25B1FC77DACAD2DE`

7. 广告调用通用流程

获取广告实例。
设置广告位 posId。
可选设置 userId。
调用 loadAd()。
在 onLoadSuccess 中拿到广告对象。
绑定展示监听。
调用 showAd() 或挂载广告组件。
页面销毁时调用 destroy()。

通用示例：

广告类型.getInstance()
  .setPosId('你的广告位ID')
  .setUserId('你的用户ID')
  .loadAd({
    onLoadSuccess: (ad) => {
      // 成功后拿到广告对象
    },
    onLoadFail: (errorCode: number, errorMessage: string) => {}
  })

8. 广告类型入口

import { OSETSplash } from '@shenshi/opensetsdk'
import { OSETBanner } from '@shenshi/opensetsdk'
import { OSETInterstitial } from '@shenshi/opensetsdk'
import { OSETReward } from '@shenshi/opensetsdk'
import { OSETNative } from '@shenshi/opensetsdk'

说明：

OSETSplash、OSETInterstitial、OSETReward 成功加载后直接调用 showAd(windowStage)。
OSETBanner、OSETNative 成功渲染后，通过 getAdComponent() 挂载到 NodeContainer。

9. 开屏广告示例

测试 posId：

const POS_ID_SPLASH = 'AB2A00DCD68A4B790BA27A5437A6C130'

示例：

import { OSETSplash, OSETSplashAd, OSETSplashListener } from '@shenshi/opensetsdk'

let splashAd: OSETSplashAd | undefined

OSETSplash.getInstance()
  .setPosId(POS_ID_SPLASH)
  .loadAd({
    onLoadSuccess: (ad: OSETSplashAd) => {
      splashAd = ad
      splashAd.setSplashAdListener({
        onShow: () => {},
        onClick: () => {},
        onClose: () => {
          splashAd = undefined
        },
        showFail: (errorCode: number, errorMsg: string) => {}
      } as OSETSplashListener)

      if (splashAd.isUsable()) {
        splashAd.showAd(SdkEnv.windowStage)
      }
    },
    onLoadFail: (errorCode: number, errorMessage: string) => {}
  })

说明：

开屏广告建议按“先加载，后展示”的方式调用。
页面结束或广告不再使用时，记得调用 destroy() 释放对象。

测试 posId：

const POS_ID_BANNER = 'D2FDD696D3D364D1DBFAF6C07A2488C2'

示例：

import { NodeController } from '@kit.ArkUI'
import { OSETBanner, OSETBannerAd, OSETBannerListener } from '@shenshi/opensetsdk'

@Component
struct BannerPage {
  @State bannerNode?: NodeController
  private bannerAd?: OSETBannerAd

  build() {
    Column() {
      Button('加载 Banner').onClick(() => {
        this.loadBanner()
      })

      if (this.bannerNode) {
        NodeContainer(this.bannerNode)
          .width('100%')
          .height(120)
      }
    }
  }

  private loadBanner() {
    this.bannerAd?.destroy()
    this.bannerAd = undefined
    this.bannerNode = undefined

    OSETBanner.getInstance()
      .setPosId(POS_ID_BANNER)
      .loadAd({
        onLoadSuccess: (ad: OSETBannerAd) => {
          this.bannerAd = ad
          this.bannerAd.setBannerListener({
            onShow: () => {},
            onClick: () => {},
            onClose: () => {
              this.bannerAd = undefined
              this.bannerNode = undefined
            },
            onRenderSuccess: () => {
              this.bannerNode = this.bannerAd?.getAdComponent()
            },
            onRenderFail: (errorCode: number, errorMsg: string) => {},
            showFail: (errorCode: number, errorMsg: string) => {}
          } as OSETBannerListener)

          this.bannerAd.showAd(SdkEnv.windowStage)
        },
        onLoadFail: (errorCode: number, errorMessage: string) => {}
      })
  }

  aboutToDisappear(): void {
    this.bannerAd?.destroy()
    this.bannerAd = undefined
    this.bannerNode = undefined
  }
}

说明：

Banner 广告成功渲染后，通过 getAdComponent() 获取 NodeController。
建议页面销毁时调用 destroy()。

11. 插屏广告示例

测试 posId：

const POS_ID_INTERSTITIAL = 'CE2F46A28FF2C299F1535EB44B10775D'

示例：

import { OSETInterstitial, OSETInterstitialAd, OSETInterstitialListener } from '@shenshi/opensetsdk'

let interstitialAd: OSETInterstitialAd | undefined

OSETInterstitial.getInstance()
  .setPosId(POS_ID_INTERSTITIAL)
  .loadAd({
    onLoadSuccess: (ad: OSETInterstitialAd) => {
      interstitialAd = ad
      interstitialAd.setInterstitialAdListener({
        onShow: () => {},
        onClick: () => {},
        onClose: () => {
          interstitialAd = undefined
        },
        showFail: (errorCode: number, errorMsg: string) => {}
      } as OSETInterstitialListener)

      if (interstitialAd.isUsable()) {
        interstitialAd.showAd(SdkEnv.windowStage)
      }
    },
    onLoadFail: (errorCode: number, errorMessage: string) => {}
  })

12. 激励视频广告示例

测试 posId：

const POS_ID_REWARD_VIDEO = '55242FD9034BBE21E5C6CD8E0C02030D'

import { OSETReward, OSETRewardAd, OSETRewardListener } from '@shenshi/opensetsdk'

OSETReward.getInstance()
  .setPosId(POS_ID_REWARD_VIDEO)
  .loadAd({
    onLoadSuccess: (ad: OSETRewardAd) => {
      ad.setRewardAdListener({
        onShow: () => {},
        onClick: () => {},
        onReward: () => {},
        onClose: () => {},
        showFail: (errorCode: number, errorMsg: string) => {}
      } as OSETRewardListener)
      ad.showAd(SdkEnv.windowStage)
    },
    onLoadFail: (errorCode: number, errorMessage: string) => {}
  })

说明：

激励视频奖励回调通过 onReward() 接收。
展示前建议通过 isUsable() 判断广告对象是否仍然有效。

13. 信息流模版广告示例

测试 posId：

const POS_ID_NATIVE = '3AC0961330E985CB25B1FC77DACAD2DE'

示例：

import { NodeController } from '@kit.ArkUI'
import { OSETNative, OSETNativeAd, OSETNativeListener } from '@shenshi/opensetsdk'

@Component
struct NativePage {
  @State nativeNode?: NodeController
  private nativeAd?: OSETNativeAd

  build() {
    Column() {
      Button('加载信息流模版广告').onClick(() => {
        this.loadNative()
      })

      if (this.nativeNode) {
        NodeContainer(this.nativeNode)
          .width('100%')
          .height(320)
      }
    }
  }

  private loadNative() {
    this.nativeAd?.destroy()
    this.nativeAd = undefined
    this.nativeNode = undefined

    OSETNative.getInstance()
      .setPosId(POS_ID_NATIVE)
      .loadAd({
        onLoadSuccess: (ad: OSETNativeAd) => {
          this.nativeAd = ad
          this.nativeAd.setNativeListener({
            onShow: () => {},
            onClick: () => {},
            onClose: () => {
              this.nativeAd = undefined
              this.nativeNode = undefined
            },
            onRenderSuccess: () => {
              this.nativeNode = this.nativeAd?.getAdComponent()
            },
            onRenderFail: (errorCode: number, errorMsg: string) => {},
            showFail: (errorCode: number, errorMsg: string) => {}
          } as OSETNativeListener)

          this.nativeAd.showAd(SdkEnv.windowStage)
        },
        onLoadFail: (errorCode: number, errorMessage: string) => {}
      })
  }

  aboutToDisappear(): void {
    this.nativeAd?.destroy()
    this.nativeAd = undefined
    this.nativeNode = undefined
  }
}

14. 常见问题

NOTFOUND package '@shenshi/xxx' not found from all the registries
先检查项目根 .ohpmrc 是否已经把 @shenshi scope 指向正式仓。
adapter 安装成功但运行时报找不到模块
优先检查 entry/build-profile.json5 是否把对应 adapter 加入了 runtimeOnly.packages。
AnyThink、子渠道 HAR 或底层渠道 SDK 找不到
优先检查项目根 oh-package.json5 的 overrides 是否已完整包含 anythink_sdk、anythink_network_*、ksadsdk 以及 @csj/openadsdk / @gdt/gdt-union-sdk 的映射。
Taku 某个子渠道运行时报 Cannot find dynamic-import module、无填充或加载无响应
优先同时检查四处是否一致：libs/ 是否存在对应 HAR、项目根 oh-package.json5.overrides 是否有对应映射、entry/oh-package.json5.dynamicDependencies 是否声明该 anythink_network_*、entry/build-profile.json5.runtimeOnly.packages 是否包含该子渠道。
GET ... 502 Bad Gateway
先检查本机 ~/.ohpm/.ohpmrc 里的 http_proxy / https_proxy 是否写错。正确示例为 http://127.0.0.1:7897。