更新记录
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。

收藏人数:
下载插件并导入HBuilderX
赞赏(0)
下载 1527
赞赏 1
下载 12779166
赞赏 1960
赞赏
京公网安备:11010802035340号