更新记录

1.0.0(2026-11-18) 下载此版本

  • 首版发布
  • 支持安装参数获取、一键拉起、注册上报、自定义事件上报、分享上报
  • 底层集成 Xinstall HarmonyOS SDK 1.0.5

平台兼容性

uni-app x(4.71)

Chrome Safari Android iOS 鸿蒙 鸿蒙插件版本 微信小程序
× × - - 13 1.0.0 ×

xinstall-harmony

鸿蒙平台 Xinstall UTS 插件,支持安装参数、一键拉起、注册与自定义事件上报。

  • 支持 uni-app(Vue3)鸿蒙工程与 uni-app x 鸿蒙工程
  • 一个插件同时用于两类工程,无需区分
  • 底层集成 Xinstall HarmonyOS SDK,包体已混淆

环境要求

项目 要求
HBuilderX 4.45 及以上
HarmonyOS API 13(5.0.1)及以上
DevEco Studio 与鸿蒙构建链匹配的版本

插件内置 HAR 按 API 13 编译,工程 compatibleSdkVersion 不能低于 5.0.1(13)。HBuilderX 当前模板默认已是该版本,一般无需修改;如需调整,在 manifest.json 的 app-harmony.distribute.compatibleSdkVersion 中设置(优先级高于 harmony-configs/build-profile.json5)。

配置

以下配置都写在 harmony-configs/entry/src/main/module.json5,harmony-configs 的作用与写法见 DCloud 文档。

配置 appKey

{
  "module": {
    "metadata": [
      {
        "name": "com.xinstall.APP_KEY",
        "value": "Xinstall 后台为应用生成的 appKey"
      }
    ]
  }
}

appKey 只从 HAP 的 metadata 读取,插件接口不接收 appKey。未配置时 SDK 所有请求都会返回配置错误(errCode 9010001)。

配置权限

{
  "module": {
    "requestPermissions": [
      { "name": "ohos.permission.INTERNET" },
      { "name": "ohos.permission.GET_WIFI_INFO" },
      { "name": "ohos.permission.GET_BUNDLE_INFO" },
      { "name": "ohos.permission.STORE_PERSISTENT_DATA" }
    ]
  }
}

需要采集 OAID 做广告归因时,额外声明 ohos.permission.APP_TRACKING_CONSENT:

{
  "name": "ohos.permission.APP_TRACKING_CONSENT",
  "reason": "$string:reason_app_tracking",
  "usedScene": {
    "abilities": ["EntryAbility"],
    "when": "inuse"
  }
}

reason 需在 entry/src/main/resources/base/element/string.json 中配置对应文案。

配置 scheme

在用于接收跳转的 Ability 中声明 Xinstall 分配给你的 scheme:

{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          },
          {
            "entities": ["entity.system.default", "entity.system.browsable"],
            "actions": ["ohos.want.action.viewData"],
            "uris": [
              { "scheme": "xi你的appKey" }
            ]
          }
        ]
      }
    ]
  }
}

导入

import * as XInstall from '@/uni_modules/xinstall-harmony'

初始化

在 App.vue 的 onLaunch 中调用。

XInstall.init()

// 需要广告归因时,先申请广告标识权限,无论是否授权都要继续初始化
XInstall.requestTrackingPermission({
  success: () => {
    XInstall.init()
  },
  fail: () => {
    XInstall.init()
  }
})

init 的配置项全部可选,不传时由 SDK 自行采集:

XInstall.init({
  // 外部已有剪贴板数据时传入;不传则由 SDK 自行采集
  // pasteboardData: 'xxx',
  // 外部已有 OAID / ODID / AAID 时传入;传 null 或 '' 表示不采集不上报
  // oaid: '',
  // odid: '',
  // aaid: '',
  // 是否采集屏幕分辨率、本地 IP,默认 true
  // collectResolution: true,
  // collectLocalIP: true
})

获取安装参数

需在 init 之后调用。

XInstall.getInstall({
  success: (data) => {
    console.log('渠道编号', data.channelCode)
    console.log('动态参数', data.data)
  },
  fail: (err) => {
    console.log('获取失败', err.errCode, err.errMsg)
  }
})
字段 类型 说明
xinstallId string Xinstall 安装标识
channelCode string 渠道编号
data object 动态参数
timeSpan number 时间间隔(毫秒)
firstFetch boolean 是否首次获取到该数据

注册唤醒

冷启动携带唤醒参数、或应用运行中被再次拉起时回调。没有有效唤醒参数时不会触发 fail。

XInstall.registerWakeUp({
  success: (data) => {
    console.log('唤醒参数', data.channelCode, data.data)
  },
  fail: (err) => {
    console.log('唤醒解析失败', err.errCode, err.errMsg)
  }
})

事件上报

// 注册上报
XInstall.reportRegister()

// 自定义事件
XInstall.reportEvent('event_id', 'event_value')

// 带详细信息的事件
XInstall.reportEventWhenOpenDetailInfo('event_id', 'event_value', 'detail_value')

// 分享上报
XInstall.reportShareByXinShareId('share_id')

// 需要结果时可传回调
XInstall.reportEvent('event_id', 'event_value', {
  success: () => {},
  fail: (err) => { console.log(err.errCode, err.errMsg) }
})

其他

// 设置是否输出 SDK 日志,需在 init 之前调用
XInstall.configSDKLog(true)

// 获取 SDK 版本号
XInstall.getVersion()

// 主动获取一次唤醒参数,通常用 registerWakeUp 即可
XInstall.getWakeUp({
  success: (data) => {},
  fail: (err) => {}
})

错误码

errCode 含义 是否可重试
9010001 SDK 配置错误,通常是未配置 appKey 否
9010002 未知错误 是
9010003 网络错误 是
9010004 未获取到数据 是
9010005 应用已被封禁 否
9010006 功能未开通 否
9010007 参数错误 否
9010008 SDK 初始化未完成 是
9010009 非 Xinstall 有效唤醒 否
9010010 未先调用 init 否
9010011 获取 UIAbilityContext 失败 否
9010012 暂无唤醒参数 否
9010013 广告标识权限未授权 否

完整说明与常见问题见插件目录 docs/集成文档.md。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

需要 ohos.permission.INTERNET、ohos.permission.GET_WIFI_INFO、ohos.permission.GET_BUNDLE_INFO、ohos.permission.STORE_PERSISTENT_DATA;广告归因还需 ohos.permission.APP_TRACKING_CONSENT

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件内部集成 Xinstall HarmonyOS SDK,会采集设备信息与安装来源用于渠道归因,详见 https://www.xinstall.com/

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

许可协议

MIT协议