更新记录

1.0.0（2026-02-15）

新增

• 初始化 OpenInstall SDK
• 获取安装参数（渠道编号、自定义参数等）
• 注册唤醒回调
• 上报效果点
• 上报分享

平台兼容性

uni-app(4.66)

uni-app x(4.66)

OpenInstall 鸿蒙 UTS 插件

OpenInstall 鸿蒙 UTS 插件，支持安装参数获取、渠道统计、效果点上报等功能。

功能特性

• ✅ 初始化 OpenInstall SDK
• ✅ 获取安装参数（渠道编号、自定义参数等）
• ✅ 自动注册唤醒回调（通过 UTSHarmony 生命周期监听器）
• ✅ 获取唤醒参数（支持自动和手动两种方式）
• ✅ 上报效果点
• ✅ 上报分享

安装

1. 在 HBuilderX 中导入本插件
2. OpenInstall SDK 已包含在插件的 libs 目录中（openinstall_v2.2.1.har），无需额外安装
3. 依赖配置已在 utssdk/app-harmony/config.json 中配置：

{
  "dependencies": {
    "@openinstall/sdk": "./libs/openinstall_v2.2.1.har"
  }
}

注意： 如果 SDK 版本需要更新，请：

1. 从 OpenInstall HarmonyOS SDK 下载最新版本的 HAR 文件
2. 将 HAR 文件放置到 utssdk/app-harmony/libs/ 目录
3. 更新 config.json 中的文件路径（如需要）

使用方法

1. 初始化

import { openInstallInit } from "@/uni_modules/zzc-openinstall";

openInstallInit({
  appKey: "your_app_key", // 从 OpenInstall 控制台获取
  adEnable: false, // 是否启用广告追踪（可选，默认 false）
  success: (res) => {
    console.log("初始化成功");
  },
  fail: (err) => {
    console.log("初始化失败:", err.errMsg);
  },
  complete: (res) => {
    console.log("初始化完成");
  },
});

推荐方式：使用工具类

// 在 App.vue 中
import openinstallManagerHarmony from "@/utils/openinstall-harmony";

onLaunch(() => {
  // 初始化 openinstall (鸿蒙)
  openinstallManagerHarmony.init();
});

2. 获取安装参数

import { openInstallGetInstall } from "@/uni_modules/zzc-openinstall";

openInstallGetInstall({
  timeout: 10000, // 超时时间（毫秒），默认 10000
  success: (res) => {
    console.log("渠道编号:", res.channelCode);
    console.log("渠道名称:", res.channelName);
    console.log("自定义参数:", res.bindData);
    console.log("自定义参数对象:", res.bindDataObj);
    console.log("是否来自分享:", res.isFromShare);
  },
  fail: (err) => {
    console.log("获取失败:", err.errMsg);
  },
  complete: (res) => {
    console.log("获取完成");
  },
});

3. 注册唤醒回调（推荐）

插件会自动注册 UTSHarmony.onAppAbilityCreate 和 UTSHarmony.onNewWant 监听器，当应用通过深度链接启动时，会自动获取 Want 对象并触发唤醒回调。

import { openInstallRegisterWakeUpHandler } from "@/uni_modules/zzc-openinstall";

// 在初始化成功后注册唤醒回调
openInstallRegisterWakeUpHandler({
  success: (res) => {
    console.log("唤醒参数:", res.channelCode, res.bindData);
    console.log("自定义参数对象:", res.bindDataObj);
    // 处理唤醒逻辑，如跳转到特定页面
  },
  fail: (err) => {
    // 获取唤醒参数失败是正常的（比如应用不是通过链接启动的）
    console.log("获取唤醒参数失败（可能是正常启动）:", err.errMsg);
  },
  complete: (res) => {
    console.log("唤醒回调完成");
  },
});

重要说明：

• 插件会在初始化时自动注册生命周期监听器（onAppAbilityCreate 和 onAppAbilityNewWant）
• 如果 SDK 已初始化且已注册唤醒回调，当应用通过深度链接启动时，会自动触发唤醒回调
• 如果唤醒回调在 Want 对象到达之后才注册，插件会自动处理已保存的 Want 对象

4. 获取唤醒参数（手动方式）

如果需要手动获取唤醒参数，可以使用 openInstallGetWakeUp：

import { openInstallGetWakeUp } from "@/uni_modules/zzc-openinstall";

// 方式1：不传 want 参数，使用插件自动保存的 Want 对象
openInstallGetWakeUp({
  success: (res) => {
    console.log("唤醒参数:", res.channelCode, res.bindData);
  },
  fail: (err) => {
    console.log("获取失败:", err.errMsg);
  },
});

// 方式2：传入 Want 对象（如果能在原生层获取到）
openInstallGetWakeUp({
  want: wantObject, // 从 EntryAbility.onCreate 或 onNewWant 中获取的 Want 对象
  success: (res) => {
    console.log("唤醒参数:", res.channelCode, res.bindData);
  },
  fail: (err) => {
    console.log("获取失败:", err.errMsg);
  },
});

注意： 通常不需要手动调用 openInstallGetWakeUp，推荐使用 openInstallRegisterWakeUpHandler 注册回调，插件会自动处理唤醒参数。

5. 上报效果点

import { openInstallReportEffectPoint } from "@/uni_modules/zzc-openinstall";

openInstallReportEffectPoint({
  pointId: "effect_point_001", // 效果点 ID（必填）
  pointValue: 100, // 效果点值（可选，默认 0）
  success: (res) => {
    console.log("上报成功");
  },
  fail: (err) => {
    console.log("上报失败:", err.errMsg);
  },
  complete: (res) => {
    console.log("上报完成");
  },
});

6. 上报分享

import { openInstallReportShare } from "@/uni_modules/zzc-openinstall";

openInstallReportShare({
  sharePlatform: "***", // 分享平台（必填）：***, qq, weibo 等
  shareId: "share_001", // 分享 ID（可选）
  success: (res) => {
    console.log("上报成功");
  },
  fail: (err) => {
    console.log("上报失败:", err.errMsg);
  },
  complete: (res) => {
    console.log("上报完成");
  },
});

API 说明

openInstallInit

初始化 OpenInstall SDK。

参数：

• appKey (string, 必填): OpenInstall 应用 AppKey
• adEnable (boolean, 可选): 是否启用广告追踪，默认 false
• success (function, 可选): 成功回调
• fail (function, 可选): 失败回调
• complete (function, 可选): 完成回调

openInstallGetInstall

获取安装参数。

参数：

• timeout (number, 可选): 超时时间（毫秒），默认 10000
• success (function, 可选): 成功回调，返回安装参数
• fail (function, 可选): 失败回调
• complete (function, 可选): 完成回调

返回结果：

• channelCode (string, 可选): 渠道编号
• channelName (string, 可选): 渠道名称
• bindData (string, 可选): 自定义参数（JSON 字符串）
• bindDataObj (object | null, 可选): 自定义参数（解析后的对象）
• isFromShare (boolean, 可选): 是否通过分享链接安装

openInstallRegisterWakeUpHandler

注册唤醒回调。插件会自动注册生命周期监听器，当应用通过深度链接启动时，会自动获取 Want 对象并触发回调。

参数：

• success (function, 可选): 成功回调，返回唤醒参数
• fail (function, 可选): 失败回调
• complete (function, 可选): 完成回调

返回结果：

• channelCode (string, 可选): 渠道编号
• channelName (string, 可选): 渠道名称
• bindData (string, 可选): 自定义参数（JSON 字符串）
• bindDataObj (object | null, 可选): 自定义参数（解析后的对象）
• isFromShare (boolean, 可选): 是否通过分享链接唤醒

重要说明：

• 插件会在初始化时自动注册 UTSHarmony.onAppAbilityCreate 和 UTSHarmony.onAppAbilityNewWant 监听器
• 如果 SDK 已初始化且已注册唤醒回调，当应用通过深度链接启动时，会自动触发唤醒回调
• 如果唤醒回调在 Want 对象到达之后才注册，插件会自动处理已保存的 Want 对象

openInstallGetWakeUp

手动获取唤醒参数。

参数：

• want (object, 可选): HarmonyOS 的 Want 对象。如果不传，会使用插件自动保存的 Want 对象（从 onAppAbilityCreate 或 onAppAbilityNewWant 获取）
• success (function, 可选): 成功回调，返回唤醒参数
• fail (function, 可选): 失败回调
• complete (function, 可选): 完成回调

返回结果：

• channelCode (string, 可选): 渠道编号
• channelName (string, 可选): 渠道名称
• bindData (string, 可选): 自定义参数（JSON 字符串）
• bindDataObj (object | null, 可选): 自定义参数（解析后的对象）
• isFromShare (boolean, 可选): 是否通过分享链接唤醒

注意： 通常不需要手动调用此方法，推荐使用 openInstallRegisterWakeUpHandler 注册回调。

openInstallReportEffectPoint

上报效果点。

参数：

• pointId (string, 必填): 效果点 ID
• pointValue (number, 可选): 效果点值，默认 0
• success (function, 可选): 成功回调
• fail (function, 可选): 失败回调
• complete (function, 可选): 完成回调

openInstallReportShare

上报分享。

参数：

• sharePlatform (string, 必填): 分享平台（如：***, qq, weibo 等）
• shareId (string, 可选): 分享 ID
• success (function, 可选): 成功回调
• fail (function, 可选): 失败回调
• complete (function, 可选): 完成回调

错误码

• 9020001: 初始化失败或 SDK 未初始化
• 9020002: 获取安装参数失败或获取唤醒参数失败
• 9020003: 上报效果点失败
• 9020004: 配置错误（如 AppKey 未配置、效果点 ID 未提供等）
• 9020005: 网络错误或未找到 Want 对象
• 9020006: 系统错误（如无法获取应用上下文）

工作原理

自动唤醒处理机制

插件实现了自动唤醒处理机制，工作流程如下：

1. 初始化时：插件自动注册 UTSHarmony.onAppAbilityCreate 和 UTSHarmony.onAppAbilityNewWant 生命周期监听器
2. 应用启动时：
   • 如果是首次启动，onAppAbilityCreate 会被触发，插件会保存 Want 对象
   • 如果是通过深度链接启动，onAppAbilityNewWant 会被触发，插件会保存 Want 对象
3. 注册唤醒回调时：
   • 如果 SDK 已初始化且已注册唤醒回调，插件会立即处理已保存的 Want 对象
   • 如果唤醒回调在 Want 对象到达之后才注册，插件会自动处理已保存的 Want 对象
4. 自动触发回调：当应用通过深度链接启动时，插件会自动调用 getWakeUp 并触发注册的回调

Want 对象处理

• 插件会自动从 onAppAbilityCreate 和 onAppAbilityNewWant 获取 Want 对象
• Want 对象会被保存到 savedWant 变量中
• 当注册唤醒回调时，如果已有保存的 Want 对象，会立即处理
• 通常不需要手动调用 openInstallSetWant，但插件提供了此函数供特殊场景使用

注意事项

1. 初始化顺序：

   • 必须先调用 openInstallInit 初始化 SDK
   • 建议在应用启动时（如 App.vue 的 onLaunch）初始化

2. 唤醒回调注册：

   • 建议在初始化成功后立即注册唤醒回调
   • 插件会自动处理 Want 对象，无需手动获取

3. 获取安装参数：

   • 建议在应用首次启动时调用（可通过 cookie 等机制判断是否首次启动）
   • 超时时间建议设置为 8-10 秒

4. 错误处理：

   • 获取唤醒参数失败是正常的（比如应用不是通过链接启动的）
   • 建议在 fail 回调中只记录日志，不要作为错误处理

5. AppKey 配置：

   • 使用前需要在 OpenInstall 控制台创建应用并获取 AppKey
   • 建议通过环境变量或配置文件管理 AppKey

完整示例

// App.vue
import openinstallManagerHarmony from "@/utils/openinstall-harmony";

onLaunch(() => {
  // 初始化 openinstall (鸿蒙)
  openinstallManagerHarmony.init();
});

// utils/openinstall-harmony.ts
import {
  openInstallInit,
  openInstallGetInstall,
  openInstallRegisterWakeUpHandler,
} from "@/uni_modules/zzc-openinstall";
import cookie from "@/utils/cookie";

class OpeninstallManagerHarmony {
  private appKey = "your_app_key";
  private isInitialized = false;

  init() {
    openInstallInit({
      appKey: this.appKey,
      adEnable: false,
      success: () => {
        console.log("OpenInstall 初始化成功");
        this.isInitialized = true;
        this.registerCallbacks();
      },
      fail: (err) => {
        console.error("OpenInstall 初始化失败:", err.errMsg);
      },
    });
  }

  private registerCallbacks() {
    // 注册唤醒回调
    openInstallRegisterWakeUpHandler({
      success: (res) => {
        console.log("唤醒参数:", res.channelCode, res.bindData);
        // 处理唤醒逻辑
      },
      fail: (err) => {
        console.log("获取唤醒参数失败（可能是正常启动）:", err.errMsg);
      },
    });

    // 获取安装参数（仅首次启动）
    const isFirstOpen = cookie.get("isFirstOpen");
    if (!isFirstOpen) {
      openInstallGetInstall({
        timeout: 8000,
        success: (res) => {
          cookie.set("isFirstOpen", true);
          console.log("安装参数:", res.channelCode, res.bindData);
          // 处理安装参数
        },
        fail: (err) => {
          console.error("获取安装参数失败:", err.errMsg);
        },
      });
    }
  }
}

参考文档

• OpenInstall 官网
• OpenInstall HarmonyOS SDK