ToBid

简体中文

English

简体中文

English

SDK接入配置 ​

1. 鸿蒙中心仓库接入 ​

1. 鸿蒙中心仓库接入 ​

从ToBid广告SDK-HarmonyOS 1.3.1版本开始，支持远程仓库依赖，接入方式详见：

步骤一：添加仓库

项目根目录.ohpmrc配置仓库地址registry=https://ohpm.openharmony.cn/ohpm/,https://ohpm.sigmob.com/repos/ohpm

备注：

可以配置多个仓库地址，以英文逗号间隔，多个仓库地址的优先级按照配置顺序排序。 https://ohpm.sigmob.com/repos/ohpm为ToBid鸿蒙远程仓库。

步骤二：添加依赖

在工程主module的oh-package.json5文件中需要引入ToBid SDK的模块，以远程包形式引入： 在oh-package.json5添加依赖

json
"dependencies": {
  "@tobid/adsdk": "${version}"
}

2. 手动引入har包 ​

步骤一：添加仓库

项目根目录.ohpmrc配置仓库地址registry=https://ohpm.openharmony.cn/ohpm/,https://ohpm.sigmob.com/repos/ohpm

备注：

可以配置多个仓库地址，以英文逗号间隔，多个仓库地址的优先级按照配置顺序排序。 https://ohpm.sigmob.com/repos/ohpm为ToBid鸿蒙远程仓库。

在oh-package.json5添加依赖

json
"dependencies": {
  "@tobid/adsdk": "file:./libs/tobidad-{version}.har",
}

工程完成依赖接入后，执行 ohpm install 执行har包的安装，即可在工程中tobidadsdk了。

注意： 如果之前接入了har或者本次为替换har包更新版本，可先执行ohpm clean cache清除oh_modules目录，避免更新har包失败。

SDK默认构建字节码HAR，工程的工程级build-profile.json5的useNormalizedOHMUrl字段true

2. 环境要求 ​

项目要求
系统HarmonyOS Next
APIAPI 12+
IDEDevEco Studio 5.0+
语言ArkTS（推荐 Strict Mode）
核心包@tobid/adsdk 5.0.0

3. 聚合 SDK 引入 ​

在应用模块（如 entry）的 oh-package.json5 中声明：

json5
{
  "dependencies": {
    "@tobid/adsdk": "file:../adsdk",
    "@sigmob/common": "^1.0.0"
  }
}

正式发包后可将 file: 路径替换为仓库版本号。

执行：

bash
ohpm install

4. 渠道适配器引入 ​

按后台配置的渠道，在业务模块 oh-package.json5 中按需声明 Adapter HAR。各 Adapter 已在自身 oh-package.json5 声明所依赖的渠道 SDK，无需业务侧再单独引入渠道 SDK：

json5
{
  "dependencies": {
    "@tobid/adsdk": "file:../adsdk",
    "@tobid/huawei_adapter": "file:../tobid_huawei_adapter",
    "@tobid/csj_adapter": "file:../tobid_csj_adapter",
    "@tobid/gdt_adapter": "file:../tobid_gdt_adapter",
    "@tobid/ks_adapter": "file:../tobid_ks_adapter",
    "@tobid/gromore_adapter": "file:../tobid_gromore_adapter"
  }
}

无需手动 import 注册：官聚渠道（csj / gromore / gdt / kuaishou / huawei）的 Adapter 已由 SDK 内部内置注册，并在瀑布流命中该渠道时通过动态 import 懒加载。业务侧不需要在初始化前写 import '@tobid/xxx_adapter'。

4.1 runtimeOnly 配置（必须） ​

由于 Adapter 是通过变量形式的动态 import(moduleName) 加载的，编译期无法静态解析，必须在业务模块的 build-profile.json5 中额外声明 runtimeOnly，否则模块不参与编译、运行时加载失败（错误码 800040）：

json5
{
  "buildOption": {
    "arkOptions": {
      "runtimeOnly": {
        "packages": [
          "@tobid/huawei_adapter",
          "@tobid/csj_adapter",
          "@tobid/gdt_adapter",
          "@tobid/ks_adapter",
          "@tobid/gromore_adapter"
        ]
      }
    }
  }
}

名字需与 dependencies 完全一致。Demo 参考：entry/build-profile.json5。

若后台配置了某渠道但依赖未引入（或 runtimeOnly 未声明、release 包混淆掉了 Adapter 类名），加载阶段会返回错误码 800040（适配器错误）。渠道清单、渠道 SDK 版本与排查方式见 第三方广告网络配置说明。

5. 权限配置（module.json5） ​

在入口模块 module.json5 的 requestPermissions 中按需声明（Demo entry/src/main/module.json5 参考）：

权限用途建议
ohos.permission.INTERNET广告请求 / 素材下载 / 埋点上报必选
ohos.permission.APP_TRACKING_CONSENTOAID / 广告标识相关推荐（合规同意后使用）
ohos.permission.GET_NETWORK_INFO网络类型采集推荐
ohos.permission.GET_WIFI_INFOWiFi 信息 / MAC可选
ohos.permission.APPROXIMATELY_LOCATION粗略定位（部分渠道定向）可选
ohos.permission.ACCELEROMETER摇一摇等互动可选
ohos.permission.VIBRATE震动反馈可选
ohos.permission.STORE_PERSISTENT_DATA持久化数据可选

详细说明见 权限与合规说明。

6. 工程注意点 ​

  1. 初始化必须使用 UIAbilityContext（如 EntryAbility 的 this.context），不要使用错误的 Context 类型。
  2. Banner / 原生广告依赖 ArkUI 组件渲染，请在页面生命周期内创建与销毁广告对象。
  3. 建议参考仓库 Demo：entry/src/main/ets/ads/。

7. 验证接入 ​

typescript
import { ToBidAdSDK } from '@tobid/adsdk';

console.info(`ToBid version = ${ToBidAdSDK.sdkVersion()}`);