鸿蒙接入指引

---

本文介绍鸿蒙（HarmonyOS）SDK 的接入方式与接口说明，内容基于 CrashSight Harmony SDK 4.3.8 版本（与移动 SDK 4.3.8 同步发布）。

1 引擎接入（Unity / Unreal）

CrashSight Harmony SDK 支持 Unity、Unreal 两种引擎接入方式。插件会在适当时机自动调用原生 initContextInJS，引擎项目无需手动调用。

Unity 引擎项目接入请参考：Unity SDK开发接入
Unreal 引擎项目接入请参考：Unreal SDK开发接入

2 原生 ArkTS 接入

纯 ArkTS 或原生鸿蒙应用（非 Unity/UE）须按以下步骤集成并初始化。

2.1 添加依赖

1. 在 CrashSight 控制台「接入指南」中下载鸿蒙 SDK。
2. 将包内 CrashSight HAR 模块目录拷贝到工程中（通常与 entry 等业务模块同级）。
3. 在应用模块（如 entry）的 oh-package.json5 中添加本地依赖：

{
  "dependencies": {
    "crashsight": "file:../CrashSight"
  }
}

file: 后的路径请按 CrashSight 模块相对当前模块的实际位置修改。在工程根目录执行 ohpm install 同步依赖。

SDK 的 CrashSight 模块已在 module.json5 中声明网络相关权限（如 ohos.permission.INTERNET）；集成后请确认应用最终 manifest 已包含所需权限。

2.2 导入

在 Ability 中导入：

import { CrashSightMain } from 'crashsight';

2.3 初始化

必须先在获得 Context 后调用 initContextInJS（注册 JS 异常捕获、网络与前后台监听、创建数据目录等），再配置上报地址并 initWithAppId：

// 1) 在 UIAbility.onCreate 等早期入口，传入 Context
CrashSightMain.getInstance().initContextInJS(this.context);

// 2) 配置与初始化（initWithAppId 之前调用 config*）
CrashSightMain.getInstance().configCrashServerUrl("https://harmony.crashsight.qq.com");
CrashSightMain.getInstance().configDebugMode(false);
CrashSightMain.getInstance().initWithAppId("YOUR_APP_ID");

上报域名：

• 国内公有云：https://harmony.crashsight.qq.com
• 海外公有云：https://harmony.crashsight.wetest.net

2.4 说明

• initContextInJS 与 initWithAppId 顺序不可颠倒；缺少 initContextInJS 会导致 JS 崩溃钩子、目录与包信息未就绪。
• initContextInJS 会从 bundle 的 versionName 与 versionCode 组合读取版本号，无需在初始化前调用 setAppVersion。
• 接口详情见下文 鸿蒙接口说明。

3 鸿蒙接口说明

以下接口由 CrashSightMain 提供（4.3.8）。

3.1 初始化 Context

类：CrashSightMain
方法：initContextInJS(context: Context): void

说明：在 UIAbility.onCreate 等早期入口调用，注册 JS 未捕获异常处理、网络与前后台状态监听，并初始化数据目录与包版本信息。必须在 initWithAppId 之前调用。

参数	类型	说明
context	Context	应用 Context，通常为 this.context

3.2 配置上报域名

类：CrashSightMain
方法：configCrashServerUrl(crash_server_url: string): void

说明：设置上报域名。须在 initWithAppId 之前调用。

参数	类型	说明
crash_server_url	string	上报地址，见上文域名列表

3.3 配置调试模式

类：CrashSightMain
方法：configDebugMode(enable: boolean): void

说明：开启后输出更详细的 SDK 日志。须在 initWithAppId 之前调用。

参数	类型	说明
enable	boolean	是否开启 Debug 模式

3.4 设置应用版本

类：CrashSightMain
方法：setAppVersion(app_version: string): void

说明：设置应用版本号。initContextInJS 已从 bundle 读取版本，无需在初始化前调用。

参数	类型	说明
app_version	string	应用版本号

3.5 初始化 SDK

类：CrashSightMain
方法：initWithAppId(app_id: string): void

说明：使用控制台申请的 APP ID 完成初始化。

参数	类型	说明
app_id	string	产品 APP ID

3.6 设置用户 ID

类：CrashSightMain
方法：setUserId(user_id: string): void

说明：设置用户标识，请在初始化之后调用。

参数	类型	说明
user_id	string	用户 ID

3.7 添加自定义数据

类：CrashSightMain
方法：addSceneData(key: string, value: string): void

说明：设置 Key-Value 自定义数据，随崩溃信息一起上报。

参数	类型	说明
key	string	键
value	string	值

3.8 上报自定义异常

类：CrashSightMain
方法：reportException(type: number, exp_name: string, exp_msg: string, exp_stack: string, extra_infos: string, is_quit: boolean, dump_type: number): void

说明：主动上报错误信息。

参数	类型	说明
type	number	异常类型，如 C#: 4，JS: 5，Lua: 6
exp_name	string	异常名称
exp_msg	string	异常信息
exp_stack	string	堆栈
extra_infos	string	附加信息（JSON 字符串），不宜过大
is_quit	boolean	上报后是否退出进程
dump_type	number	Native 堆栈 dump 类型：0 关闭，1 系统 dump，3 minidump

3.9 打印日志

类：CrashSightMain
方法：printLog(level: number, message: string): void

说明：通过 SDK 输出日志。

参数	类型	说明
level	number	日志级别
message	string	日志内容

3.10 JS 异常后是否退出

类：CrashSightMain
方法：isJsExceptionExit(enable: boolean): void

说明：控制捕获未处理 JS 异常后是否退出应用进程，默认 true。

参数	类型	说明
enable	boolean	是否在 JS 异常后退出进程