自定义数据

在完成 SDK 接入后，你可以通过 bugly-native 插件提供的一组 API 为上报数据附加自定义信息。这些信息会跟随崩溃、ANR 以及主动调用 reportError 上报的异常一起进入 Bugly 后台，用于：

按 设备维度 / 用户维度 定位问题（哪台设备、哪个用户复现了崩溃）
按 业务标签 聚合 & 筛选异常个例（例如"支付流程"、"直播房内"）

支持的自定义数据类型

类型	API	作用	后台查看位置
设备 ID	`updateUniqueId(deviceId)`	覆盖 SDK 默认设备标识，用于按设备维度聚合与查询	异常个例详情 → 设备信息 / 设备标识
用户 ID	`updateUserId(userId)`	关联异常到具体用户，用于按用户维度定位问题	异常个例详情 → 用户信息 / 用户标识
个例标签	`setCaseLabels(labels)`	给单条上报打上一个或多个"个例标签"，用于筛选、分类	异常个例详情 → 个例标签；异常列表页支持按标签筛选
业务下钻标签	`setTestLabels(labels)`	给上报打上业务维度的下钻标签，用于按维度做下钻分析	异常列表页 / 数据分析 → 按业务下钻标签分组
自定义字段（K/V）	`putUserData(key, value)`	附加任意业务 K/V，最多 50 对	异常个例详情 → 自定义字段

tip

所有 API 都需要在 initBugly 成功之后调用；调用后设置的值只影响之后上报的数据，对已上报的历史数据不生效。

一、设置设备 ID 与用户 ID

设备 ID 和用户 ID 是最常用的两个维度，通常在应用启动完成或用户登录成功后立即设置：

// #ifdef APP-PLUS
import {
  updateUniqueId,
  updateUserId,
  reportError,
} from "@/uni_modules/bugly-native"

// 设置设备 ID：建议使用 IDFV（iOS）/ OAID 或 AndroidId（Android）等设备级稳定标识
const uniqueId = "change-device-001"
updateUniqueId(uniqueId)

// 设置用户 ID：建议在登录成功回调里设置，未登录状态不要提前塞占位值
const userId = "change-user-003"
updateUserId(userId)

// 之后触发的上报都会带上这两个 ID
const jsStack = new Error().stack || ""
reportError(
  "reportError after updateUniqueId & updateUserId",
  "BizError_UpdateUserId",
  null,
  jsStack,
  {
    unique_id: uniqueId,
    user_id: userId,
    scene: "test-bugly",
  }
)
// #endif

在 Bugly 控制台查看：进入产品 → 崩溃分析 / 错误分析 → 打开任意一条异常个例，在 设备信息 中可以看到设备标识、在 用户信息 中可以看到用户标识。异常列表页也支持按设备 ID / 用户 ID 直接搜索定位。

二、设置标签（个例标签 & 业务下钻标签）

Bugly 提供两类标签，用途和数据来源不同，不要混用：

个例标签 setCaseLabels：标签 ID 必须先在 Bugly 控制台创建，然后把创建后拿到的 ID 传进 API，多个 ID 用 | 分割。用于给某类异常打上运营/业务侧预定义的标记，方便在异常列表页按标签筛选。
业务下钻标签 setTestLabels：任意字符串，业务侧自由定义，多个用 | 分割，最多 30 个、每个 ≤1024 字符。用于按业务维度做下钻分析（例如"直播房内"、"支付流程 step2"）。

// #ifdef APP-PLUS
import {
  setCaseLabels,
  setTestLabels,
  reportError,
} from "@/uni_modules/bugly-native"

// 个例标签：必须是 Bugly 控制台创建后拿到的标签 ID
// 若传入的 ID 在平台没建过，后台会忽略这条标签
const caseLabels = "123456"
setCaseLabels(caseLabels)

// 业务下钻标签：任意字符串，业务自由定义
const testLabels = "biz_a|biz_b|test_page"
setTestLabels(testLabels)

const jsStack = new Error().stack || ""
reportError(
  "reportError after setCaseLabels & setTestLabels",
  "BizError_UpdateLabels",
  null,
  jsStack,
  {
    case_labels: caseLabels,
    test_labels: testLabels,
    scene: "test-bugly",
  }
)
// #endif

danger

setCaseLabels 传入的必须是 Bugly 控制台已创建的标签 ID，不是任意字符串。创建路径：Bugly 控制台 → 产品设置 → 标签管理。控制台没有的 ID，SDK 上报后会被后台丢弃。

在 Bugly 控制台查看：

个例标签：异常列表页顶部有"标签筛选"入口；进入异常个例详情，可在头部看到该个例携带的所有标签 ID。
业务下钻标签：数据分析 / 下钻分析 页可以按 testLabels 做维度拆分；异常列表页也支持按业务下钻标签检索。

三、设置自定义字段（K/V）

putUserData 用于给上报附加任意业务 K/V，是最灵活的自定义数据形式。适合放订单号、页面路径、当前登录态、AB 实验分组等业务快照信息：

// #ifdef APP-PLUS
import { putUserData, reportError } from "@/uni_modules/bugly-native"

// K/V 会随后续所有上报一起带上
const orderId = "ORD_20260723_001"
putUserData("order_id", orderId)
putUserData("scene", "test-bugly-page")

const jsStack = new Error().stack || ""
reportError(
  "reportError after putUserData",
  "BizError_UpdateUserData",
  null,
  jsStack,
  {
    order_id: orderId,
    scene: "test-bugly-page",
    page: "/pages/test-bugly/test-bugly",
  }
)
// #endif

约束：

key 和 value 都是 字符串，非字符串类型请业务侧自行 String(x) 转换
全局最多保留 50 对 K/V，相同 key 重复设置会覆盖旧值
只对之后的上报生效，历史数据不追溯

在 Bugly 控制台查看：进入异常个例详情 → 自定义字段 区块，可以看到该次上报携带的所有 K/V。异常列表页支持按自定义字段的 key/value 做检索。

四、`reportError` 的 `extraInfo` 参数

除了上面三类"全局"的自定义数据，reportError 本身还有一个 extraInfo 参数，用于给 这一条上报单独 附加 K/V：

reportError(
  "错误描述",
  "BizError_Xxx",     // errorType，用于后台聚合
  null,                // errorMsg，为空时使用 message
  new Error().stack,   // JS 调用栈
  {                    // extraInfo：仅本条上报生效
    scene: "checkout",
    step: "confirm",
    ts: String(Date.now()),
  }
)

extraInfo 与 putUserData 的区别：

维度	`extraInfo`（reportError 参数）	`putUserData`（全局 K/V）
作用范围	仅本次 `reportError` 调用	之后所有上报（含崩溃/ANR/reportError）
生命周期	一次性	常驻，直到进程结束或被覆盖
后台查看	异常个例详情 → 自定义字段	异常个例详情 → 自定义字段
典型用途	上报现场快照（时间戳、当前操作）	稳定的业务上下文（用户等级、AB 分组）

完整示例

下面这段是插件 demo 工程 pages/test-bugly/test-bugly.vue 里的实际用法，把三类自定义数据 + reportError 串在一起，可以直接抄：

// #ifdef APP-PLUS
import {
  initBugly,
  reportError,
  updateUniqueId,
  updateUserId,
  setCaseLabels,
  setTestLabels,
  putUserData,
  BuglyServerHost
} from "@/uni_modules/bugly-native"

// 1. 初始化
// initBugly 位置参数：appId, appKey, debug, channel, logLevel, serverHost
initBugly("你的 AppID", "你的 AppKey", true, null, null, BuglyServerHost.BuglyPro)

// 2. 设备/用户维度
updateUniqueId("change-device-001")
updateUserId("change-user-003")

// 3. 标签维度（个例标签 ID 需要先在 Bugly 控制台创建）
setCaseLabels("123456")
setTestLabels("biz_a|biz_b|test_page")

// 4. 稳定的业务 K/V
putUserData("order_id", "ORD_20260723_001")
putUserData("scene", "test-bugly-page")

// 5. 触发一次上报，本条同时带上 extraInfo
const jsStack = new Error().stack || ""
reportError(
  "reportError with custom data",
  "BizError_Demo",
  null,
  jsStack,
  {
    page: "/pages/test-bugly/test-bugly",
    ts: String(Date.now()),
  }
)
// #endif

上报成功后，前往 Bugly 专业版控制台打开对应产品，在 崩溃分析 / 错误分析 页的异常列表里找到这条上报，进入个例详情即可看到上述所有维度：

设备信息 → change-device-001
用户信息 → change-user-003
个例标签 → 123456
业务下钻标签 → biz_a / biz_b / test_page
自定义字段 → order_id / scene / page / ts

自定义数据

支持的自定义数据类型​

一、设置设备 ID 与用户 ID​

二、设置标签（个例标签 & 业务下钻标签）​

三、设置自定义字段（K/V）​

四、reportError 的 extraInfo 参数​

完整示例​