npm package: @fantai/account
Description: ftaccount js sdk
Author: jiagang
Latest version: 0.3.16

Fantai账号平台js sdk
---

### 使用
1、引入脚本

    <script src="https://cdn.jsdelivr.net/npm/@fantai/account/dist/ftaccount.sdk.min.js"></script>
    <script>
      const ftAccount = new FTAccount({
        address: 'xxxxxxx',
        accessId: 'xxxxxxx',
        accessKey: 'xxxxxxx',
        channel: 'WEB',
        isDev: false,
      });
      ftAccount.login('xxxxxx');
      ftAccount.log('trackId', { ...trackData });
    </script>

    // 或者直接在脚本上加上初始化参数
    <script src="https://cdn.jsdelivr.net/npm/@fantai/account/dist/ftaccount.sdk.min.js?token=xxxxxx&isDev=true"></script>
    <script>
      const ftAccount = window.ftAccount;
      ftAccount.login('xxxxxx');
      ftAccount.log('trackId', { ...trackData });
    </script>

2、模块化

安装

    npm install @fantai/account

使用

    import FTAccount from '@fantai/account';
    ...

### API
##### 创建实例
new FTAccount(options)
- **options** `Object` 必填，具体参数如下
- **options.address** `String` 可选，连接后台账户系统服务器地址，默认值为 'https://acc.fantaiai.com/v1'
- **options.accessId** `String` 必填，后台分配的app id
- **options.accessKey** `String` 必填，后台分配的app key
- **options.channel** `String` 可选，App所属渠道，取值为 WEB|ANDROID|IOS|WXAPP，默认WEB
- **options.isDev** `Boolean` 可选, 是否在开发模式，在开发模式中不向服务器发出请求，请求直接通过前端控制台输出（console.debug chrome中需要设置控制台日志等级），默认值false
- **options.token** `String|Promise<String>|{ getToken: () => String | Promise<String> }` 可选，设置自定义token，可以是固定值，或者一个包含getToken的对象（设置token的话，则不在自动管理token和account，只用作记录日志log）
- **options.ftsession** `String` 可选，对应账号系统gateway对请求做加密的方式，可选设 '3b272a70' 或者 '8191ad2e-a944-41da-bccd-a4145ee2d7a1'
- **options.autoTrack** `Boolean|Object` 可选，开启自动埋点配置，默认false


##### 实例方法
FTAccount.prototype.getAccount(userId, attribute) 获取对应账户平台用户账户，别名 FTAccount.prototype.login
- **userId** `String` 可选，应用中对应用户唯一标志，可以是第三方账户名称、设备ID、微信openid等，不填时返回上一次调用时获取的账户
- **attribute** `Object` 可选，用于注册账户时关联的一些用户属性
- **return** `Promise<Account>` 返回fantai账户平台的账户信息
>- Account.prototype.ID `String` 账户id

FTAccount.prototype.log(operation, payload) 记录用户行为日志
- **operation** `String|AccessLog` 必填，字符串时作为记录日志的operation字段，AccessLog时表示完整的日志对象，具体其中字段说明请参照 <https://code.aliyun.com/fantai/ftaccount/blob/master/ft/account.proto>
- **payload** `Object` 可选，对应operation_payload

### vue插件使用
1、引入脚本，按顺序依次引入如下脚本

    <script src="https://cdn.jsdelivr.net/npm/vue"></script>
    <script src="https://cdn.jsdelivr.net/npm/@fantai/account/dist/ftaccount.sdk.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/@fantai/account/dist/ftaccount.vue-plugin.min.js"></script>

2、模块化

    import VueFTAccount from '@fantai/account/vue-plugin';

    // 注册插件，创建并注入FTAccount实例，Vue.prototype.$ftAccount
    Vue.use(VueFTAccount, {
      address: 'xxxxxxx',
      accessId: 'xxxxxxx',
      accessKey: 'xxxxxxx',
      channel: 'WEB',
      isDev: false,
    });

    // 使用自定义埋点
    // vue 2.x 和 3.x 通用方式
    const ftAccount = VueFTAccount.useFTAccount();
    ftAccount.log('trackId', { ...trackData });

    // vue 2.x
    this.$ftAccount.log('trackId', { ...trackData });
    Vue.prototype.$ftAccount.log('trackId', { ...trackData });

    // 使用指令埋点 v-ftaccount-track，埋点数据可以是字符串或对象
    <div v-ftaccount-track:click.capture="'trackId'"> // :click指定触发埋点事件是点击事件，.capture表示事件捕获阶段触发
    <div v-ftaccount-track="{ key: 'trackId', value: { test: 1 } }">
    <div v-ftaccount-track="{ trackId: { test: 1 } }">
    <custom-component v-ftaccount-track:custom.vm="'trackId'"> // .vm表示在自定义组件上的自定义事件触发埋点


### 自动化埋点的设置说明

初始化时参数设置`autoTrack`属性以启动自动化埋点，`autoTrack`取值可以是布尔类型 `true` 表示启动自动化埋点，默认 `false` 是不启用；`autoTrack`还可以是对象类型为详细的埋点设置

    // autoTrack: true时的默认设置为
    autoTrack: {
      load: true, // 页面加载
      click: true, // 元素点击事件
      change: true, // change事件
      scroll: true, // 滚动事件
      input: true, // 文本输入事件
      focus: false, // 焦点事件
      blur: false, // 失去焦点事件
    }

每一项表示一种自定埋点的事件触发类型，还可以添加更多dom事件类型，取值 `boolean | string | ((type: string, el: Element | undefined, operation: string, payload: any) => { operation?: string, payload?: any } | false | undefined)`。
设置为`true|false`，表示对应的事件是否做埋点; `string` 表示埋点时记录的track_id（也就是operation）; 设置为`function`可以在埋点时自定义埋点值，返回 `false` 会取消这次埋点事件，返回 `{ operation?: string, payload?: any }` 对象会将其作为埋点的数据

例如自定义如下设置：

    const ftAccount = new FTAccount({
      ...
      autoTrack: {
        load: 'PAGE_LOAD',                               // 页面加载时埋点 log('PAGE_LOAD')
        input: true,                                     // 在文本框中输入时埋点
        change: false,                                   // 取消change事件埋点
        scroll: (type, el, operation, payload) => {      // 页面滚动时记录埋点 log('PAGE_SCROLL', { scrollTop: document.scrollingElement.scrollTop })
          if (el.scrollingElement.scrollTop !== 0) {
            return {
              operation: 'PAGE_SCROLL',
              payload: {
                scrollTop: el.scrollingElement.scrollTop
              },
            }
          }
          return false;
        },
      },
    });

自动化埋点的值，除了自定义以外默认的埋点值为 `operation="FT_TRACK_{TYPE}_{ELEMENT_ID}"`，其中`TYPE`是触发埋点的事件类型，`ELEMENT_ID`是触发元素的唯一标记，如果元素设置了id，直接就是这个id，否则由元素标签名、类名和元素在dom中序号确定（`load`事件例外，因为没有元素触发只记录为`FT_TRACK_LOAD`）

另外还可以通过设置元素上的data数据来自定义埋点值，设置 `data-ft-track-{TYPE}` 为自定义的`trackid`, 当 `data-ft-track` 存在时 `data-ft-track-value` 是自定义的埋点数据

例如设置 `autoTrack: true`时，页面内容如下：

    <div id="app_page" data-ft-track-load>
      <input id="testInput" type="text">
      <div class="btn">click me</div>
    </div>

当页面加载后会记录 `log('FT_TRACK_LOAD_APP_PAGE')`
当文本框内容变化时会记录 `log('FT_TRACK_CHANGE_TESTINPUT', { value: "xxx" })`
点击`div.btn`时会记录 `log('FT_TRACK_CLICK_DIV_BTN_0', { id: "DIV_BTN_0" })`

如上建议使用自动化埋点时尽量在需要记录的元素上设置唯一的id，能更容易的分析找到对应的埋点数据

### 微信授权认证

在微信环境中通过钒钛认证授权后跳转到H5页面，可以通过设置 token: 'qywx'，之前获取得到对应授权信息，此时不需要再设置 accessId 和 accessKey

例如，可以直接通过引入脚本时设置参数来做自动化埋点

    <script src="https://cdn.jsdelivr.net/npm/@fantai/account/dist/ftaccount.sdk.min.js?token=qywx&autoTrack=true"></script>