@datafinder/embed-sdk
Version:
Embed SDK for DataFinder
147 lines (113 loc) • 8.8 kB
Markdown
# @datafinder/embed-sdk 使用文档
## 简介
UBA（Finder）应用包含一些较为通用的功能（例如看板，报表，用户细查等），需要被外部页面嵌入，外部页面包括字节内部（例如 Finder）和外部（例如私有化用户）。因此 UBA 提供了该 SDK 用于 Finder 子模块的统一接入。
## 安装
### 通过 npm 包接入
```bash
# npm
npm i -S @datafinder/embed-sdk
# yarn
yarn add @datafinder/embed-sdk
# pnpm
pnpm add @datafinder/embed-sdk
```
## 快速开始
### 示例：渲染用户分析应用
```typescript
import * as EmbedSDK from '@datafinder/embed-sdk';
EmbedSDK.render({
// 自定义渲染页面的容器元素，例如
targetNode: document.queryElementById('finder-app'),
// finder 应用 id
appId: 164154,
// 页面 ID
page: 'behavior-detail',
// 不启动桥接的跨域请求
crossOrigin: false,
// 其他自定义参数
basePath: '/fedev-embed-behavior-detail',
from: 'tester',
customRequestHeaders: {
'X-Tester-Source': 'tester',
},
});
```
## API 参考
**render(options: EmbedRenderOptions)**
**函数功能**
渲染增长分析集成页面
**函数声明**
```typescript
function render(options: EmbedRenderOptions): void;
```
**参数说明**
- 该函数的参数说明如下。
| **参数名称** | **参数类型** | **必填** | **说明** |
| :-------------------- | :----------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| targetNode | HTMLElement | 是 | 渲染 Finder 应用的容器 |
| appId | number | 是 | 嵌入的 Finder 应用 ID |
| projectId | number | 是 | 嵌入的 Finder 项目 ID ，项目Id和应用ID(appId)必填一个 |
|host | string | 否 | 嵌入的 Finder 页面 Host，如置空则默认为同域，并使用当前环境的 host- host 参数目前需要指定协议头或 '//'_例如需要接入 xxx.datarangers-onpremise.volces.com 提供的 Finder 页面，传入 host: "//xxx.datarangers-onpremise.volces.com"_ |
| basePath | string | 否 | Finder 应用的路径。默认是 '/datafinder' |
| crossOrigin | boolean | 否 | 嵌入页面是否跨域。默认会根据传入的 host 自动判断 |
| dorToken | string | 否 | 如传入了 dorToken，则会通过 dorToken 作为鉴权方式渲染页面 |
| from | string | 否 | 接入方来源。保留字段，SDK 预留 |
| needsMinibaseRedirect | boolean | 否 | 是否需要 minibase 的重定向 |
| proxyPath | string | 否 | 嵌入页面中 Finder 请求代理的接口地址，在 crossOrigin 为 true 时使用 |
| page | EmbedPage | 否 | 嵌入的 Finder 模块页面 |
| customRequestHeaders | Record<string, string> | 否 | 嵌入页面内请求的自定义 headers |
| embedQueryParams | | 否 | filter_id: 传入筛选器参数;hideTitleAndOps;隐藏整个头部 hideBelongTo; 隐藏图表的所属人 hideTitle; 隐藏看板标题 hideOpActions; 隐藏操作区按钮 |
| iframeOptions | HTMLIFrameElement | 否 | 渲染 iframe 节点时的自定义 attrs。默认为 { width: '100%', height: '100%', frameBorder: '0' } |
| onSuccess | () => void | 否 | 嵌入页面渲染成功时的回调 |
| onError | (reason: string) => void | 否 | 嵌入页面渲染失败时的回调 |
| onFinish | (data: unknown) => void | 否 | 嵌入页面完成功能后的回调- 分群编辑页： 分群保存成功后触发 |
**page 参数说明**
目前支持嵌入的页面列表：
- dashboard
- report
- behavior-detail
- user-cohort/edit-cohort/:type/:id
| **页面** | **参数值** | **说明** |
| :-------------------------------- | :------------------------ | :----------- |
| dashboard | dashboard | 看板页面 |
| report | report | 单独报表页面 |
| behavior-detail | behavior-detail | |
| user-cohort/edit-cohort/:type/:id | user-cohort/edit-cohort/4 | |
**返回值**
无
**示例**
- 渲染用户分析应用（同域）
```typescript
import * as EmbedSDK from '@datafinder/embed-sdk';
EmbedSDK.render({
// 渲染页面的容器元素
targetNode: document.queryElementById('finder-app'),
// finder 应用 id
appId: 164154,
// 页面 ID
page: 'behavior-detail',
// 不启动跨域请求
crossOrigin: false,
// 其他自定义参数
from: 'tester',
customRequestHeaders: {
'X-Tester-Source': 'tester',
},
});
```
- 外部用户嵌入 Finder 看板（跨域）
```typescript
import * as EmbedSDK from '@datafinder/embed-sdk';
EmbedSDK.render({
// 渲染页面的容器元素
targetNode: document.queryElementById('finder-app'),
appId: 214032,
host: '//e168-6-120finder.datarangers-onpremise.volces.com',
basePath: '/datafinder',
page: 'dashboard',
dashboardId: '7118932524570509838',
crossOrigin: true,
proxyPath: `/datafinder/openapi/v1/10000000/dashboard_requests`,
filterId: 29,
});
```