hina-cloud-js-sdk 4.0.0 → 4.0.2

package/dist/index.d.ts

@@ -1,107 +1,19 @@
-import { Monitor } from 'hina-cloud-monitor';
-export { MonitorInstance } from 'hina-cloud-monitor';
-import { WebClient } from 'hina-cloud-core';
-import { PluginBase, TrackOptions, ReportDataType, VariablesTypes, FetchParams, ResultItem, StorageDataType, RequestData, ResponseData, PageLeaveAutoTrackObject, IAnyObject, LinkerItem, SiteLinkerOptions, AbTestingOptions, VoidFn, UnKnownFn, ReportProperties, AnyFn, ReportTypes } from 'hina-cloud-types';
-export * from 'hina-cloud-types';
-import { State } from 'hina-cloud-utils';
+import { WebClient } from 'hina-cloud-js-core';
+import { FetchParams, ResponseData, PluginBase, ReportDataType, WebOptions, AbTestingOptions, IAnyObject, PluginConstructor, CommonGeneralProperties, HLatestUtmOptions, HUtmOptions, VoidFn, UnKnownFn, AnyFn, ReportTypes } from 'hina-cloud-type';
+export * from 'hina-cloud-type';
+import { AbtestBasePlugin, WebState } from 'hina-cloud-util';
+import { PerformanceOptions } from 'hina-cloud-js-monitor';
 
-declare class AbTestingPlugin extends PluginBase<TrackOptions> {
+declare class AbTestingPlugin extends AbtestBasePlugin {
     options: TrackOptions;
     context: TrackInstance;
     name: string;
-    isReady: boolean;
-    /**
-     * 浏览器平台 H5 Web
-     */
-    platform: "H5" | "Web";
-    /**
-     * 项目key
-     */
-    projectKey: string;
-    /**
-     * 本地存储名称
-     */
-    storageName: string;
     constructor(options: TrackOptions, context: TrackInstance);
-    init(): void;
-    transform(): ReportDataType<any>;
-    /**
-     * 判断类型和值是否匹配
-     * @param value
-     * @param type
-     */
-    valueMatchType(value: unknown, type: VariablesTypes): boolean;
-    /**
-     * 处理参数
-     * @param prefixLog
-     * @param params
-     * @param validateKeys
-     */
-    normalizeParams(prefixLog: string, params: FetchParams, validateKeys?: (keyof FetchParams)[]): {
-        verify_success: boolean;
-        para: FetchParams;
-    };
-    /**
-     * 发送 H_ABTestTrigger事件
-     * @param data
-     */
-    sendTriggerEvent(data: {
-        abtest_experiment_id: string;
-        abtest_experiment_group_id: string;
-    }): void;
-    /**
-     * 从本地缓存中获取实验结果
-     * @param params 实验参数对象
-     * @param list
-     */
-    getExpResult(params: FetchParams, list?: ResultItem[]): string | number | boolean;
-    /**
-     * 获取本地数据
-     * @returns
-     */
-    getStorageData(): StorageDataType | null;
-    /**
-     * 保存数据到本地
-     * @param list
-     */
-    saveResponseData(list: ResultItem[]): void;
-    /**
-     * 创建请求数据
-     * @param params
-     */
-    createRequestData(params: FetchParams): RequestData;
     /**
      * 从服务器获取数据
      * @param params
      */
     getResultFromServer(params: FetchParams): Promise<ResponseData>;
-    /**
-     * 请求服务接口获取数据
-     * @param params
-     */
-    asyncFetch(params: FetchParams): Promise<ResponseData>;
-    /**
-     * 调用方法前验证参数
-     */
-    preFetch(prefixLog: string, params: FetchParams): boolean;
-    /**
-     * 获取试验变量
-     * 忽略本地缓存，从服务端获取数据
-     * @param params
-     */
-    asyncFetchABTest(params: FetchParams): void;
-    /**
-     * 获取试验变量
-     * 读取本地缓存，缓存不存在时使用默认值
-     * @param params
-     */
-    fetchCacheABTest(params: FetchParams): void;
-    /**
-     * 获取试验变量
-     * 优先读取本地缓存，缓存不存在时从服务端获取数据
-     * @param params
-     */
-    fastFetchABTest(params: FetchParams): void;
 }
 
 declare class PageLeavePlugin extends PluginBase<TrackOptions> {
@@ -140,7 +52,7 @@ declare class PageLeavePlugin extends PluginBase<TrackOptions> {
     delHeartBeatData(storageKey?: string): void;
     isCollectUrl(): boolean;
     saveHeartBeatData(type?: string): void;
-    getPageLeaveProperties(): IAnyObject;
+    getPageLeaveProperties(): WebPageLeaveOptions;
 }
 
 declare class SiteLinkerPlugin extends PluginBase<TrackOptions> {
@@ -188,6 +100,407 @@ declare class SiteLinkerPlugin extends PluginBase<TrackOptions> {
     addClickListen(): void;
 }
 
+/**
+ * 上报数据事件
+ */
+type ReportEventsName = 'H_SignUp' | 'H_pageview' | 'H_WebClick' | 'H_WebStay' | 'H_WebPageLeave' | string;
+/**
+ * 上报数据类型
+ */
+type ReportTypesName = 'user_set' | 'user_unset' | 'user_delete' | 'user_set_once' | 'user_append' | 'user_add' | 'track_signup' | 'track' | string;
+/**
+ * 埋点配置
+ */
+interface TrackOptions extends WebOptions {
+    /**
+     * 埋点配置
+     */
+    autoTrackConfig: {
+        /**
+         * 是否开启自动点击采集(默认 true), true表示开启，自动采集 H_WebClick 事件
+         */
+        clickAutoTrack?: boolean;
+        /**
+         * 是否开启dom元素采集(默认 false) 可以是boolean类型，也可以是object类型(只对div元素有效)
+         *
+         * object类型，有如下参数：
+         *
+         * ignoreTags：忽略的标签 不可自定义，内部定义好的
+         * maxLevel：层级 默认是 1，可配置范围是 [1, 2, 3],非该范围配置值，会被当作 1 处理。
+         * 其中：['a', 'input', 'button', 'textarea']这四个元素是固定采集的
+         */
+        collectTags?: {
+            [key: string]: boolean | {
+                ignoreTags?: string[];
+                maxLevel?: number;
+            };
+        };
+        /**
+         * 开启全埋点时，配置带有指定属性的页面元素点击，自动采集点击事件(默认['hn-click'])
+         */
+        trackAttr?: string[];
+        /**
+         * 是否采集当前页面的数据(默认返回true)，返回false表示不采集当前页面,
+         * 设置这个函数后，内容为空的话，是返回false。不设置函数默认是采集所有页面。
+         */
+        isCollectUrl?: () => boolean;
+        /**
+         * 用户点击页面元素时会触发这个函数，判断是否要采集当前这个元素，返回true表示采集，返回false表示不采集。(默认true)
+         */
+        isCollectElement?: (value?: any) => boolean;
+        /**
+         * 考虑到用户隐私，这里可以设置 input 里的内容是否采集
+         * 如果返回true，表示采集 input 内容，返回false表示不采集 input 内容,(默认false)。
+         */
+        isCollectInput?: (value?: any) => boolean;
+        /**
+         * 根据特定标签添加上报的自定义字段
+         * 比如您需要给有 data=test 属性的标签的点击事件增加自定义属性 name:'aa' ，则代码如下：
+         * if(element_target.getAttribute('data') === 'test'){
+         *      return {
+         *        name:'aa'
+         *      }
+         *    }
+         */
+        addCustomProperty?: (value?: any) => any;
+        /**
+         * 是否开启页面停留采集(默认 true), true表示开启，自动采集 H_WebStay 事件
+         */
+        stayAutoTrack?: boolean;
+        /**
+         * 有效停留时长超过多少毫秒过开始采集(默认4000ms)，单位ms
+         */
+        stayDelayTime?: number;
+        /**
+         * 预置属性停留时长 event_duration 的最大值，(默认 18000s)，单位s
+         */
+        maxStayPageDuration?: number;
+        /**
+         * 是否开启页面浏览采集(默认 false)，auto 只在SDK初始化时会上报一次H_pageview事件 singlePage 路由改变时自动采集H_pageview事件
+         * 若页面中有锚点设计，需要将该配置设为 false，否则触发锚点会多触发 H_pageview 事件
+         */
+        pageviewAutoTrack?: 'singlePage' | 'auto' | false;
+        /**
+         * 自动采集web离开事件(默认 false) false object(PageLeave的配置) 默认关闭
+         */
+        pageLeaveAutoTrack?: boolean | PageLeaveAutoTrackObject;
+    };
+    /**
+     * 多域名打通插件配置项 v4版本开始支持配置项开启,v4版本之前只能通过use方法开启
+     */
+    siteLinkerConfig?: SiteLinkerOptions;
+    /**
+     * abTest插件配置
+     */
+    abTestingPluginConfig?: AbTestingOptions;
+    /**
+     * 采集当前页面的视区停留事件(默认返回 true)，返回false则不采集
+     */
+    stayAutoTrackConfig?: {
+        isCollectUrl?: () => boolean;
+    };
+    /**
+     * @deprecated
+     * 慎重使用，在未来的某个版本将不再支持该配置项。
+     *
+     * 单页面配置(默认false)，若页面中有锚点设计，需要将该配置删除，否则触发锚点会多触发 H_pageview 事件
+     */
+    isSinglePage?: boolean | (() => boolean | IAnyObject);
+    /**
+     * 是否使用app的jsBridge
+     */
+    appJsBridge?: boolean;
+    /**
+     * 是否开启 H_latest 相关的最近一次相关事件属性采集以及配置 H_url 作为公共属性，默认值为一个对象
+     * 子配置项 true 表示采集,false 表示不采集,未设置的参数取默认值
+     */
+    presetProperties?: PresetProperties;
+    /**
+     * 自定义渠道来源属性，默认为空，用户可以自定义，如['utm_account']等
+     */
+    sourceChannel?: string[];
+    /**
+     * 插件系统，v4版本开始支持用户自定义插件，具体插件开发规范参考插件文档
+     */
+    plugins?: PluginConstructor<TrackOptions>[];
+    /**
+     * 性能监控系统配置
+     */
+    performanceErrorConfig?: PerformanceOptions;
+}
+/**
+ * 采集最近一次的广告系列相关参数
+ */
+interface PresetProperties {
+    /**
+     * 是否采集 最近一次广告系列相关参数，默认值 true
+     */
+    latest_utm?: boolean;
+    /**
+     * 是否采集 最近一次流量来源类型，默认值 true
+     */
+    latest_traffic_source_type?: boolean;
+    /**
+     * 是否采集 最近一次搜索引擎关键字，默认值 true
+     */
+    latest_search_keyword?: boolean;
+    /**
+     * 是否采集 最近一次前向地址，默认值 true
+     */
+    latest_referrer?: boolean;
+}
+/**
+ * PageLeavePlugin插件参数
+ */
+interface PageLeaveAutoTrackObject {
+    /**
+     * 心跳记录刷新时间 单位秒(s) 默认值 5s
+     */
+    heartbeat_interval_time?: number;
+    /**
+     * 最大页面浏览时长 单位秒(s) 默认值 432000s (5天)
+     */
+    max_duration?: number;
+    /**
+     * 设置是否采集当前页面浏览时长, 返回 true 为需要采集，返回 false 或者不返回则为不采集
+     */
+    isCollectUrl?: (url?: string) => boolean;
+    /**
+     * 页面浏览时长自定义属性
+     */
+    custom_props?: {
+        [key: string]: any;
+    };
+}
+/**
+ * SiteLinker插件参数
+ */
+interface LinkerItem {
+    /**
+     *  配置值为打通网站网址的一部分。建议配置时配置为打通网站的域名。
+     */
+    part_url?: string;
+    /**
+     * 配置 _hnsdk 参数在 URL 的 hash 部分（即 # 后部分）还是在 URL 的 search 部分（即 # 前的 ？部分）。
+     * 必填属性，且属性值必须为布尔类型，即 true 或 false（默认建议填 false）。
+     */
+    after_hash?: boolean;
+}
+interface SiteLinkerOptions {
+    /**
+     * 该配置设置为 true 后，如果从已登录的页面跳转过来，即使当前网页已经登录，当前网页仍然会以之前网页的登录 id 再次登录。
+     */
+    re_login?: boolean;
+    /**
+     * 具体网站链接配置项
+     */
+    linker?: LinkerItem[];
+}
+/**
+ * 公共事件属性/预置属性
+ */
+interface GeneralProperties extends CommonGeneralProperties, HLatestUtmOptions {
+    /**
+     * 是否首日访问
+     */
+    H_is_first_day?: boolean;
+    /**
+     * 最近一次站外地址
+     */
+    H_latest_referrer?: string;
+    /**
+     * 最近一次站外域名
+     */
+    H_latest_referrer_host?: string;
+    /**
+     * 最近一次搜索引擎关键词 由于各搜索引擎策略不同，可能有获取不到的情况
+     */
+    H_latest_search_keyword?: string;
+    /**
+     * 最近一次流量来源类型
+     */
+    H_latest_traffic_source_type?: string;
+    /**
+     * 页面高度 滚动高度
+     */
+    H_page_height?: number;
+}
+/**
+ * user_setOnce事件
+ */
+interface UserSetOnceOptions extends HUtmOptions {
+    /**
+     * 首次访问时间
+     */
+    H_first_visit_time?: number;
+    /**
+     * 首次前向地址
+     */
+    H_first_referrer?: string;
+    /**
+     * 首次前向域名
+     */
+    H_first_referrer_host?: string;
+    /**
+     * 首次浏览器语言
+     */
+    H_first_browser_language?: string;
+    /**
+     * 首次浏览器字符
+     */
+    H_first_browser_charset?: string;
+    /**
+     * 首次搜索引擎关键词
+     */
+    H_first_search_keyword?: string;
+    /**
+     * 首次流量来源类型
+     */
+    H_first_traffic_source_type?: string;
+    [key: string]: any;
+}
+/**
+ * Web 浏览页面 H_pageview事件
+ */
+interface PageViewOptions extends HUtmOptions {
+    /**
+     * 是否首次
+     */
+    H_is_first_time?: boolean;
+    /**
+     * 页面路径
+     */
+    H_url_path?: string;
+    /**
+     * 前向地址
+     */
+    H_referrer?: string;
+    /**
+     * 前向域名
+     */
+    H_referrer_host?: string;
+    [key: string]: any;
+}
+/**
+ * Web 元素点击 H_WebClick事件
+ */
+interface WebClickOptions {
+    /**
+     * 元素类型
+     */
+    H_element_type?: string;
+    /**
+     * 元素名称
+     */
+    H_element_name?: string;
+    /**
+     * 元素ID
+     */
+    H_element_id?: string;
+    /**
+     * 元素链接地址
+     */
+    H_element_target_url?: string;
+    /**
+     * 元素内容
+     */
+    H_element_content?: string;
+    /**
+     * 元素className
+     */
+    H_element_class_name?: string;
+    /**
+     * 元素选择器
+     */
+    H_element_selector?: string;
+    /**
+     * 元素路径
+     */
+    H_element_path?: string;
+    /**
+     * 页面路径
+     */
+    H_url_path?: string;
+    /**
+     * 点击位置距网页左侧距离
+     */
+    H_page_x?: number;
+    /**
+     * 点击位置距网页顶部距离
+     */
+    H_page_y?: number;
+    /**
+     * 页面点击位置
+     * 页面 li 标签 以及 li 标签内的子标签（即叶子结点为 li 标签 或叶子结点的父节点或父父节点为 li 标签）时采集。
+     */
+    H_element_position?: number;
+    [key: string]: any;
+}
+/**
+ * Web 视区停留 H_WebStay
+ */
+interface WebStayOptions {
+    /**
+     * 视区宽度
+     */
+    H_viewport_width?: number;
+    /**
+     * 视区高度
+     */
+    H_viewport_height?: number;
+    /**
+     * 视区距顶部的位置
+     */
+    H_viewport_position?: number;
+    /**
+     * 停留时长
+     */
+    event_duration?: number;
+    /**
+     * 页面路径
+     */
+    H_url_path?: string;
+    [key: string]: any;
+}
+/**
+ * H_WebPageLeave事件
+ */
+interface WebPageLeaveOptions {
+    /**
+     * 页面地址
+     */
+    H_url?: string;
+    /**
+     * 页面路径
+     */
+    H_url_path?: string;
+    /**
+     * 页面hash
+     */
+    H_url_hash?: string;
+    /**
+     * 前向地址
+     */
+    H_referrer?: string;
+    /**
+     * 前向域名
+     */
+    H_referrer_host?: string;
+    /**
+     * 视区距顶部的位置
+     */
+    H_viewport_position?: number;
+    /**
+     * 停留时长
+     */
+    event_duration?: number;
+    [key: string]: any;
+}
+/**
+ * 埋点上报数据类型
+ */
+type ReportProperties = (PageViewOptions | WebClickOptions | WebStayOptions | WebPageLeaveOptions) & GeneralProperties & HUtmOptions;
+
 /**
  * 内置插件实例
  */
@@ -224,33 +537,28 @@ interface BuiltPluginsConfig {
 }
 
 declare class HinaTrack extends WebClient<TrackOptions> {
-    consolePrefix: string;
     /**
      * 存储对象
      */
-    store: State<TrackOptions>;
-    /**
-     * 性能监控实例
-     */
-    epmInstance: Monitor;
+    store: WebState;
     /**
      * 上报数据的dom元素 默认有 'a', 'input', 'button', 'textarea'
      */
     trackTags: string[];
     /**
-     * 事件静态公共属性
+     * 用户手动设置的公共事件属性
      */
-    presetProps: IAnyObject;
+    customProperties: IAnyObject;
+    /**
+     * 公共事件属性/预置属性
+     */
+    generalProperties: GeneralProperties;
     constructor(options: TrackOptions, useInstancing?: boolean);
     /**
      * 注册/初始化SDK
      * @param options
      */
     init(options: TrackOptions): void;
-    /**
-     * 初始化共享数据
-     */
-    initState(): void;
     /**
      * 处理配置信息
      */
@@ -259,10 +567,20 @@ declare class HinaTrack extends WebClient<TrackOptions> {
      * 更新采集的dom元素
      */
     updateTrackTags(): void;
+    /**
+     * 初始化共享数据
+     */
+    initState(): void;
     /**
      * 初始化广告参数
      */
     initAdvProps(): void;
+    /**
+     * 获取公共事件属性
+     * H_url H_url_host H_title这三个属性会变化 所以每次获取的时候 都需要重新获取
+     * @returns
+     */
+    getGeneralProperties(): GeneralProperties;
     /**
      * 应用插件
      */
@@ -318,7 +636,7 @@ declare class HinaTrack extends WebClient<TrackOptions> {
      * @param data
      * @param callback
      */
-    userSetOnce(data: IAnyObject, callback?: VoidFn): void;
+    userSetOnce(data: UserSetOnceOptions, callback?: VoidFn): void;
     /**
      * 对当前用户的属性做递增或者递减
      * @param data
@@ -328,7 +646,7 @@ declare class HinaTrack extends WebClient<TrackOptions> {
         [key: string]: number;
     }, callback?: VoidFn): void;
     /**
-     * 给数组属性添加值。通过userSet只能改变属性的值。如果这个属性是数组类型的，你不想完全改变这个值，只想做添加操作可以使用此方法。
+     * 给数组属性添加值。如果这个属性是数组类型的，你不想完全改变这个值，只想做添加操作可以使用此方法。
      */
     userAppend(data: IAnyObject, callback?: VoidFn): void;
     /**
@@ -350,19 +668,13 @@ declare class HinaTrack extends WebClient<TrackOptions> {
     registerCommonProperties(params: IAnyObject | UnKnownFn): void;
     /**
      * 获取预置属性
-     * 此方法可获取，页面地址，页面标题，前向地址，SDK 类型及版本，屏幕宽高，最近一次的相关属性
      */
-    getPresetProperties(): ReportProperties;
+    getPresetProperties(): GeneralProperties;
     /**
-     * 清空或删除指定预置属性
+     * 清空或删除指定自定义预置属性
      * @param payload
      */
     clearPageRegister(payload?: boolean | string[]): void;
-    /**
-     * 检查发送数据
-     * @param props
-     */
-    checkReportProperties(props: IAnyObject): void;
     /**
      * 自定义埋点事件
      * @param event
@@ -389,23 +701,17 @@ declare class HinaTrack extends WebClient<TrackOptions> {
      * @param callback
      * @param type
      */
-    report(data: ReportDataType<any>, callback?: AnyFn, type?: ReportTypes): void;
+    report(data: ReportDataType<ReportProperties>, callback?: AnyFn, type?: ReportTypes): void;
     /**
      * 获取上报数据
      * @param type
      * @param event
      * @param data
      */
-    getReportData<T = any>(type: string, event: string, data?: T): ReportDataType<T & ReportProperties>;
-    /**
-     * 获取通用的上报数据
-     * @param type 上报类型
-     * @param event 事件名称
-     */
-    getReportProperties(type?: string, event?: string): ReportProperties;
+    getReportData<T = any>(type: ReportTypesName, event: ReportEventsName, data?: T): ReportDataType<ReportProperties>;
 }
 type TrackInstance = InstanceType<typeof HinaTrack>;
 
 declare const hinaSdk: HinaTrack;
 
-export { HinaTrack, type TrackInstance, hinaSdk as default };
+export { type BuiltPluginsConfig, type BuiltPluginsInstanceMap, type GeneralProperties, HinaTrack, type LinkerItem, type PageLeaveAutoTrackObject, type PageViewOptions, type PresetProperties, type ReportEventsName, type ReportProperties, type ReportTypesName, type SiteLinkerOptions, type TrackInstance, type TrackOptions, type UserSetOnceOptions, type WebClickOptions, type WebPageLeaveOptions, type WebStayOptions, hinaSdk as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hina-cloud-js-sdk",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "WEB埋点SDK",
   "main": "dist/hina.full.js",
   "module": "dist/hina.esm.js",
@@ -14,23 +14,30 @@
   "author": {
     "name": "dongrudong@hinadt.com"
   },
+  "sideEffects": false,
   "license": "ISC",
   "dependencies": {
-    "hina-cloud-core": "4.0.0",
-    "hina-cloud-monitor": "4.0.0",
-    "hina-cloud-types": "2.0.0",
-    "hina-cloud-utils": "2.0.0"
+    "hina-cloud-js-core": "4.0.1",
+    "hina-cloud-type": "2.0.1",
+    "hina-cloud-util": "2.0.1"
   },
-  "buildOptions": {
-    "name": "hinaDataStatistic",
-    "fileName": "hina",
-    "formats": [
-      "esm",
-      "esm-full",
-      "cjs",
-      "global",
-      "umd"
-    ],
-    "external": []
-  }
-}
+  "devDependencies": {
+    "hina-cloud-js-monitor": "4.0.1"
+  },
+  "buildOptions": [
+    {
+      "name": "hinaDataStatistic",
+      "inputName": "index",
+      "outputName": "hina",
+      "formats": [
+        "esm",
+        "esm-full",
+        "cjs",
+        "cjs-full",
+        "global",
+        "umd"
+      ],
+      "external": []
+    }
+  ]
+}