# `@deppon/deppon-log`

前端埋点工具库（自研上报，不依赖神策 SDK）

## 安装

```bash
npm install @deppon/deppon-log
```

## 基础使用

### JavaScript/TypeScript 项目

```javascript
import depponLog from '@deppon/deppon-log';

// 初始化（可覆盖默认上报地址）
depponLog.init(process.env.NODE_ENV, {
    server_url: 'https://your-api.com/salog/api/events',
    app_name: 'my-app',
    send_type: 'beacon', // beacon | fetch
});

// 自定义事件埋点
depponLog.eventTrack('button_click', {
    id: 1,
    name: 'test',
});
```

### 默认上报地址

| 环境 | 默认 `server_url` |
|------|-------------------|
| production | `https://dot.Deppon.com/salog/api/events` |
| 其他 | `https://dot.Deppon.net/salog/api/events` |

请求体为 JSON，`POST` 或 `sendBeacon`，示例：

```json
{
  "type": "track",
  "event": "button_click",
  "distinct_id": "匿名ID",
  "login_id": "登录用户ID",
  "app_name": "my-app",
  "time": 1716000000000,
  "properties": {
    "url": "https://...",
    "uuid": "...",
    "platformType": "H5"
  }
}
```

后端需实现对应接口并完成入库；字段可按平台规范扩展。

**接口详细说明见：[docs/api-events.md](./docs/api-events.md)**

## Vue 3 使用

### 1. 安装插件

```javascript
import { createApp } from 'vue';
import { VuePlugin } from '@deppon/deppon-log';
import router from './router';

const app = createApp(App);

app.use(VuePlugin, {
    router,
});

app.mount('#app');
```

### 2. 在模板中使用指令

#### 点击埋点

```vue
<template>
    <button v-log="'button_click'">点击按钮</button>
    <button v-log:property="{ id: 1, name: 'test' }" v-log="'button_click'">点击</button>
</template>
```

#### 曝光埋点

```vue
<template>
    <div v-log:exposure="'element_exposure'">内容区域</div>
</template>
```

### 3. Composition API

```vue
<script setup>
import { useLog } from '@deppon/deppon-log';

const log = useLog();

const handleClick = () => {
    log.eventTrack('button_click', { id: 1 });
};
</script>
```

## API

### 初始化配置

| 字段 | 说明 |
|------|------|
| `server_url` | 埋点上报 API（必填，可由 init 覆盖） |
| `show_log` | 非生产环境是否在控制台打印 |
| `send_type` | `beacon`（默认）或 `fetch` |
| `app_name` | 应用标识，写入上报体 |
| `enable_page_leave` | 是否采集页面离开时长，默认 `true` |

### 方法

- `init(develop, property)` - 初始化
- `eventTrack(event_name, properties, callback?)` - 自定义事件
- `eventQuick('autoTrack', properties)` - 页面浏览（`$pageview`）
- `login(user_id)` - 绑定登录用户
- `changeDistinctId(distinct_id)` - 匿名 ID

### DOM 声明式埋点（兼容旧属性名）

- `data-sensors-click-event-name` - 点击事件名
- `data-sensors-exposure-property-*` - 附加属性

## 与神策版的差异

- 已移除 `sa-sdk-javascript` 及神策热力图/曝光插件
- 上报改为自有 REST 接口（JSON），不再请求 `sa.gif`
- 页面离开事件仍为 `$WebPageLeave`，路由页浏览仍为 `$pageview`，便于后端迁移映射