开吧商城接入 SDK

⚠️ 重要提示：本 SDK 基于 TypeScript 开发，所有 API 参数均带有明确的必填 / 选填类型标注。使用时请务必开启 TS 类型检查或在 IDE 中查看参数提示，必填项缺失会直接提示错误，选填项可按需传入，请勿忽略类型提示以避免使用异常。

安装方式 1：npm

npm:

npm i @kbapp/market-partner-sdk

import { runAction } from '@kbapp/market-partner-sdk'

const onTapRunAction = async () => {
    runAction({
        action: 'pageWeb',
        actionParams: {
            url: 'https://www.baidu.com',
        },
        success() {
            console.log('执行成功')
        },
    })
}

安装方式 2：通过 script 标签引入

请先引入 JS Bridge：<script src="https://unpkg.com/@kbapp/js-bridge@latest/dist/umd/index.js"></script>，再引入本 SDK。

使用 unpkg CDN：

<script src="https://unpkg.com/@kbapp/market-partner-sdk@latest/dist/umd/index.js"></script>

使用 jsdelivr CDN：

<script src="https://cdn.jsdelivr.net/npm/@kbapp/market-partner-sdk@latest/dist/umd/index.js"></script>

通过 script 标签引入后，SDK 将作为全局变量 kbMarket 挂载在 window 对象上

<!-- 该插件依赖js-bridge -->
<script src="https://unpkg.com/@kbapp/js-bridge@latest/dist/umd/index.js"></script>
<script src="https://unpkg.com/@kbapp/market-partner-sdk@latest/dist/umd/index.js"></script>
<script>
const onTapRunAction = async () => {
    // 通过全局变量kbMarket访问SDK功能
    kbMarket.runAction({
        action: 'pageWeb',
        actionParams: {
            url: 'https://www.baidu.com',
        },
        success() {
            console.log('执行成功')
        },
    })
}
</script>

API

总览

| 方法 | 说明 | | -------------------------- | -------------------------------------- | | registerNativeApiHandler | 注册提供给 Native 端调用的 API | | invokeNativeApi | 触发 App 桥接 | | runAction | 执行统一跳转页面标准 | | defineAppShareModel | 定义页面分享内容 | | openAppSharePanel | 主动唤起分享面板 | | reportDAEvent | 上报数据埋点 | | getAppBaseInfo | 获取开吧 App 基础信息 | | shareImage | 分享图片 | | onAppSharePanelShow | 监听分享面板打开事件 | | isAppVersionSupport | 判断当前版本号是否 大于等于 某个版本 | | getAuthToken | 获取认证令牌 | | getAuthTokenWithSilent | 静默获取认证令牌 | | requestPayment | 唤起支付 | | requestRefund | 申请退款 |

| 类/枚举 | 说明 | | --------------- | -------------------- | | BridgeCode | 错误码枚举 | | AppBaseInfo | App 基础信息数据模型 | | AppShareModel | 应用分享模型 | | AuthResult | 认证结果数据模型 |

registerNativeApiHandler

注册提供给 Native 端调用的 API

请求参数

| 参数 | 类型 | 必填 | 说明 | | ---------- | ----------------------------- | ---- | -------------------------------- | | name | string | 是 | 任务名称 | | handler | (...params: any[]) => any | 是 | 回调函数，当 Native 端调用时触发 | | success | () => void | 否 | 注册函数成功回调 | | fail | (error: BridgeCode) => void | 否 | 注册函数失败回调 | | complete | () => void | 否 | 无论成功失败都会执行的回调 |

返回值

Promise<void>

示例代码

import { registerNativeApiHandler } from '@kbapp/market-partner-sdk'

// 回调形式
registerNativeApiHandler({
    name: 'CommonShare',
    handler(data) {
        console.log('Native端调用了CommonShare', data)
    },
    success() {
        console.log('注册成功')
    },
    fail(error) {
        console.error('注册失败', error)
    },
})

// Promise形式
await registerNativeApiHandler({
    name: 'CommonShare',
    handler(data) {
        console.log('Native端调用了CommonShare', data)
    },
})

invokeNativeApi

触发 App 桥接

请求参数

| 参数 | 类型 | 必填 | 说明 | | --------- | ------------------------------ | ---- | -------------------- | | name | string | 是 | 任务名称 | | params | { type: number; data?: any } | 是 | 任务参数 | | timeout | number | 否 | 设置超时时间（毫秒） | | success | (result: Result) => void | 否 | 执行成功回调 | | fail | (error: BridgeCode) => void | 否 | 执行失败回调 |

返回值

Promise<Result>

示例代码

import { invokeNativeApi, BridgeCode } from '@kbapp/market-partner-sdk'

invokeNativeApi({
    name: 'OpenActRequest',
    params: {
        type: 60500,
        data: {
            title: '分享标题',
            content: '分享内容',
        },
    },
    timeout: 5000,
    success(result) {
        console.log('调用成功', result)
    },
    fail(error) {
        if (error.errorCode === BridgeCode.TIMEOUT.errorCode) {
            console.error('调用超时')
        } else {
            console.error('调用失败', error)
        }
    },
})

invokeNativeApi({
    name: 'OpenActRequest',
    params: {
        type: 60500,
        data: {
            title: '分享标题',
            content: '分享内容',
        },
    },
    timeout: 5000,
})
    .then(() => {
        console.log('调用成功')
    })
    .catch((error) => {
        console.error('调用失败', error)
    })

isAppVersionSupport

判断当前版本号是否 大于等于 minVersion

请求参数

| 参数 | 类型 | 必填 | 说明 | | ------------ | ----------------------------- | ---- | -------------- | | minVersion | number | 是 | 最低支持版本号 | | success | (result: boolean) => void | 否 | 成功回调 | | fail | (error: BridgeCode) => void | 否 | 失败回调 |

返回值

Promise<boolean>

示例代码

import { isAppVersionSupport } from '@kbapp/market-partner-sdk'

// 回调形式
isAppVersionSupport({
    minVersion: 80711,
    success(result: boolean) {
        console.log('是否能使用', result)
    },
})

// Promise 形式
const canUse = await isAppVersionSupport({ minVersion: 80711 })
console.log('是否能使用', canUse)

getAuthToken

获取认证令牌

@version 开吧 APP：80806 开始支持，低版本需开发者做兼容处理

请求参数

| 参数 | 类型 | 必填 | 说明 | | --------- | ----------------------------- | ---- | -------- | | success | (token: AuthResult) => void | 否 | 成功回调 | | fail | (error: BridgeCode) => void | 否 | 失败回调 |

返回值

Promise<AuthResult>

示例代码

import { getAuthToken } from '@kbapp/market-partner-sdk'

// 回调形式
getAuthToken({
    success(authResult: AuthResult) {
        if (authResult.code === 0) {
            console.log('登录成功')
        }
    },
})

// Promise 形式
const authResult = await getAuthToken()
if (authResult.code === 0) {
    console.log('登录成功')
}

getAuthTokenWithSilent

静默获取认证令牌，当用户未登录时不会唤起登录界面

@version 开吧 APP：80806 开始支持，低版本需开发者做兼容处理

请求参数

| 参数 | 类型 | 必填 | 说明 | | --------- | ----------------------------- | ---- | -------- | | success | (token: AuthResult) => void | 否 | 成功回调 | | fail | (error: BridgeCode) => void | 否 | 失败回调 |

返回值

Promise<AuthResult>

示例代码

import { getAuthTokenWithSilent } from '@kbapp/market-partner-sdk'

// 回调形式
getAuthTokenWithSilent({
    success(authResult: AuthResult) {
        if (authResult.code === 0) {
            console.log('已登录，token:', authResult.token)
        } else {
            console.log('用户未登录')
        }
    },
})

// Promise 形式
const authResult = await getAuthTokenWithSilent()
if (authResult.code === 0) {
    console.log('已登录，token:', authResult.token)
} else {
    console.log('用户未登录')
}

runAction

执行统一跳转页面标准

@version 开吧 APP：80806 开始支持，低版本需开发者做兼容处理

请求参数

| 参数 | 类型 | 必填 | 说明 | | -------------- | ----------------------------- | ---- | -------- | | action | string | 是 | 动作名称 | | actionParams | Record<string, any> | 否 | 动作参数 | | success | () => void | 否 | 成功回调 | | fail | (error: BridgeCode) => void | 否 | 失败回调 |

返回值

Promise<void>

示例代码

import { runAction } from '@kbapp/market-partner-sdk'

runAction({
    action: 'pageWeb',
    actionParams: {
        url: 'https://www.baidu.com',
    },
})

defineAppShareModel

定义 app 点击转发时候的分享卡片内容

@version 开吧 APP：80806 开始支持，低版本需开发者做兼容处理

请求参数 方式 1

| 参数 | 类型 | 必填 | 说明 | | ---------- | ----------------------------- | ---- | ---------------------------- | | title | string | 否 | 分享标题 | | content | string | 否 | 分享内容 | | imageUrl | string | 否 | 分享图片 URL | | url | string | 否 | 分享链接 URL | | ... | unknow | 否 | 其他参数详情见 AppShareModel | | success | () => void | 否 | 成功回调 | | fail | (error: BridgeCode) => void | 否 | 失败回调 |

请求参数 方式 2

| 参数 | 类型 | 必填 | 说明 | | ------------ | ----------------------------- | ---- | -------------------------------------------- | | onShareApp | () => AppShareModel | 否 | 点击分享时触发的函数，返回分享模型（方式 2） | | success | () => void | 否 | 成功回调 | | fail | (error: BridgeCode) => void | 否 | 失败回调 |

返回值

Promise<void>

示例代码

import { defineAppShareModel } from '@kbapp/market-partner-sdk'

// 方式1：直接提供分享模型
defineAppShareModel({
    title: '分享标题',
    content: '分享内容',
    imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
    url: 'http://www.kaiba315.com.cn/',
    success() {
        console.log('设置成功')
    },
    fail(error) {
        console.log('设置失败', error)
    },
})

// 方式2：提供分享模型函数（点击分享时动态生成分享内容）
defineAppShareModel({
    onShareApp() {
        // 点击页面右上角或分享按钮时触发该回调，动态生成分享内容
        return {
            title: '动态生成的分享标题',
            content: '动态生成的分享内容',
            imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
            url: 'http://www.kaiba315.com.cn/?t=' + Date.now(),
        }
    },
    success() {
        console.log('设置成功')
    },
    fail(error) {
        console.log('设置失败', error)
    },
})

// Promise 形式
await defineAppShareModel({
    title: '分享标题',
    content: '分享内容',
    imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
    url: 'http://www.kaiba315.com.cn/',
})

openAppSharePanel

主动唤起分享面板

@version 开吧 APP：80806 开始支持，低版本需开发者做兼容处理

请求参数

| 参数 | 类型 | 必填 | 说明 | | -------- | --------------------------------------- | ---- | ------------------------ | | params | AppShareModel & CallbackOptions<void> | 是 | 分享模型与回调选项的组合 |

返回值

Promise<void>

示例代码

import { openAppSharePanel } from '@kbapp/market-partner-sdk'

openAppSharePanel({
    title: '开吧分享',
    content: '开吧，开汽车上新生活！',
    url: 'http://www.kaiba315.com.cn/',
    imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
    success() {
        console.log('打开分享面板成功')
    },
    fail(error) {
        console.log('打开分享面板失败', error)
    },
})

onAppSharePanelShow

监听分享面板打开时触发（主动和被动）

@version 开吧 APP：80806 开始支持，低版本需开发者做兼容处理

请求参数

| 参数 | 类型 | 说明 | | ---------- | ------------------------------------ | -------------------- | | callback | EventListenerOrEventListenerObject | 分享面板打开时的回调 |

返回值

// 返回函数，调用该函数取消监听
() => void

示例代码

import { onAppSharePanelShow } from '@kbapp/market-partner-sdk'

const stopHandle = onAppSharePanelShow(() => {
    console.log('分享面板打开')
})

// stopHandle() 停止监听

shareImage

分享图片

@version 开吧 APP：80806 开始支持，低版本需开发者做兼容处理

请求参数

| 参数 | 类型 | 必填 | 说明 | | ---------- | ----------------------------- | ---- | ---------------------------------------- | | imageUrl | string | 是 | 图片 URL（仅支持网络地址，jpg/png 格式） | | success | () => void | 否 | 成功回调 | | fail | (error: BridgeCode) => void | 否 | 失败回调 |

返回值

Promise<void>

示例代码

import { shareImage } from '@kbapp/market-partner-sdk'

shareImage({
    imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png',
})

getAppBaseInfo

获取开吧 App 基础信息

@version 开吧 APP：80806 开始支持，低版本需开发者做兼容处理

请求参数

| 参数 | 类型 | 说明 | | --------- | ----------------------------------- | -------- | | success | (deviceInfo: AppBaseInfo) => void | 成功回调 | | fail | (error: BridgeCode) => void | 失败回调 |

返回值

Promise<AppBaseInfo>

示例代码

import { getAppBaseInfo, AppBaseInfo } from '@kbapp/market-partner-sdk'

// 回调形式
getAppBaseInfo({
    success(deviceInfo: AppBaseInfo) {
        console.log(deviceInfo)
    },
    fail(error) {
        console.error(error)
    },
})

// Promise 形式
getAppBaseInfo().then((deviceInfo: AppBaseInfo) => {
    console.log(deviceInfo)
})

reportDAEvent

上报数据埋点

@version 开吧 APP：80806 开始支持，低版本需开发者做兼容处理

请求参数

| 参数 | 类型 | 必填 | 说明 | | ------------- | ----------------------------- | ---- | ---------------- | | eventName | string | 是 | 事件名 | | eventParams | { [key: string]: any } | 否 | 上报参数 | | eventType | 'Begin' \| 'End' | 否 | 开始结束类型传递 | | success | () => void | 否 | 成功回调 | | fail | (error: BridgeCode) => void | 否 | 失败回调 |

返回值

Promise<void>

示例代码

import { reportDAEvent } from '@kbapp/market-partner-sdk'

reportDAEvent({
    eventName: 'event_name',
    eventParams: {
        test_param: 'test_value',
    },
    success() {
        console.log('上报成功')
    },
})

requestPayment

唤起支付

@version 开吧 APP：80806 开始支持，低版本需开发者做兼容处理

请求参数

| 参数 | 类型 | 必填 | 说明 | | ------------- | ----------------------------- | ---- | ----------------------------------------------------------------- | | payFee | number | 是 | 支付金额，单位分 | | orderCode | string | 是 | 订单 code（商户订单 UK） | | payChannel | number | 是 | 支付渠道 1: 支付宝 2: 微信（20260115 暂不支持微信支付） | | subjectName | string | 是 | 订单展示名称 | | partnerKey | string | 是 | 约定的商户标识 | | notifyUrl | string | 否 | 支付完成回调地址 | | expireTime | number | 否 | 订单过期时间，13 位毫秒数的绝对时间戳，不传默认当前时间 + 15 分钟 | | success | (result: Result) => void | 否 | 成功回调 | | fail | (error: BridgeCode) => void | 否 | 失败回调 |

返回值

Promise<{
    /** 支付结果 0: 成功 1: 失败 */
    result: 0 | 1
    /** 支付结果描述 */
    msg: string
    /** 支付成功时返回支付订单号, 失败不返回 */
    fundsCode: string
}>

示例代码

import { requestPayment } from '@kbapp/market-partner-sdk'

requestPayment({
    payFee: 1,
    orderCode: 'xxxx',
    payChannel: 1,
    partnerKey: 'xxxx',
    subjectName: 'xxxx',
    success(result) {
        console.log(result)
    },
    fail(error) {
        console.error(error)
    },
})

requestRefund

申请退款

@version 开吧 APP：80806 开始支持，低版本需开发者做兼容处理

请求参数

| 参数 | 类型 | 必填 | 说明 | | ------------ | ----------------------------- | ---- | ------------------------ | | orderCode | string | 是 | 订单 code（商户订单 UK） | | partnerKey | string | 是 | 约定的商户标识 | | fundsCode | string | 是 | 支付成功时返回支付订单号 | | success | (result: Result) => void | 否 | 成功回调 | | fail | (error: BridgeCode) => void | 否 | 失败回调 |

返回值

Promise<{
    /** 0: 成功 1: 失败 */
    result: 0 | 1
    /** 结果描述 */
    msg: string
}>

示例代码

import { requestRefund } from '@kbapp/market-partner-sdk'

requestRefund({
    orderCode: 'xxxx',
    partnerKey: 'xxxx',
    fundsCode: 'xxxx',
    success(result) {
        console.log(result)
    },
    fail(error) {
        console.error(error)
    },
})

数据模型

AuthResult

认证结果数据模型

class AuthResult {
    /** 状态码 0 成功, 1: 未登录, 2: 取消登录, 3: 获取token失败 */
    code!: 0 | 1 | 2 | 3

    /** 登录凭证, 当 code === 0 的时候返回 */
    token!: string
}

AppBaseInfo

App 基础信息数据模型

class AppBaseInfo {
    /** 例如iOS */
    do!: string

    /** 例如iPhone11,2 */
    db!: string

    /** 例如15.5 */
    dv!: string

    /** 版本号.例如69011 */
    vcode!: number

    /** 版本号.例如6.90.11 */
    v!: string

    /** 未知 */
    source!: number

    /** 电台id */
    siteId!: number

    /** 用户id.当登录时返回 */
    userId?: number

    /** 未知 */
    cid!: string
}

AppShareModel

应用分享模型

class AppShareModel {
    /**
     * 标题
     */
    title!: string

    /**
     * 文字内容
     */
    content?: string

    /**
     * 图片
     */
    imageUrl!: string

    /**
     * 分享链接
     */
    url!: string

    /**
     * 分享功能是否开启. 默认为 true.
     * 当分享功能关闭时, 其他分享相关字段均无效.
     */
    enabled?: boolean

    // -------------------------------------------------------

    /**
     * 海报分享标题.
     * 客户端: 海报分享必须. 若不存在则取 {@link #title}, 若也不存在, 则海报分享功能关闭.
     * H5: 非必填. 通过桥接给到客户端时, 建议可以只填充 {@link #title}.
     * 后端: 非必填.
     */
    posterTitle?: string

    /**
     * 海报分享内容.
     * 客户端: 非必须. 若不存在则取 {@link #content}, 若也不存在, 则海报只有标题内容.
     * H5: 非必填. 通过桥接给到客户端时, 建议可以只填充 {@link #content}.
     * 后端: 非必填.
     */
    posterContent?: string

    /**
     * 海报分享封面图.
     * 客户端: 海报分享非必须. 若不存在则取 {@link #imageUrl}, 若也不存在, 则海报无封面.
     * H5: 非必填. 通过桥接给到客户端时, 建议可以只填充 {@link #imageUrl}.
     * 后端: 非必填.
     */
    posterUrl?: string

    /**
     * 海报分享的展示时间.
     * 客户端: 海报分享非必须. 若不存在则海报不展示时间.
     * H5: 非必填. 通过桥接给到客户端时, 建议忽略该字段.
     * 后端: 非必填.
     */
    posterTime?: string

    /** 海报分享展示时间格式. */
    posterTimeFormat?: string

    /**
     * 海报分享功能是否开启. 默认为 false.
     * 当海报分享功能关闭时, 其他海报分享相关字段均无效.
     */
    posterEnabled?: boolean

    // -------------------------------------------------------

    /**
     * 分享小程序设置: 小程序原始ID.
     * 获取方法: 登录小程序管理后台-设置-基本设置-帐号信息.
     *
     * 当此字段非空时, 客户端会显示 '分享至小程序' 功能. 详见微信小程序分享文档:
     * https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/share.html
     */
    wxMiniUserName?: string

    /**
     * 分享小程序设置: 小程序页面路径.
     */
    wxMiniPath?: string

    /**
     * 分享小程序设置: 额外信息.
     * 通常开发者希望分享出去的小程序被二次打开时可以获取到更多信息, 例如群的标识.
     */
    wxMiniShareTicket?: boolean

    /**
     * 分享小程序设置: 小程序的类型.
     * 0为正式版, 1为测试版, 2为体验版.
     */
    wxMiniType?: number
}

BridgeCode

错误码枚举

| 常量 | 值 | 说明 | | ----------------------------------- | ----------------------------------------------------- | ------------------- | | BridgeCode.UNKNOWN | { errorCode: 1000, errorMsg: '未知错误' } | 未知错误 | | BridgeCode.UNSUPPORTED_VERSION | { errorCode: 1001, errorMsg: '当前开吧版本不支持' } | 当前开吧版本不支持 | | BridgeCode.TIMEOUT | { errorCode: 1002, errorMsg: '执行超时' } | 执行超时 | | BridgeCode.UNSUPPORTED_BRIDGE_ENV | { errorCode: 1003, errorMsg: '请在开吧app内执行' } | 请在开吧 app 内执行 |

IS_KB_APP_ENV

环境检测常量，用于检测当前是否在开吧 App 内运行

类型

export const IS_KB_APP_ENV: boolean

说明

该常量通过检测 User-Agent 中是否包含开吧 App 的特征字符串来判断当前环境是否在开吧 App 内运行。

示例代码

import { IS_KB_APP_ENV } from '@kbapp/market-partner-sdk'

if (IS_KB_APP_ENV) {
    console.log('当前在开吧App内运行，可以使用SDK功能')
} else {
    console.log('当前不在开吧App内运行，可能需要降级处理')
}

常见问题

1. 桥接触发无反应：请检查当前是否处于开吧 App 内，以及当前网页是否在白名单内