# APM - Insight 小程序 SDK

## 使用方式

在 `app.js` 中初始化:

```js
import $$Rangers from './vender/rangers' // DataFinder
import Rangers from '@apm-insight-web/rangers-mini-sdk'

Rangers.init({
  aid: 111, // 应用 ID
  finderInstance: $$Rangers, // 如果已有，可接入 DataFinder 实例
  userId: 'xxx', // 或者直接传入用户 ID
  ...
})

App({
  onLaunch() {
    setTimeout(() => {
      Rangers.capture(new Error('oops')) // 手动捕获错误上报
    }, 1000)
    ...
  }
  ...
})
```

## API

- `init` 初始化，只能调用一次

  - 参数

  ```ts
    {
      aid: number, // 应用 ID, 必传
      finderInstance?: DataFinderInstance // DataFinder SDK 的实例
      userId?: string // 若传入 DataFinder 实例则优先检测 DataFinder 中已配置的值，否则使用传入值，不传则生成一个随机 UUID
      context?: { // 自定义维度，默认为 {}
        [key: string]: any // 注意，不可序列化的值类型在最终上报时会被丢弃
      }
    }
  ```

- `config` 修改配置

  - 参数

  ```ts
    {
      userId?: string // 修改用户 ID
      context?: { // 覆盖之前的定义的值
        [key: string]: any
      }
    }
  ```

- `report` 发送自定义事件（暂不支持）

- `capture` 手动捕获异常上报

- `addBreadcrumb` 手动记录用户行为（暂不支持）

- `sendNow` 立刻发送上报请求（清空批量上报队列）

- `context` 快速修改 context

  - 用法:

  ```js
  // 通过 config 方法修改
  Rangers.config('context', {
    foo: 'bar',
  })
  // 通过 context 属性获取值
  Rangers.context.get('foo') // => 'bar'
  // 通过 context 属性链式修改
  Rangers.context.set('foo2', 'bar').delete('foo').set('bar', 'foo')
  // 获取目前的 context 对象
  Rangers.context.toObject() // => { foo2: 'bar', bar: 'foo' }
  ```

  - 最终上报时 `context` 将会被序列化为 `Record<string, string>` 类型

## 事件

- `PageView` 当 `Page.onShow` 回调时触发
- `JsError` 当 `App.onError` | `App.onUncaughtRejection` (必须有 reason) 回调时触发，或者手动捕获

## 数据结构

### 面包屑 Breadcrumb

用于记录用户行为轨迹

```ts
enum BreadcrumbType {
  DOM = 'dom',
  HTTP = 'http',
}

enum BreadcrumbCategory {
  ROUTE = 'route',
}

interface Breadcrumb {
  type: BreadcrumbType
  level?: string
  category?: BreadcrumbCategory
  message?: string
  timestamp: number
}
```

一个路由变化面包屑

```json
{
  "type": "dom",
  "category": "route",
  "message": "pages/index/index",
  "timestamp": 1606310419183
}
```