xybAgent 说明文档

Appearance

简介 ​

最新版本 ​

  • npm版本：0.0.32
  • jssdk版本：2.0.10

安装 ​

npm install @xybplugins/xyb-agent@latest --save -dev

使用场景 ​

湘易办JSSDK为h5微应用/uni-app应用提供了数据追踪埋点等业务API（会持续扩展底层通用组件的适配能力），帮助开发者相关业务场景实现。此文档面向开发者介绍该JSSDK如何使用及相关注意事项。

环境适配说明 ​

该JSSDK仅支持在湘易办APP内的小程序/小程序通过webview嵌套的H5页面，其余环境的H5，只支持初始化、埋点上报；

环境名称是否支持jssdk文件最低版本号npm包最低版本号备注
湘易办APP-小程序✅1.1.40.0.4完全支持
湘易办APP-小程序-webview✅1.1.80.0.4完全支持
湘易办APP-webview✅2.0.00.0.4大部分支持
三方小程序❌--不支持

💡注意事项 ​

  • SDK有使用ES6语法，若使用环境非uni-app的话，需支持babel等兼容工具，更建议项目切换到uni-app进行搭配使用
  • 自动上报页面事项ID：在页面切换时，会自动进行页面事项ID上报；且需在调用时，将页面事项ID的路径映射关系传入SDK
  • 插件初始化默认是测试环境，会自动根据当前环境进行切换，如果需要更改上报的环境，可自行在初始化时传入环境类型

通过小程序webview嵌套的H5，可以直接使用该SDK进行原生能力调用，但小程序的webview需要按照SDK要求进行配置，参照：小程序webview配置

  • 推荐项目使用uni-app框架，否则部分功能可能导致异常
  • 不要在pages.json中设置navigationStyle配置项，否则可能会导致小程序的胶囊按钮无法显示
  • 若小程序有提示版本差异的弹窗，可在manifest.json-源码视图-app-plus配置，添加代码：
javascript
compatible:{
  ignoreVersion:true
}
  • 若编译为H5时，需要注意manifest.json-Web配置-运行的基础路径配置，一般配置为./ 或者 H5的文件夹名即可，否则会导致静态资源无法获取

准备工作 ​

工程化 ​

  • Vue实例全局挂载 - npm包 【🔥🔥🔥推荐】

可以直接在脚本层直接使用this.$xybAgent.xxx来调用对应的API，使用成本低

javascript
import App from './App'
import Vue from 'vue'
import xybAgent from '@xybplugins/xyb-agent';

import './uni.promisify.adaptor'

Vue.config.productionTip = false
Vue.prototype.$xybAgent = xybAgent;
App.mpType = 'app'
const app = new Vue({
  ...App
})
app.$mount()
javascript
import {createSSRApp} from 'vue';
import xybAgent from '@xybplugins/xyb-agent';

export function createApp() {
  const app = createSSRApp(App)
  app.config.globalProperties.$xybAgent = xybAgent;
  return {
    app
  }
}
  • Vue实例全局挂载 - js-sdk文件

可以直接在脚本层直接使用this.$xybAgent.xxx来调用对应的API，使用成本低

javascript
import App from './App'
import Vue from 'vue'
import xybAgent from './$DIR/xybAgent-$VERSION.esm.js';

import './uni.promisify.adaptor'

Vue.config.productionTip = false
Vue.prototype.$xybAgent = xybAgent;
App.mpType = 'app'
const app = new Vue({
  ...App
})
app.$mount()
javascript
import {createSSRApp} from 'vue';
import xybAgent from './$DIR/xybAgent-$VERSION.esm.js';

export function createApp() {
  const app = createSSRApp(App)
  app.config.globalProperties.$xybAgent = xybAgent;
  return {
    app
  }
}
javascript
import App from './App'
import Vue from 'vue'
import xybAgent from '@xybplugins/xyb-agent';

import './uni.promisify.adaptor'

Vue.config.productionTip = false
Vue.prototype.$xybAgent = xybAgent;
App.mpType = 'app'
const app = new Vue({
  ...App
})
app.$mount()
javascript
import {createSSRApp} from 'vue';
import xybAgent from '@xybplugins/xyb-agent';

export function createApp() {
  const app = createSSRApp(App)
  app.config.globalProperties.$xybAgent = xybAgent;
  return {
    app
  }
}
  • UNI-APP 全局挂载方案 🙅🏻‍♀️ 【不推荐】

虽说可以挂载到全局，但是使用成本过高，需要在每个页面都去获取实例信息，再一层层取值

vue
<script>
  import xybAgent from './$DIR/xybAgent-$VERSION.esm.js'

  export default {
    onLaunch() {
      this.globalData = {
        xybAgent: xybAgent
      }
    },
  }
</script>
vue
<script>
  import xybAgent from '@xybplugins/xyb-agent'

  export default {
    onLaunch() {
      this.globalData = {
        xybAgent: xybAgent
      }
    },
  }
</script>

非工程化 ​

在index.html，添加script标签并执行引入；会自动挂载到window上；非浏览器环境不要使用这种方式

html

<script src="./$DIR/xybAgent-$VERSION.umd.js"></script>

🐞文档/API 纠错 ​

微信联系：Christal_welt 备注：xybAgent SDK