@bi-nova/core

NovaSDK 核心包，提供跨平台适配器和插件系统。

支持环境：H5（浏览器）、微信小程序、支付宝小程序。

安装

::: code-group

pnpm add @bi-nova/core

npm install @bi-nova/core

:::

快速开始

⚠️ 重要提示：

• 微信小程序/支付宝小程序：必须设置 autoEnv: true 或手动指定适配器，否则网络请求、存储等功能将无法正常使用
• H5 应用：可省略 autoEnv（默认使用 WebAdapter）

微信小程序

import { createNova } from '@bi-nova/core'

const nova = createNova({
  appId: 'your-app-id',
  autoEnv: true, // ⚠️ 小程序环境必须开启，使用 wx.request / wx.getStorageSync 等原生 API
})

或者手动指定适配器：

import { createNova, WechatAdapter } from '@bi-nova/core'

const nova = createNova({
  appId: 'your-app-id',
  adapter: new WechatAdapter(),
})

支付宝小程序

import { createNova } from '@bi-nova/core'

const nova = createNova({
  appId: 'your-app-id',
  autoEnv: true, // ⚠️ 小程序环境必须开启，使用 my.request / my.getStorageSync 等原生 API
})

H5 应用（浏览器）

import { createNova } from '@bi-nova/core'

const nova = createNova({
  appId: 'your-app-id',
  // autoEnv 可省略，默认使用 WebAdapter（fetch / localStorage）
})

核心概念

适配器（Adapter）

适配器抹平不同平台的 API 差异，所有适配器均实现 AdapterInterface：

内置适配器：

插件系统

通过 nova.use(plugin) 注册插件，插件需满足 Plugin 接口：

interface Plugin {
  name: string
  install(sdk: NovaSDK): void
}

示例：

import { createServices } from '@bi-nova/services'

nova.use(createServices({ env: 'sit', debug: true }))

同名插件仅安装一次，重复调用 use() 会跳过并打印警告。

API

createNova(config)

工厂函数，创建 NovaSDK 实例。

参数：NovaConfig

埋点在第一条事件到达时懒初始化，默认沿用 _Lyy_Bury_Point:${appId} storage key。 同一 appId 存在多个 SDK 实例时，可传 tracking.instanceKey，或配置 tracking: { isolateByNamespace: true } 使用 advert-plugin:${appId}:${instanceKey || 'default'} 隔离会话；显式传入 tracking.namespace 的优先级最高。

userId 与匿名访客身份

埋点始终使用 qt-hook payload 顶层的 userId 字段，不增加 biVisitorId 等扩展字段。

• tracking.getUserId 仅用于同步读取宿主已经缓存的真实用户 ID，不能在其中发起异步登录请求。
• 如果初始化时没有真实 ID，SDK 默认在当前 namespace 生成一次 anon_v1_<唯一值>，并写入持久化 storage：微信/支付宝使用 setStorageSync，H5 使用 localStorage，不会使用 sessionStorage。
• 登录接口异步返回后调用 await nova.tracking.setUserId(loginResult.userId)，后续事件会覆盖为真实 ID。
• 退出登录调用 await nova.tracking.clearUserId()，恢复同一 namespace 的匿名 ID。
• 匿名 ID 只保存在 SDK 自己的 __BI_NOVA_USER_ID__:<namespace> key 中，不扫描或读取其他 _Lyy_Bury_Point* key，也不会把真实账号写入该匿名 key。

示例：

const nova = createNova({
  appId: 'your-app-id',
  autoEnv: true,
  tracking: {
    getUserId: () => app.globalData.userId || undefined,
  },
})

const loginResult = await login()
app.globalData.userId = loginResult.userId
await nova.tracking.setUserId(loginResult.userId)

React Native 需要在创建 SDK 前注册 Native 端实现：

import '@bi-nova/core/native'

返回值： NovaSDK 实例

适配器选择逻辑：

1. 若传入 adapter，直接使用
2. 若 autoEnv: true，调用 detectEnv() 自动选择
3. 否则默认使用 WebAdapter ⚠️ 小程序环境必须设置 autoEnv: true，否则功能异常

NovaSDK 实例方法

NovaSDK 实例属性

nova.tracking 用户身份方法：

await nova.tracking.setUserId(loginResult.userId) // 覆盖 anon_v1_...
await nova.tracking.clearUserId()                 // 恢复持久化匿名 ID
const userId = nova.tracking.getUserId()

detectEnv()

检测当前运行环境。

import { detectEnv } from '@bi-nova/core'

const env = detectEnv() // 'web' | 'wechat' | 'alipay' | 'unknown'

检测优先级： wechat > alipay > web > unknown

UMD 使用

通过 <script> 标签引入 UMD 产物后，所有导出挂载在 window.BiNova 上：

<script src="bi-nova.umd.js"></script>
<script>
  const { createNova } = window.BiNova
  const nova = createNova({ appId: 'xxx', autoEnv: true })
</script>

UMD 全局类型声明可通过 @bi-nova/core/global 导入：

/// <reference types="@bi-nova/core/global" />

类型导出

import type {
  AdapterInterface,
  NovaConfig,
  Plugin,
} from '@bi-nova/core'

import type { ComponentBinding, ComponentHandle } from '@bi-nova/core'

故障排查

Q: 小程序中报错 "fetch is not defined" 或 "localStorage is not defined"？

原因： 未设置 autoEnv: true，SDK 默认使用 WebAdapter（依赖 fetch、localStorage 等 Web API），而小程序环境不支持这些 API。

解决方案：

// 方式一：开启自动环境检测（推荐）
const nova = createNova({
  appId: 'your-app-id',
  autoEnv: true, // 自动选择 WechatAdapter 或 AlipayAdapter
})

// 方式二：手动指定适配器
import { WechatAdapter } from '@bi-nova/core'
const nova = createNova({
  appId: 'your-app-id',
  adapter: new WechatAdapter(),
})

Q: 小程序中网络请求、存储功能不工作？

原因： 同上，使用了错误的适配器。

解决方案： 设置 autoEnv: true 或手动指定对应平台的适配器。

Q: 如何确认当前使用的适配器？

方法： 调用 nova.getEnv() 查看当前环境：

console.log(nova.getEnv()) // 'web' | 'wechat' | 'alipay'

Q: 跨端开发（Taro/uniapp）如何配置？

推荐配置： 设置 autoEnv: true，让 SDK 根据运行环境自动选择适配器：

const nova = createNova({
  appId: 'your-app-id',
  autoEnv: true, // H5 用 WebAdapter，小程序用对应适配器
})