# @xnsk/tracking

> 先农数科前端埋点sdk

Latest version **0.0.3** (published 2024-08-07) · ISC license · 0 weekly downloads

## Install

```sh
npm install @xnsk/tracking
pnpm add @xnsk/tracking
yarn add @xnsk/tracking
bun add @xnsk/tracking
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.3 |
| Published | 2024-08-07 |
| First published | 2023-07-19 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14 |
| Dependencies | 1 |
| Unpacked size | 568.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | qwei, lvjianqin, zhiqiang03, gzb9527, xnsk-openlayers-sdk, weiyurun |
| Keywords | xnsk, tracking, mp, h5, web |

## Links

- npm: https://www.npmjs.com/package/@xnsk/tracking
- npm.io page: https://npm.io/package/@xnsk/tracking

## Dependencies (1)

- [@xnsk/core](https://npm.io/package/@xnsk/core.md) workspace:*

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 0.0.3 (latest) — 2024-08-07
- 0.0.2 — 2023-08-01
- 0.0.2-alpha.2 — 2023-08-01
- 0.0.1 — 2023-07-20
- 0.0.1-alpha.1 — 2023-07-19

## README

# @xnsk/tracking
先农数科团队行为监控平台埋点部分的SDK，用于上报多种事件类型，支持客户端webview和浏览器。

## 安装

``` ts
// yarn 
yarn add @xnsk/tracking-sdk
// npm
npm i @xnsk/tracking-sdk
// pnpm
pnpm add @xnsk/tracking-sdk
```

## 使用

``` ts
import { Tracking } from '@xnsk/tracking-sdk';

// 初始化weblogger
const tracker = new Tracking({
  env: process.env.VUE_APP_TYPE,
  isInApp: false,
  allowEventIdList: [],
  storageLimit: {
    time: 10
    store: 20
  }
}, router);
```

## 参数说明

#### option [env]：`required`
当前环境，非生产环境开启debug模式


#### option [isInApp]：`required`
运行环境，是否在原生APP中运行，默认false
``` ts
// 初始化的时候传入
const tracker = new Tracking({
  env: process.env.VUE_APP_TYPE,
  isInApp: false,
});
```

#### option [allowEventIdList]
页面白名单，在某些特殊页面不用上报埋点数据
``` ts
// 初始化的时候传入
const tracker = new Tracking({
  env: process.env.VUE_APP_TYPE,
  isInApp: false,
  allowEventIdList: ['eventIdA', 'eventIdB', 'eventIdC']
});
```

#### option [storageLimit]

> __option [storageLimit] [time]__

> __option [storageLimit] [store]__

缓存配置，默认触发条件（一条满足即可）：
- option [storageLimit] [time]: 每10s内上传一次；
- option [storageLimit] [store]: 本地存储到达20条数据上传一次；

``` ts
// 初始化的时候传入
const tracker = new Tracking({
  env: process.env.VUE_APP_TYPE,
  isInApp: false,
  allowEventIdList: ['eventIdA', 'eventIdB', 'eventIdC'],
  storageLimit: {
    time: 10
    store: 20
  }
});
```

#### [router]
用于做路由跳转时上报page类型的事件
``` ts
import VueRouter from 'vue-router'

// 项目路由配置
const router = new VueRouter({
  mode: 'hash',
  base: process.env.BASE_URL,
  routes: [{
    path: '/demo',
    component: (resolve) => require(['@/views/Demo.vue'], resolve),
    meta: {
      title: 'Demo页面Title'，
      trackEventId: ''  // 埋点配置平台中配置的eventId
    }
  }],
})

// 初始化埋点实例
const tracker = new Tracking({
  env: process.env.VUE_APP_TYPE,
  isInApp: false,
  allowEventIdList: [],
  storageLimit: {
    time: 10
    store: 20
  }
}, router);

// 挂载到Vue全局
Vue.prototype.$tracker = tracker;
```
## web端接入说明  

#### 1. web端需要补充部分通用字段（commons），作为SDK上报数据时使用，包含  
    
    - deviceId: 设备标识，目前xnsk_web_code使用的token  
    - appId: 项目ID，目前xnsk_web_code使用的appCode  
    - userId: 用户ID  
    - orgCode: 区域code  
    - env: 运行环境（SDK会截取前3个字符）  
    
#### 2. 补充方式  
注入到localStorage的`__XNSK_TRACKING_DATA__`项中（xnsk_web_code已添加，路径：src/util/index.js）  
#### 3. 补充时机
理论上应该是登录成功时注入，但目前xnsk_web_code登录只存了token，userinfo是初始化菜单时获取的，所以目前方案是在src/pages/mainPage/index.vue的initMenu中注入数据（enterprise入口暂未添加）   
#### 4. 登录埋点问题
因为上面3的原因，导致无法在登录按钮处上报登录点击埋点，目前是做的路由劫持，如果从登录页面进入，则上报登录点击埋点（后期优化）
#### 5. 其他字段
其他字段（如经纬度、项目版本号）也可以注入commons中，由于目前版本号未维护，经纬度web端也无法直接获取，暂时未上报
    

## 其他非Vue技术栈的场景

#### 手动上报，支持的API有：`click`, `page`, `requst`；
``` ts
// 点击事件
tracker.click('eventId', option);
// 页面事件
tracker.page('eventId', option);
// 自定义上报
tracker.request('eventId', option);


```

## TODO

---
_Source: https://npm.io/package/@xnsk/tracking · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
