@kbapp/market-partner-sdk 0.0.1

package/README.MD

@@ -0,0 +1,661 @@
+# 开吧商城接入 SDK
+
+> 该 SDK 仅限于开吧 App 内使用
+
+## 下载
+
+npm:
+
+```js
+npm i @kbapp/market-partner-sdk
+```
+
+### 或通过 script 标签引入
+
+使用 unpkg CDN：
+
+```html
+<script src="https://unpkg.com/@kbapp/market-partner-sdk@latest/dist/index.umd.js"></script>
+```
+
+使用 jsdelivr CDN：
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@kbapp/market-partner-sdk@latest/dist/index.umd.js"></script>
+```
+
+> 通过 script 标签引入后，SDK 将作为全局变量 `kbMarket` 挂载在 window 对象上
+
+## 示例
+
+```js
+import { runAction } from '@kbapp/market-partner-sdk'
+
+const onTapRunAction = async () => {
+    runAction({
+        action: 'pageWeb',
+        actionParams: {
+            url: 'https://www.baidu.com',
+        },
+        success() {
+            console.log('执行成功')
+        },
+    })
+}
+```
+
+### 通过 script 标签引入的使用示例
+
+```js
+const onTapRunAction = async () => {
+    // 通过全局变量kbMarket访问SDK功能
+    kbMarket.runAction({
+        action: 'pageWeb',
+        actionParams: {
+            url: 'https://www.baidu.com',
+        },
+        success() {
+            console.log('执行成功')
+        },
+    })
+}
+```
+
+## API
+
+### 总览
+
+| 方法 | 说明 |
+| --- | --- |
+| `registerNativeApiHandler` | 注册提供给Native端调用的API |
+| `invokeNativeApi` | 触发App桥接 |
+| `runAction` | 执行统一跳转页面标准 |
+| `defineAppShareModel` | 定义页面分享内容 |
+| `openAppSharePanel` | 主动唤起分享面板 |
+| `reportGetui` | 上报数据埋点到个推 |
+| `getAppBaseInfo` | 获取开吧 App 基础信息 |
+| `shareImage` | 分享图片 |
+| `onAppSharePanelShow` | 监听分享面板打开事件 |
+| `isAppVersionSupport` | 检查当前App版本是否支持某个API |
+| `getAuthToken` | 获取认证令牌 |
+
+| 类/枚举 | 说明 |
+| --- | --- |
+| `BridgeCode` | 错误码枚举 |
+| `AppBaseInfo` | App 基础信息数据模型 |
+| `AppShareModel` | 应用分享模型 |
+| `AuthToken` | 认证令牌数据模型 |
+| `AuthMode` | 认证模式枚举 |
+
+### registerNativeApiHandler
+
+> 注册提供给Native端调用的API
+
+#### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `name` | `string` | 是 | 任务名称 |
+| `handler` | `(...params: any[]) => any` | 是 | 回调函数，当Native端调用时触发 |
+| `success` | `() => void` | 否 | 注册函数成功回调 |
+| `fail` | `(error: BridgeCode) => void` | 否 | 注册函数失败回调 |
+| `complete` | `() => void` | 否 | 无论成功失败都会执行的回调 |
+
+#### 返回值
+
+```js
+Promise<void>
+```
+
+#### 示例代码
+
+```js
+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` | 否 | 执行失败回调 |
+
+#### 返回值
+
+```js
+Promise<Result>
+```
+
+#### 示例代码
+
+```js
+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
+
+> 是否能用某个api(根据版本号来判断)
+
+#### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `minVersion` | `number` | 是 | 最低支持版本号 |
+| `success` | `(result: boolean) => void` | 否 | 成功回调 |
+| `fail` | `(error: BridgeCode) => void` | 否 | 失败回调 |
+
+#### 返回值
+
+```js
+Promise<boolean>
+```
+
+#### 示例代码
+
+```js
+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：80801开始支持，低版本需开发者做兼容处理
+
+#### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `mode` | `AuthMode` | 是 | 登录授权模式 |
+| `success` | `(token: AuthToken) => void` | 否 | 成功回调 |
+| `fail` | `(error: BridgeCode) => void` | 否 | 失败回调 |
+
+#### 返回值
+
+```js
+Promise<AuthToken>
+```
+
+#### 示例代码
+
+```js
+import { getAuthToken, AuthMode } from '@kbapp/market-partner-sdk';
+
+// 回调形式
+getAuthToken({
+    mode: AuthMode.Force,
+    success(authToken: AuthToken) {
+        if (authToken.code === 0) {
+            console.log('登录成功')
+        }
+    },
+})
+
+// Promise 形式
+const authToken = await getAuthToken({ mode: AuthMode.Force })
+if (authToken.code === 0) {
+    console.log('登录成功')
+}
+```
+
+
+
+### runAction
+
+> 执行统一跳转页面标准
+> @version 开吧APP：80801开始支持，低版本需开发者做兼容处理
+
+#### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `action` | `string` | 是 | 动作名称 |
+| `actionParams` | `Record<string, any>` | 否 | 动作参数 |
+| `success` | `() => void` | 否 | 成功回调 |
+| `fail` | `(error: BridgeCode) => void` | 否 | 失败回调 |
+
+#### 返回值
+
+```js
+Promise<void>
+```
+
+#### 示例代码
+
+```js
+import { runAction } from '@kbapp/market-partner-sdk';
+
+runAction({
+    action: 'pageWeb',
+    actionParams: {
+        url: 'https://www.baidu.com',
+    }
+})
+```
+
+### defineAppShareModel
+
+> 定义app点击转发时候的分享卡片内容
+> @version 开吧APP：80801开始支持，低版本需开发者做兼容处理
+
+#### 请求参数 方式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` | 否 | 失败回调 |
+
+
+#### 返回值
+
+```js
+Promise<void>
+```
+
+#### 示例代码
+
+```js
+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：80801开始支持，低版本需开发者做兼容处理
+
+#### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `params` | `AppShareModel & CallbackOptions<void>` | 是 | 分享模型与回调选项的组合 |
+
+#### 返回值
+
+```js
+Promise<void>
+```
+
+#### 示例代码
+
+```js
+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：80801开始支持，低版本需开发者做兼容处理
+
+#### 请求参数
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `callback` | `EventListenerOrEventListenerObject` | 分享面板打开时的回调 |
+
+#### 返回值
+
+```js
+// 返回函数，调用该函数取消监听
+() => void
+```
+
+#### 示例代码
+
+```js
+import { onAppSharePanelShow } from '@kbapp/market-partner-sdk';
+
+const stopHandle = onAppSharePanelShow(() => {
+    console.log('分享面板打开')
+})
+
+// stopHandle() 停止监听
+```
+
+### shareImage
+
+> 分享图片
+> @version 开吧APP：80801开始支持，低版本需开发者做兼容处理
+
+#### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `imageUrl` | `string` | 是 | 图片URL（仅支持网络地址，jpg/png格式） |
+| `success` | `() => void` | 否 | 成功回调 |
+| `fail` | `(error: BridgeCode) => void` | 否 | 失败回调 |
+
+#### 返回值
+
+```js
+Promise<void>
+```
+
+#### 示例代码
+
+```js
+import { shareImage } from '@kbapp/market-partner-sdk';
+
+shareImage({
+    imageUrl: 'https://static.kaiba315.com.cn/kaiba-logo.png'
+})
+```
+
+### getAppBaseInfo
+
+> 获取开吧 App 基础信息
+> @version 开吧APP：80801开始支持，低版本需开发者做兼容处理
+
+#### 请求参数
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `success` | `(deviceInfo: AppBaseInfo) => void` | 成功回调 |
+| `fail` | `(error: BridgeCode) => void` | 失败回调 |
+
+#### 返回值
+
+```js
+Promise<AppBaseInfo>
+```
+
+#### 示例代码
+
+```js
+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)
+})
+```
+
+### reportGetui
+
+> 上报数据埋点到个推
+> @version 开吧APP：80801开始支持，低版本需开发者做兼容处理
+
+#### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `eventName` | `string` | 是 | 事件名 |
+| `eventParams` | `{ [key: string]: any }` | 否 | 上报参数 |
+| `eventType` | `'Begin' \| 'End'` | 否 | 开始结束类型传递 |
+| `success` | `() => void` | 否 | 成功回调 |
+| `fail` | `(error: BridgeCode) => void` | 否 | 失败回调 |
+
+#### 返回值
+
+```js
+Promise<void>
+```
+
+#### 示例代码
+
+```js
+import { reportGetui } from '@kbapp/market-partner-sdk';
+
+reportGetui({
+    eventName: 'event_name',
+    eventParams: {
+        test_param: 'test_value',
+    },
+    success() {
+        console.log('上报成功')
+    },
+})
+```
+
+## 数据模型
+
+### AuthToken
+
+> 认证令牌数据模型
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `token` | `string` | 认证令牌 |
+| `userId` | `number` | 用户ID |
+| `expireTime` | `number` | 过期时间戳（毫秒） |
+
+### AuthMode
+
+> 认证模式枚举
+
+| 常量 | 值 | 说明 |
+| --- | --- | --- |
+| `AuthMode.Force` | `'force'` | 若用户未登录弹窗引导登录 |
+| `AuthMode.Silent` | `'silent'` | 静默授权模式，不会弹出登录弹窗 |
+
+### AppBaseInfo
+
+> App 基础信息数据模型
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `do` | `string` | 设备类型，例如 iOS |
+| `db` | `string` | 设备型号，例如 iPhone11,2 |
+| `dv` | `string` | 系统版本，例如 15.5 |
+| `vcode` | `number` | 版本号，例如 69011 |
+| `v` | `string` | 版本号，例如 6.90.11 |
+| `source` | `number` | 未知 |
+| `siteId` | `number` | 电台ID |
+| `userId` | `number` | 用户ID（当登录时返回，可选） |
+| `cid` | `string` | 未知 |
+
+### AppShareModel
+
+> 应用分享模型
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `title` | `string` | 分享标题 |
+| `content` | `string` | 分享文字内容（可选） |
+| `imageUrl` | `string` | 分享图片URL |
+| `url` | `string` | 分享链接URL |
+| `enabled` | `boolean` | 分享功能是否开启，默认为true。当关闭时，其他分享相关字段均无效（可选） |
+| `posterTitle` | `string` | 海报分享标题（可选）。若不存在则取title，若也不存在，则海报分享功能关闭 |
+| `posterContent` | `string` | 海报分享内容（可选）。若不存在则取content，若也不存在，则海报只有标题内容 |
+| `posterUrl` | `string` | 海报分享封面图（可选）。若不存在则取imageUrl，若也不存在，则海报无封面 |
+| `posterTime` | `string` | 海报分享的展示时间（可选）。若不存在则海报不展示时间 |
+| `posterTimeFormat` | `string` | 海报分享展示时间格式（可选） |
+| `posterEnabled` | `boolean` | 海报分享功能是否开启，默认为false。当关闭时，其他海报分享相关字段均无效（可选） |
+| `wxMiniUserName` | `string` | 分享小程序设置：小程序原始ID（可选）。获取方法：登录小程序管理后台-设置-基本设置-帐号信息。当此字段非空时，客户端会显示'分享至小程序'功能 |
+| `wxMiniPath` | `string` | 分享小程序设置：小程序页面路径（可选） |
+| `wxMiniShareTicket` | `boolean` | 分享小程序设置：是否开启分享票据，用于获取群的标识等信息（可选） |
+| `wxMiniType` | `number` | 分享小程序设置：小程序的类型，0为正式版，1为测试版，2为体验版（可选） |
+
+### BridgeCode
+
+> 错误码枚举
+
+| 常量 | 值 | 说明 |
+| --- | --- | --- |
+| `BridgeCode.UNKNOWN` | `{ errorCode: 1000, errorMsg: '未知错误' }` | 未知错误 |
+| `BridgeCode.UNSUPPORTED_VERSION` | `{ errorCode: 1001, errorMsg: '当前开吧版本不支持' }` | 当前开吧版本不支持 |
+| `BridgeCode.TIMEOUT` | `{ errorCode: 1002, errorMsg: '执行超时' }` | 执行超时 |
+
+### IS_KB_APP_ENV
+
+> 环境检测常量，用于检测当前是否在开吧App内运行
+
+#### 类型
+
+```js
+export const IS_KB_APP_ENV: boolean
+```
+
+#### 说明
+
+该常量通过检测 User-Agent 中是否包含开吧App的特征字符串来判断当前环境是否在开吧App内运行。
+
+#### 示例代码
+
+```js
+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 内，以及当前网页是否在白名单内