@hackler/react-sdk

中文文档
12.2.1发布于 2026/10/08ISCTypeScriptESM + CJS近 30 天下载 3.1万

React SDK for Hackle

原始使用文档
文档目录5 节
  1. Install
  2. Usage
  3. initialize
  4. Decide the variation
  5. Records the event

Hackle React SDK

Install

npm install @hackler/react-sdk --save
yarn add @hackler/react-sdk

Usage

initialize

import { createInstance, HackleProvider } from "@hackler/react-sdk"

const hackleClient = createInstance("YOUR_SDK_KEY")
const user = {
  id: "ae2182e0",
  properties: {
    app_version: "1.0.1",
    age: 23,
    paying_customer: true
  }
}
ReactDOM.render(
  <HackleProvider hackleClient={hackleClient} user={user} timeout={1000}>
    <YourApp />
  </HackleProvider>,
  document.getElementById("root")
)

The user prop replaces the current user

The user prop is applied only when its value has changed since the last time it was applied (or hackleClient was replaced) — not on every render, and not merely because the prop is present. When it is applied, it replaces the current user rather than merging into it. Properties are merged when both userId and deviceId are unchanged — in local evaluation mode only; in remote evaluation mode the server resolves properties. If either identifier differs, the previous user is discarded entirely.

This means the prop and the imperative API overwrite each other. Pick one:

// Imperative — do not pass the `user` prop
const hackleClient = createInstance("YOUR_SDK_KEY")
hackleClient.setUserId("ae2182e0")

// Declarative — do not call setUserId/setDeviceId/resetUser
<HackleProvider hackleClient={hackleClient} user={user}>
  <YourApp />
</HackleProvider>

Mixing them loses data. If the app passes user={{ deviceId }}, calls setUserId("ae2182e0"), and then re-renders with a user prop whose value has changed — an added property, say — that application replaces the user and the user id is gone. The same applies to resetUser(): a logout call is not undone by a later re-render whose user prop value is unchanged, but it is undone by a re-render whose value has changed.

A prop that goes absent (null/undefined) and later comes back with the same value it had before is not applied again, because what is tracked is the last value that was applied, not the current prop. This is deliberate: it keeps an unrelated toggle from wiping out a setUserId call made while the prop was absent.

The provider compares the prop by value, so an unstable reference — an inline object literal, say — costs nothing as long as its property values are primitives or arrays of primitives, which is what the SDK accepts. A stable reference only matters when a property value is a nested object: those compare by reference and would otherwise re-apply every render. Pass the prop as a stable reference in that case — a module-scope constant, or useMemo when it is derived:

const user = useMemo(() => ({ id: userId, properties: { plan } }), [userId, plan])

If you only need a starting user and never update it, pass it to createInstance instead and drop the prop:

const hackleClient = createInstance("YOUR_SDK_KEY", {
  user: { id: "ae2182e0", properties: { plan: "premium" } }
})

Decide the variation

function App() {
  return (
    <HackleExperiment experimentKey={42}>
      <HackleVariation variation={"A"}>
        <OldBlueButton />
      </HackleVariation>
      <HackleVariation variation={"B"}>
        <NewRedButton />
      </HackleVariation>
    </HackleExperiment>
  )
}

Records the event

const track = useTrack()
const event = {
  key: "purchase",
  value: 5000,
  properties: {
    first_paying: false,
    item_count: 5
  }
}

<button onClick={() => track(event)}>Purchase</button>

版本与发布记录

@hackler/react-sdk 共发布 172 个版本,首次发布于 2020/12/09;过去 12 个月发布了 16 个版本。

版本发布日期距今
12.2.1latest2026/10/081 个月前
12.2.02026/10/081 个月前
12.1.12026/09/032 个月前
12.1.02026/08/252 个月前
12.0.02026/08/053 个月前
11.56.12026/08/043 个月前

其他发布通道:rc → 2.0.0-rc.2,patch-11.13.3 → 11.13.3,canary → 11.54.0-canary.27。

关于 @hackler/react-sdk 的常见问题

@hackler/react-sdk 是什么?

React SDK for Hackle

如何安装 @hackler/react-sdk?

在项目目录运行 npm install @hackler/react-sdk,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=16.8.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@hackler/react-sdk 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hackler/react-sdk 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@hackler/react-sdk 可以商用吗?

@hackler/react-sdk 使用 ISC 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@hackler/react-sdk 的下载量有多少?

根据 npm 官方下载统计,@hackler/react-sdk 在 2026/10/17 – 2026/11/15 这 30 天内被下载 30,576 次,日均约 1,019 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hackler/react-sdk 还在维护吗?

最新版本 12.2.1 发布于 2026/10/08(1 个月前);至今共发布 172 个版本,其中过去 12 个月发布了 16 个;首次发布于 2020/12/09。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。