斐波那契 SDK 接入文档

更新日志

2017 年 02 月 18 日完善基础接入步骤
2018 年 06 月 20 日 init 增加 apptype, unionid, userid 字段
2018 年 07 月 24 日增加 pfid 权限 function 字段
2019 年 06 月 29 日增加 saudid 字段处理逻辑
2020 年 02 月 21 日增加 identitys、platform 字段处理多客户身份逻辑
2020 年 09 月 07 日增加自定义采集的事件和事件属性 pushCustomEvent 自定义事件上报方法
2020 年 10 月 16 日增加 contenttype 字段
2020 年 11 月 15 日增加 enterPage, leavePage 事件
2020 年 12 月 22 日增加 dealUrl 函数自定义分享来源 from 字段
2022 年 04 月 28 日将外部 mpid 收入到 identitys 数组内，删去 openid 和 unionid

正文

1. SDK 使用步骤

1.1 步骤一：引入 JS 文件

将下面的代码加在<body>中，在调用斐波那契 SDK 接口之前加载。

<script
  type="text/javascript"
  src="https://res.fibodata.com/data/fibosdk-v2.min.js"
></script>

1.2 步骤二：通过 init 接口初始化

为了能够正常使用 SDK 接口，必须首先调用 init 接口进行初始化（建议接入微信网页授权，并在成功之后调用）， init 接口返回值为一个 Promise 对象。

注意事项：请确保编码格式为 utf-8，以保证传入的授权信息不会出现乱码。

var fibo = fiboSDK.init({
  pfid: "", // （必须）斐波那契分配的平台id
  appid: "", // （必须）1-50位，数字，大小写字母，下划线，短横线）场景载体id，一般指作品id
  apptype: "", // （必须）应用类型，外部作品=xapp、长页=longpage、翻页=multipage、短视频=shortvideo、产品=productinfo、上传文件=uploadfiles、上传视频=uploadvideo
  contenttype: "", //(非必须)应用子类型，用于区分内容类型，例如：information（资讯）
  userInfo: {}, // （非必须）如果有微信授权并能拿到用户信息，则必须填入微信公众号网页授权获取的用户信息JSON对象；支持传入用户字段管理下"已启用"的用户信息
  title: "", // （非必须）页面标题，因为在微信 pc 端内置浏览器使用 document.title 获取 title 会异常，所以建议直接传入
  independent: true //（非必须）表示是否在初始化时自动推送view事件和userInfo事件，默认值为 true
  identitys: [{
    identityType: "", //（非必须）用户身份类型，如openid（微信openid）、 unionid（微信openid）、phone（手机号）或自定义的用户身份等，自定义的用户身份在导入前需要先在工作台创建
    identityValue: "", //（非必须）用户身份的取值，如微信openid的具体取值
    platform: "", //（非必须）平台类型，枚举值——gzh（微信公众号）、contentminiapp（微信小程序）、workwechat（企业微信-第三方应用）、selfbuilt（企业微信-自建应用）、workwechat_employee（企业微信-员工）、              YOUZAN（有赞）、EZR（驿客）、RP_LSY（零售云）、EXTERNAL（自建应用）
    mpid: "", //（非必须）应用id，如公众号appid、小程序appid、企业微信corpid、自建应用id等
    isWeChatEcosystem: "" //（非必须）是否微信生态（传了mpid必须传此参数），isWeChatEcosystem=true｜false
  }] // （非必须）客户多身份类型标识，可以传入多组（最多支持五组）
});


// init 接口的返回值为一个Promise对象，可以调用 then 方法实现相应的业务逻辑。
fibo.then(function(initData) {
  // 分享链接，将需要分享的链接传入fiboSDK.dealUrl()
  var shareLink = fiboSDK.dealUrl(location.href);
  ...
}, function(err){

});

2. SDK 接口

2.1 微信分享事件

使用场景：

接入后可以看到作品的传播途径，微信朋友圈、微信朋友消息等各种方式所占比例
作品在各个时间段的分享率
传播的层级，各层级所占比例

如果需要监测作品在微信生态的传播，需要引入微信的 JS-SDK。具体的引入方式可以直接查看微信 JS-SDK 说明文档

在微信定义的几个分享接口中，对分享链接 link 和分享成功回调函数 success 接入斐波那契监测代码；在分享到朋友圈( wx.onMenuShareTimeline )或分享给好友( wx.onMenuShareAppMessage )时，对分享链接 link 调用 dealUrl 函数可以增加自定义分享来源字段（"timeline" 或 "singlemessage"）例如分享到朋友圈：

wx.onMenuShareTimeline({
  title: "", // 分享标题
  // 分享链接，将需要分享的链接传入fiboSDK.dealUrl()
  // 如果 shareurl 是当前页面的链接，请务必保留链接上可能存在的特定参数，
  // 如：actid、stepid、cnl、cnltype、lc、sui
  // 如果 shareurl 是由程序生成的其它链接，请将当前页面链接上可能存在的
  // 参数（actid、stepid、cnl、cnltype、lc、sui）也拼接到此链接上
  link: fiboSDK.dealUrl(shareurl, "timeline"), // 当分享到朋友圈时，增加自定义分享来源字段 timeline
  imgUrl: "", // 分享图标
  success: function () {
    //用户确认分享后执行的回调函数，需要调用fiboSDK.share()并传入对应的分享渠道
    fiboSDK.share("timeline");
  },
  cancel: function () {
    // 用户取消分享后执行的回调函数
  },
});

分享渠道和需要传入 fiboSDK.share()的值对应如下：

分享渠道	对应的值
朋友圈	timeline
朋友	friend
QQ	qq
腾讯微博	txweibo
QQ 空间	qzone

2.2 按钮点击事件

使用场景：通过接入按钮点击事件，可以获取到按钮的点击次数和转化率。

对于需要记录点击次数的按钮或者 a 标签里的跳转链接，需要在待点击的元素上绑定 click 事件并调用 fiboSDK.btnClick(buttonId,buttonName)，其中参数 buttonId 为按钮识别 id，buttonName 是该按钮的名称，例如：

/**
 * 推送用户点击事件
 * @param {string} btnId 按钮ID
 * @param {string} btnName 按钮名称
 * @param {string} type 按钮类型，'longclick'(长按) | 'NULL'(点击)，默认'NULL'
 * @param {object} dataArgs 附加数据，JSON对象
 */
function btnClick(
  btnId: string,
  btnName: string,
  type?: string,
  dataArgs?: Record<str, any>
) {}

/**
 * 推送用户点击事件
 * @param {string} btnId 按钮ID
 * @param {string} btnName 按钮名称
 * @param {object} dataArgs 附加数据，JSON对象
 */
function btnClick(
  btnId: string,
  btnName: string,
  dataArgs?: Record<str, any>
) {}

<a
  href="http://www.baidu.com"
  onclick="fiboSDK.btnClick('button1', '跳到百度')"
></a>

或者：

<script>
  function buttonClick() {
    //登录流程...
    fiboSDK.btnClick("button2", "登录按钮");
  }
</script>
<button onclick="buttonClick()">登录</button>

如果需要统计多个不同按钮的点击次数，buttonId 必须不同。如果两个不同的按钮传入同一个 buttonId，会算成同一个按钮的点击事件。 dataArgs 为 JSON 对象，只能存储基础数据类型的数据，序列化后总长度最多 800 字符

为了防止 buttonId 与其他作品的冲突，导致统计混乱，建议使用 `${appid}${buttonId}` 的形式作为 buttonId 传入。

2.3 自定义表单推送

使用场景：推送自定义表单后，可以及时获取收集到的表单数据。

对于需要提交表单信息的作品，可以推送表单信息，表单的格式必须是键值对。

注意事项：表单的键值都必须是字符串。

使用 saveFormInfo(formInfo, version) 接口。

  var form = { "姓名": "张三", "手机": "13512345678" };
  fiboSDK.saveFormInfo(form, "1");

2.5 操作结果事件

使用场景：用户在页面内完成某项操作，或调用外部接口完成操作，当下无法马上记录此操作带来的结果/状态变化，需要等服务器返回数据后，前端得到数据再传输给斐波。

例如：邀请有奖场景中，用户参与活动填写并提交表单后，后端验证并返回获奖信息时，前端调用此事件

var opInfo = { operation: "getAward" };
fiboSDK.opState(opInfo);

// 如果操作有额外的业务数据需要存储
var opInfo = { operation: "getAward" };
var dataArgs = { userId: "xxxx" };
fiboSDK.opState(opInfo, dataArgs);

其中 opInfo 是存储操作结果信息的容器对象，支持任意传入任意键值对（方便后期的字段扩展），但具体要传到 fibo 的有效字段由 opState 的代码内部进行确定。目前确定的有效字段有：

operation
ownerOpenid

dataArgs 为 JSON 对象，只能存储基础数据类型的数据，序列化后总长度最多 800 字符

2.6 处理 url 参数

使用场景：用户在分享时，处理分享链接，添加或修改 url 中的 lc、sui、cnl、cnltype、from 等参数。

注意事项：在调用此方法前，一定要保证已经成功的调用 fiboSDK.init 接口完成了 SDK 的初始化，如果分享链接是当前页面的链接，请务必保留链接上可能存在的特定参数，如：actid、stepid、cnl、cnltype、lc、sui；如果分享链接是由程序生成的其它链接，请将当前页面链接上可能存在的参数（actid、stepid、cnl、cnltype、lc、sui）也拼接到此链接上；如果分享到朋友圈或好友时，可以新增分享来源参数 from。

lc 从 0 开始(int) 层级参数
cnl 渠道 id (使用渠道分发时，会在链接中)
sui 分享来源者的 viewid，由前端 sdk 从作品 url 或小程序 path 中获取
请务必保留原链接上可能存在的特定参数，如：actid、stepid、cnl、cnltype、lc、sui

例如：在处理作品的分享链接时

// shareLink = http://www.xxx.com/a/b?lc=0&sui=2&cnl=123&cnltype=CHANNEL
var link = fiboSDK.dealUrl(shareLink);
// 设置为分享链接
// ...

2.7 自定义采集的事件和事件属性

使用场景：当系统预设的事件及事件属性不满足数据采集需求时，可以自定义采集的事件和事件属性，比如：自定义购买、加入购物车等事件，及加购事件对应的商品名称、商品价格等

注意事项：

自定义事件的事件 ID 必须以c_开头，除c_外最多 30 个字符，只能是数字和字母，不区分大小写。
属性 id 必须以c_开头，除c_外最多 30 个字符，只能是数字和字母，不区分大小写。事件属性的数据类型包括：文本型、数值型、布尔型、日期型

使用 pushCustomEvent(eventName, eventArgs) 接口。

其中 eventName 事件 ID, eventArgs 自定义属性对象

var eventName = "c_eventName";
var eventArgs = { c_attribute1: 123456, c_attribute2: "自定义属性" };
fiboSDK.pushCustomEvent(eventName, eventArgs);

2.8 访问页面事件

使用场景：进入 h5 应用的某个页面。记录用户访问某个页面的操作，如果你的 h5 应用是多页应用或者是服务器端路由，你可能不需要使用这个事件，如果是 SPA 应用，请在跳转到其它视图后立即调用。

// 以下为示例代码，请第三方开发人员根据自己的业务逻辑和项目技术栈自行实现
// 如果在进入新页面或视图时，需要更新上报数据的某些参数，可以按下面方式操作，
// 数据来源可能是当前页面或视图的url，也可能是其它方式。
var query = queryString(location.href);
// 例如当前页面 url = https://www.a.com?a=1&b=2
// 则 query = {"a": 1, "b": 2}
fiboSDK.enterPage({
  query: { ...query },
  independent: false, // 是否推送 view 事件
});

2.9 离开页面事件

使用场景：离开 h5 应用当前页面。记录用户访问过某个页面的操作，如果没有调用 enterPage 事件，那么也请不要调用这个事件，如果是 SPA 应用，请在跳转到其它视图前调用。

// 例如：基于react的SPA
fiboSDK.leavePage();
history.push("/next_page_path");

页面树结构