@bi-nova/services

跨平台广告服务 SDK，以 NovaSDK 插件形式提供京东保险口令、京东金融现金贷、平台大会员等业务服务。

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

安装

::: code-group

pnpm add @bi-nova/core @bi-nova/services

npm install @bi-nova/core @bi-nova/services

:::

快速开始

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

const nova = createNova({ appId: 'your-app-id', autoEnv: true })

nova.use(createServices({
  env: 'prod',
  debug: false,
  getAuthToken: () => getToken(),
}))

// 调用服务
const result = await nova.jd.handleJdInsurance({ equipmentValue: '...' })

平台大会员接入请参阅 平台大会员服务接入指南。

平台大会员单次购买（大会员入口 / 商家套餐入口，内部完成命中判断、统一下单与调起支付）请参阅 单次购买组件接入文档。

跨渠道签约接入请参阅 自动代扣服务接入文档。

登录态 token 管理

createServices 安装后会在 nova 实例上挂载登录态管理方法：

nova.setToken(token)
nova.clearToken()

推荐在宿主登录成功后写入 token：

const nova = createNova({ appId: 'your-app-id', autoEnv: true })

nova.use(createServices({
  env: 'prod',
  debug: false,
}))

// 用户登录成功后写入 token，后续需要登录态的内部服务会自动携带。
nova.setToken(loginResult.token)

// 用户退出登录或 token 失效时清理。
nova.clearToken()

如果宿主已经有统一登录态管理，也可以继续使用初始化配置中的 getAuthToken：

nova.use(createServices({
  env: 'prod',
  getAuthToken: () => appStore.token,
}))

内部请求的 token 获取优先级为：

nova.setToken(token) 写入的运行时 token
> createServices({ getAuthToken }) 返回值
> SDK storage 中的 auth_token

默认情况下，内部 API 请求需要 token；明确无需 token 的接口会在 SDK 内部单独标记，例如展示广告配置接口。

UMD 使用

<script src="bi-nova.umd.js"></script>
<script>
  const { createNova, createServices } = window.BiNova

  const nova = createNova({ appId: 'xxx', autoEnv: true })
  nova.use(createServices({
    env: 'sit',
    debug: true,
    getAuthToken: () => getToken(),
  }))

  // 调用方式完全一致
  const result = await nova.jd.handleJdInsurance({ equipmentValue: '...' })
</script>

初始化配置

配置选项（ServicesOptions）

⚠️ 注意：externalAppId 和 externalAppSecret 是由乐遥摇平台分配的应用凭证，与微信/支付宝小程序的 appId/appSecret 无关。

配置示例

仅内部服务：

nova.use(createServices({
  env: 'sit',
  debug: true,
  getAuthToken: () => getToken(),
}))

仅外部对接服务：

nova.use(createServices({
  externalEnv: 'sit',
  externalAppId: 'leyaoyao-assigned-app-id',
  externalAppSecret: 'leyaoyao-assigned-secret',
}))

同时使用内部和外部服务：

nova.use(createServices({
  // 内部服务配置
  env: 'sit',
  getAuthToken: () => getToken(),
  // 外部服务配置
  externalEnv: 'sit',
  externalAppId: 'leyaoyao-assigned-app-id',
  externalAppSecret: 'leyaoyao-assigned-secret',
  debug: true,
}))

环境域名映射

内部 API（env） — 适用于京东保险服务、京东金融现金贷服务

外部对接 API（externalEnv） — 适用于外部对接京东保险服务

API 详解

所有方法返回统一格式：

interface BuildResultReturn<T = any> {
  code: number     // 0 = 成功，非 0 = 失败
  message: string  // 提示信息
  data: T | null   // 业务数据
}

TypeScript 类型

类型导入

方式一：导入特定类型（推荐）

// 配置类型
import type { ServicesOptions } from '@bi-nova/services'

// 京东保险服务类型
import type {
  JdInsuranceOptions,
  JdInsuranceExternalOptions,
  JdInsuranceResult,
} from '@bi-nova/services'

// 京东金融现金贷服务类型
import type {
  JdjrCashLoanOptions,
  JdjrCashLoanExternalOptions,
} from '@bi-nova/services'

// 通用类型
import type {
  PluginConfig,
  BuildResultReturn,
  JumpConfig,
} from '@bi-nova/services'

// 环境枚举
import { ENV_TYPE, EXTERNAL_ENV_TYPE } from '@bi-nova/services'

// 错误码
import { JdErrorCode } from '@bi-nova/services'

方式二：导入所有类型

import type * as ServiceTypes from '@bi-nova/services'

// 使用时：ServiceTypes.JdInsuranceOptions

类型使用示例

使用 ENV_TYPE 枚举配置

import { createNova } from '@bi-nova/core'
import { createServices, ENV_TYPE } from '@bi-nova/services'
import type { ServicesOptions } from '@bi-nova/services'

const config: ServicesOptions = {
  env: ENV_TYPE.SIT,        // IDE 会提示可用的环境选项
  debug: true,
  getAuthToken: async () => {
    return await getToken()
  },
}

const nova = createNova({ appId: 'your-app-id', autoEnv: true })
nova.use(createServices(config))

泛型错误处理函数

import type { BuildResultReturn } from '@bi-nova/services'

async function handleServiceResult<T>(
  promise: Promise<BuildResultReturn<T>>
): Promise<T | null> {
  const result = await promise

  if (result.code === 0 && result.data !== null) {
    return result.data
  }

  showToast(result.message || '操作失败，请重试')
  return null
}

// 使用
const data = await handleServiceResult(
  nova.jd.handleJdInsurance({ equipmentValue: 'xxx' })
)

外部对接服务类型

import type { JdInsuranceExternalOptions } from '@bi-nova/services'

const params: JdInsuranceExternalOptions = {
  thirdPlatform: 'yipule',
  thirdPlatformUserId: '23413494',
  thirdPlatformEquipmentValue: '999999',
  phone: '13800138000',
  extendData: {
    customField1: 'value1',
    customField2: 123,
  },
}

const result = await nova.jd.handleJdInsuranceExt(params)

外部对接现金贷服务类型

import type { JdjrCashLoanExternalOptions } from '@bi-nova/services'

const params: JdjrCashLoanExternalOptions = {
  phone: '13800138000',
  rtaId: 'rta_strategy_001',
  thirdPlatform: 'yipule',
  thirdPlatformUserId: '23413494',
  thirdPlatformEquipmentValue: '999999',
  os: 'ios',
  client: 'miniapp',
  extendData: {
    customField1: 'value1',
    customField2: 123,
  },
}

const result = await nova.jd.handleJdjrCashLoanExt(params)

注意事项

通用

1. SDK 引入：确保已正确引入京东 SDK 文件（LyyGetCommandSDK.min.js）
2. 网络请求：插件会发起网络请求，确保小程序已配置合法域名
3. 小程序跳转权限：使用小程序跳转功能时，需要在小程序配置中添加跳转白名单
4. 剪贴板权限：复制口令功能需要用户授权剪贴板权限
5. 异步处理：所有方法返回 Promise，使用 async/await 或 .then() 处理