Webfunny Event Node SDK

Webfunny事件上报Node.js SDK。

安装

npm install webfunny-event-node-sdk-public

快速开始

import { initWebfunnySDK, webfunnyEvent } from 'webfunny-event-node-sdk-public';

// 1. 初始化SDK（只需一次）
initWebfunnySDK({
  serverUrl: 'https://xxx.webfunny.cn',
  projectId: 'event_20250312_153829912',
  debug: true
});

// 2. 上报事件 - 兼容旧版调用结构
webfunnyEvent({ pro: 15 }).trackEvent({
  behaviorType: '点击',
  xingWeiMiaoShu: '点击11',
  yeMianYuMing: '首页',
  wangZhanLaiYuan: '百度',
  tuiGuangChuangYiId: '12',
  tuiGuangDanYuan: '啊啊'
}, {
  upNow: false  // false: 延迟上报（默认）, true: 立即上报
});

环境点位ID配置

// 生产环境使用 pro，开发环境使用 dev
webfunnyEvent({ 
  pro: 15,  // 生产环境点位ID
  dev: 20   // 开发环境点位ID
}).trackEvent({
  behaviorType: '测试'
}, {
  upNow: true  // false: 延迟上报（默认）, true: 立即上报
});

配置项

| 配置项 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | serverUrl | string | 是 | - | 服务端点地址 | | projectId | string | 是 | - | 项目ID | | eventSecret | string | 否 | - | 事件密钥，用于签名 | | signatureEnabled | boolean | 否 | false | 是否开启签名验证 | | batchSize | number | 否 | 10 | 批量上报大小 | | flushIntervalMs | number | 否 | 5000 | 自动刷新间隔(ms) | | maxQueueSize | number | 否 | 1000 | 最大队列大小 | | maxRetries | number | 否 | 3 | 最大重试次数 | | retryIntervalMs | number | 否 | 1000 | 重试间隔(ms) | | connectTimeoutMs | number | 否 | 5000 | 连接超时(ms) | | socketTimeoutMs | number | 否 | 10000 | 读取超时(ms) | | debug | boolean | 否 | false | 调试模式 |

WebfunnyEvent 事件对象

系统字段（we开头）

| 字段 | 类型 | 说明 | |------|------|------| | projectId | string | 项目ID（必填） | | pointId | string | 点位ID（必填） | | weUserId | string | 用户ID | | weCustomerKey | string | 客户Key | | weIp | string | IP地址 | | weCountry | string | 国家 | | weProvince | string | 省份 | | weCity | string | 城市 | | weHappenTime | number | 发生时间戳 | | weHappenDate | string | 发生日期 | | weHappenHour | string | 发生小时 | | weHappenMinute | string | 发生分钟 | | wePath | string | 页面路径 | | weFirstStepDay | string | 首次访问日期 | | weRelationPointId | string | 关联点位ID | | weRelationField | string | 关联字段 |

生命周期钩子

client.setHooks({
  beforeInit: () => {
    console.log('SDK初始化前');
  },
  afterInit: () => {
    console.log('SDK初始化后');
  },
  beforeReport: (event) => {
    console.log('上报前:', event);
    // 返回false可拦截上报
    return true;
  },
  afterReport: (response) => {
    console.log('上报后:', response);
  },
  onError: (error) => {
    console.error('上报错误:', error);
  }
});

手动刷新队列

// 同步刷新
client.flush();

// 异步刷新
client.flushAsync();

// 获取队列大小
const size = client.getQueueSize();

异常处理

import { WebfunnyEventException } from 'webfunny-event-node-sdk-public';

try {
  client.track(event);
} catch (e) {
  if (e instanceof WebfunnyEventException) {
    console.error('错误码:', e.getCode());
    console.error('错误信息:', e.message);
  }
}

发布

详见 发布.md

License

MIT