@hz-beidou/web-sdk

beidou-js-sdk

北斗 BI 浏览器端 JS SDK。目前已升级v2版本， v1文档。

更多内容参考语雀文档

特性

v1.0.3开始支持动态加载，利用index入口（源码中的entry，一个注入器），动态插入script，获取最新主代码（源码中的src/index）。

架构

接入

推荐在自己的业务系统中引入index（即注入器），而非直接引用beidou.v2.xx.js（主代码）

模块化系统(webpack/gulp等模块方式引入)

next.js，ant-design-pro项目，example

@hz/beidou-js-sdk默认导出的是index.v2.(cjs|esm).js

import { init } from "@hz/beidou-js-sdk";

const beidouInstance = init({
    app_id: "应用id",
    app_version: "应用版本",
    // 如果有使用到next.js的内置链接，该选项需要开启用来追踪next.js的单页面应用跳转
    is_track_single_page: true,
    // 下面的一般情况请不要开启，会记录所有的用户行为，上行流量会很大
    heatmap: {
        //是否开启点击图，默认 default 表示开启，自动采集 _web_click 事件，可以设置 'not_collect' 表示关闭
        clickmap: "default",
        //是否开启触达注意力图，默认 not_collect 表示关闭，不会自动采集 _web_stay 事件，可以设置 'default' 表示开启
        scroll_notice_map: "default"
    }
});

beidouInstance.call("autoTrail");

require.js

example

requirejs(["//res.huizecdn.com/beidou-web-sdk-std/index.v2.umd.js"], function(BeidouSDK) {
    BeidouSDK.init({
        app_id: "应用id",
        app_version: "应用版本",
        // 如果有使用到next.js的内置链接，该选项需要开启用来追踪next.js的单页面应用跳转
        is_track_single_page: true,
        // 下面的一般情况请不要开启，会记录所有的用户行为，上行流量会很大
        heatmap: {
            //是否开启点击图，默认 default 表示开启，自动采集 _web_click 事件，可以设置 'not_collect' 表示关闭
            clickmap: "default",
            //是否开启触达注意力图，默认 not_collect 表示关闭，不会自动采集 _web_stay 事件，可以设置 'default' 表示开启
            scroll_notice_map: "default"
        },
    })
    
    BeidouSDK.beidou.call("autoTrail");
})

sciript标签(iife)

example

【注意】iife方式引入index注入器时，暴露在全局的名称为BeidouInject，如果引入的是主代码，名称为BeidouData

<script src="//res.huizecdn.com/beidou-web-sdk-std/index.v2.min.js"></script>

BeidouInject.init({
    app_id: "应用id",
    app_version: "应用版本",
    // 如果有使用到next.js的内置链接，该选项需要开启用来追踪next.js的单页面应用跳转
    is_track_single_page: true,
    // 下面的一般情况请不要开启，会记录所有的用户行为，上行流量会很大
    heatmap: {
        //是否开启点击图，默认 default 表示开启，自动采集 _web_click 事件，可以设置 'not_collect' 表示关闭
        clickmap: "default",
        //是否开启触达注意力图，默认 not_collect 表示关闭，不会自动采集 _web_stay 事件，可以设置 'default' 表示开启
        scroll_notice_map: "default"
    }
})
BeidouInject.beidou.call("autoTrail");

使用静态文件

# 1、随意找个目录安装包
npm install @hz/beidou-js-sdk

# 2、把 node_module/@hz/beidou-js-sdk/dist 目录下文件拷贝到自己项目静态目录中

使用

注入器的配置

注入器init方法支持一个配置sdkUrl，修改SDK的获取URL

import { init } from "@hz/beidou-js-sdk";

init({
    sdkUrl: 'dist/beidou.v2.min.js'
})

获取sdk实例

SDK目前是单例模式，可以通过以下方式获取到sdk实例的引用

beidouInstance = BeidouSDK.beidou

// 模块系统引入注入器
import { init } from "@hz/beidou-js-sdk";

const beidouInstance = init({
	// ...
});

// require.js引入注入器
requirejs(["./dist/index.v2.umd"], function(BeidouSDK) {
    // ...
    
    beidouInstance = BeidouSDK.beidou
})

// iife引入
BeidouInject.init({})

beidouInstance = BeidouInject.beidou

下面的使用都基于beidouInstance实例

自动上报

开启全埋点，SDK 就会自动追踪页面上的按钮( a button input )这种 html 标签类型 的点击情况，一旦页面某一个按钮发生了点击行为，我们就会去采集此按钮的一些信息，例如: 这个按钮的标签类型( a button input )，这个按钮的文本内容，这个按钮的 name ，这个按钮的 id 、 class 名，还有一些按钮特有的属性如 href 等。

*点击图默认只采集这些交互元素（ a input button ）

beidouInstance.call("autoTrail"); // 全局自动上报

<ul>
    <li beidou-auto-track="click_product_detail_amount_insured" beidou-prop-amount_insured="10000">
        50万
    </li>
</ul>

页面内公共属性

// 注册全局埋点
beidouInstance.registerCommonProps({
    product_id: prodId,
    plan_id: planId,
    merchant_id: partnerInfo.partnerId,
});

手动上报

beidouInstance.track('click_product_detail_amount_insured', {
    amount_insured: 10000
})

postMessage

让sdk通过postMessage向祖先window传递一些信息，主要应用场景是页面在iframe中打开。

// 配置
init({
    post_message: {
        is_track: true, // 默认开启，设置false关闭
        traget_origin: '*' // postMessage方法的targetOrigin属性
    }
})

// 祖先window接收
window.addEventListener("message", (e) => {
    console.log('message', e)
})

注意message的监听，过滤一下origin，避免来自非目标站点的MessageEvent产生错误的处理。

开发与发布

目录

  .
  ├── dist/                          // 默认的 build 输出目录
  └── src/                           // 源码目录
      ├── index.js                   // 主程序入口文件
      └── core/                      // 核心能力
  ├── examples                       // 使用案例
  ├── entry.js						 // 注入器（动态加载）
  ├── README.md
  └── package.json

core相关 core ├─basic // 基础层 │ │ log.js // 日志 │ │
│ ├─cache // 缓存 │ │ Cookie.js
│ │ Store.js │ │
│ ├─listener // 基础监听 │ │ EventListener.js │ │
│ └─sendData // 发送数据 │ BatchSend.js │ Bridge.js │ DataSend.js │ SendState.js │
│─support // 支撑层 │ ├─dataAssemble // 数据组装 │ │ BeidouEvent.js │ │ BeidouNewUser.js │ │
│ └─debug // 调试能力 │ Debug.js │
├─event // 事件层 │ ├─basicEvent // 事件基本监听 │ │ profile.js │ │ trail.js │ │
│ └─presetEvent // 预置事件处理 │ AutoExposure.js │ Heatmap.js │ ry.util.js │
└─business // 业务层 login.js

开发调试

npm run dev

更新版本号

npm version major/minor/patch

打包

npm run build

npm run build:main # 单独打包sdk主程序
npm run build:entry # 单独打包注入器

发布

这个是npm包的发布，容器化发布使用CICD

npm publish

接口说明

参考API文档