埋点API

1 如何查看埋点方案

在进行埋点前，需要确定在哪里埋点、埋哪些点等，即需要梳理清楚明确的埋点需求。在QuickTracking平台中将明确的埋点需求称为埋点方案，并为埋点方案设计了规范模板。如下：

在埋点方案中，明确的所需埋点内容有：

1、事件主体：指“谁”触发了这个事件，分为设备ID和账号ID，上报的事件务必具备其中之一。

• 设备ID：在小程序中一般为openid，小程序中嵌入的h5页面设备ID也需要设置为小程序的openid。

• 账号ID：客户端用户登录后账号标识，当一个用户在不同的设备进行登录时，设备ID会发生变化，但是账号ID不会发生变化。例如一个用户使用手机和pad分别登录。

2、用户属性：针对账号ID的属性，例如账号ID为“testdemo@111”的用户，“生日”为“1999-02-13”，“会员等级”为“铂金”等。“生日”和“会员”等级就为用户属性。

3、渠道属性：广告投放的属性，例如投放渠道、投放方式、投放内容等。

4、全局属性：在全局设置一次后，每一个事件都会携带的属性

5、页面浏览事件：页面加载时上报的事件（埋点方案中页面编码和事件编码相等的事件，也是标记为蓝色的事件）

6、点击、曝光、自定义事件：客户端用户与客户端发生任意交互时上报的事件。

2 设置设备ID&账号ID

2.1 设备ID设置

由于各小程序平台均有自己的设备ID生成逻辑，所以QuickTracking SDK不会自动生成任何设备ID，但是QuickTracking SDK的日志依赖设备ID，所以在进行埋点之前，需要设置设备ID。如果是微信小程序，SDK支持授权QuickTracking自动获取openid。或者开发者获取openid/unionid等官方小程序ID后手动上传作为设备ID，否则，QuickTracking SDK将无法进行任何日志上报。

手动上传方式如下：

//方式1：
wx.aplus.setMetaInfo("_anony_id", 业务侧自己实现的id);

// 方式2：
wx.aplus_queue.push({
  action: "aplus.setMetaInfo",
  arguments: ["_anony_id", 业务侧自己实现的id],
});

请注意：示例为微信小程序的代码调用示例，其他小程序平台逻辑相似

// inside app.js
const aplusConfig = {
  metaInfo: {
    ... //sdk部分配置
    '_hold: 'BLOCK',  //阻塞日志上报，待openid&unionid成功获取后再上报
    ... //sdk部分配置
  },
};

//初始化qt_mini_sdk
import { initQTSDK } from "./utils/qt_mini.umd.js";
initQTSDK(aplusConfig);

wx.login({
  success: (res) => {
    // 通过 code 换取openid
    if (res.code) {
      wx.request({
        url: 客户业务侧后端获取openid的接口,
        method: "post",
        data: {
          code: res.code,
        },
        success: (res) => {
          if (res.data && res.data.openid) {
            // 方式1：
            wx.aplus.setMetaInfo("_anony_id", res.data.openid);

            // 方式2：
            /**
              wx.aplus_queue.push({
                action: 'aplus.setMetaInfo',
                arguments: ['_anony_id', res.data.openid]
              });
              */
          } else {
            //方式1：
            wx.aplus.setMetaInfo("_anony_id", 业务侧自己实现的id);

            // 方式2：
            /**
              wx.aplus_queue.push({
                action: 'aplus.setMetaInfo',
                arguments: ['_anony_id', 业务侧自己实现的id]
              });
              */
          }
        },
      });
    }
  },
  fail: () => {
    // 失败提示信息等
  },
  complete: () => {
    //方式1：
    wx.aplus.setMetaInfo("_hold", "START");

    //方式2：
    /**
        wx.aplus_queue.push({
          action: 'aplus.setMetaInfo',
          arguments: ['_hold', 'START']
        });
        */
  },
});

PS：目前QuickTracking支持自动采集微信小程序openid，需要在产品中进行授权。授权方式如下，点击后按照要求填写内容即可。

授权后，设置设备ID代码方式为：

const aplusConfig = {
  metaInfo: {
  ... //sdk部分配置
  'autoGetOpenid': true //开启openid自动采集  
  ... //sdk部分配置
  }
};
//初始化qt_mini_sdk
import { initQTSDK } from './utils/qt_mini.umd.js';
initQTSDK(aplusConfig);    

如果之前已经使用了手动设置openid，现希望改为上述的QuickTracking自动采集微信小程序openid，还需要注意以下内容：

1. 移除metainfo中设置_hold=BLOCK的SDK阻塞上报逻辑

2. 注释掉之前手动设置「_anony_id=openid」的相关逻辑代码，也就是移除从wx.login中获取openid的相关代码。

3. 注意，务必确保关于设置appKey和收数域名的内容不受影响。

2.2 账号ID设置

在用户登录时，以及登录态进入小程序时，都需要设置账号ID。因为设置后的每一条日志都将携带账号ID，但退出小程序再进入后触发的事件不会携带账号ID。所以需要在用户登录时，以及登录态进入小程序时设置账号ID：

const { aplus } = 小程序平台环境变量 //如微信wx、支付宝my、字节tt、百度 swan等

//用户登录时，获取到用户登录账号信息 or 用户已登录，通过cookie或者localstorage获取用户登录账号
function demoLogin() {
  /*************************如果同步场景***********************************/
  aplus.setMetaInfo("_user_id", '用户的账号id');
  
  /*************************如果是异步场景*********************************/
  //先通过设置_hold=BLOCK阻塞采集上报
  aplus.setMetaInfo("_hold", 'BLOCK');

  ...
  function callback() {
    //获取异步回调结果中的用户账号id
    aplus.setMetaInfo("_user_id", '用户的账号id');
    
    //再通过设置_hold=START允许采集上报
    aplus.setMetaInfo("_hold", 'START');
  };
  ...
};
//用户登出时，重置用户账号id
function demoLogOff() {
    aplus.setMetaInfo("_user_id", '');
};

2.3 设备ID和账号ID获取

若需要在小程序端上获取QuickTracking的设备ID时，可以在metainfo中获取_anony_id，以微信小程序为例：

const { aplus } = 小程序平台环境变量 //如微信wx、支付宝my、字节tt、百度 swan等
aplus.getMetaInfo('_anony_id');

若需要在小程序端上获取QuickTracking的账号ID时，可以在metainfo中获取_user_id，以微信小程序为例：

const { aplus } = 小程序平台环境变量 //如微信wx、支付宝my、字节tt、百度 swan等
aplus.getMetaInfo('_user_id');

3 设置用户属性

通过预置事件编码 $$_user_profile 上报用户属性，事件类型为其他事件。

在上报用户属性之前，需要先设置_user_id上报用户账号，否则QuickTracking流量分析对用户属性不会进行关联计算。确认上报用户的账号ID后，上报用户属性示例如下：

const { aplus } = 小程序平台环境变量; //如微信wx、支付宝my、字节tt、百度 swan等
//示例
aplus.record("$$_user_profile", "OTHER", {
  name: "sss", //用户属性1
  gender: "male", //用户属性2
  class: "3", //用户属性3
});

上述内容中，3行不能发生任何变化，仅可自定义4、5、6行。

4 渠道属性

渠道属性无需进行任何埋点，但是需要唤起小程序的URL中携带这些渠道属性，且属性key务必以“utm_”开头，因为SDK识别的关键字为“utm_”。例如：

qaplus/product?utm_channel=gzh

PS：如果渠道属性已经与市面上渠道投放公司进行了合作，无法使用utm_开头，可以使用全局属性API将渠道属性进行埋点上报（属性key依然需要以“utm_”开头）。

5 全局属性

全局属性的生命周期为应用启动到应用隐藏

5.1 追加全局属性（aplus.appendMetaInfo）

使用aplus.appendMetaInfo进行全局属性上报时，如果和已经存在的全局属性key重复，则更新已有值；如果和已经存在的全局属性key不一致，则插入新的全局属性。

接口：

const { aplus } = 小程序平台环境变量; //如微信wx、支付宝my、字节tt、百度 swan等

aplus.appendMetaInfo("globalproperty", {
  //追加全局属性
  xxx: xxx,
});

示例：

const { aplus } = 小程序平台环境变量; //如微信wx、支付宝my、字节tt、百度 swan等

aplus.appendMetaInfo("globalproperty", {
  //追加全局属性
  a: 3,
  b: 4,
});
//当前globalproperty为a:3和b:4

aplus.appendMetaInfo("globalproperty", {
  //追加全局属性
  b: 2,
  d: 4,
});
//当前globalproperty为a:3、b:2、d:4

5.2 覆盖全局属性

使用aplus.setMetaInfo进行全局属性上报时，仅会以最后一次上报为准。即先清空已有全部全局属性，再将本次setMetaInfo设置的全局属性放入。

接口：

const { aplus } = 小程序平台环境变量; //如微信wx、支付宝my、字节tt、百度 swan等

aplus.setMetaInfo("globalproperty", {
  xxx: xxx,
});

示例：

const { aplus } = 小程序平台环境变量; //如微信wx、支付宝my、字节tt、百度 swan等

aplus.setMetaInfo("globalproperty", {
  a: 1,
  b: 2,
});
//当前globalproperty为a:1和b:2

aplus.setMetaInfo("globalproperty", {
  c: 1,
  d: 2,
});
//当前globalproperty为c:1和d:2,“a:1和b:2不再存在”

6 页面浏览事件API

1、页面浏览事件分为SDK自动埋点（全埋点）和代码埋点两种方式，默认页面浏览事件的全埋点是开启的。

2、页面浏览事件需要埋点的内容为：

• 事件编码：也就是页面编码，在页面浏览事件中事件编码即为页面编码。

• 页面浏览事件的事件属性：具体属性见埋点方案

• 

6.1 pageConfig

pageConfig为全局设置页面的页面编码的方式，具体示例如下：

const aplusConfig = {
  metaInfo: {
    appKey: "", //QuickTracking 创建应用时填写的Appkey, 必填
    "aplus-rhost-v": "", //采集日志上报域名，必填
    _user_id: "testUserId", //小程序自身的登录账号id，如需要计算分析用户账号纬度的数据，需上报
    _anony_id: "testOpenid", //小程序平台用户唯一标识，用于计算UV, 必填
    DEBUG: true, //打开调试日志
    appVersion: "您当前小程序的版本",

    //全局配置页面编码
    //若未设置页面编码默认为path
    //若未设置页面标题微信小程序默认为页面标题，其他小程序默认为""
    pageConfig: {
      "pages/index/index": {
        pageName: "page_name_test_index",
        pageTitle: "首页",
        skipMe: true, //忽略自动上报该页面的页面浏览事件， 默认为undefined
      },
      "pages/detail/detail": {
        pageName: "page_name_test_detail",
        pageTitle: "详情页",
      },
    },
  },
};

其中

• pageName表示页面编码

• pageTitle表示页面标题

• skipMe为是否关闭该页面的自动浏览事件采集（true表示关闭，false表示开启）

注意：skipMe设置的优先级低于关闭页面浏览事件自动采集的总开关aplus-disable-apv

6.2 页面自动埋点

SDK识别到页面的onHide时，上报页面浏览事件，上报的内容为：

• 当前客户端时间

• 页面path

• 页面编码（默认为页面path，如果设置了pageConfig，则取值为映射pageConfig的page_name）

• 页面标题（默认为页面title，如果设置了pageconfig，则取值为映射的page_title）

• 页面停留时长：从onShow到onHide的时间

6.2.1 关闭页面自动埋点

页面自动上报默认是开启的，如果需要关闭自动页面上报，API如下：

const { aplus } = 小程序平台环境变量 //如微信wx、支付宝my、字节tt、百度 swan等

aplus.setMetaInfo('aplus-disable-apv', true);

如果仅须关闭某一页面的自动页面上报，可以在pageconfig中设置skipMe为true关闭。

6.2.2 设置自动页面浏览事件的事件属性

在页面onhide钩子触发之前，可以调用updatePageProperties动态设置页面编码和页面浏览事件的事件属性。

API说明：

const { aplus } = 小程序平台环境变量 //如微信wx、支付宝my、字节tt、百度 swan等

aplus.updatePageProperties($params, $page_path);

其中

• $params: 页面事件属性集合，object类型，不支持多层嵌套，其中预制字段page_name，用于动态设置自动页面事件的页面编码

• $page_path：可选字段，string类型，如果不传，默认为当前页面路径

示例

onShow() {
  const { aplus } = 小程序平台环境变量 //如微信wx、支付宝my、字节tt、百度 swan等

  aplus.updatePageProperties({
    page_name: '', //（可选）预制字段，用于动态设置自动页面事件的页面编码
    param1: '',
    param2: ''
  }, 'pages/home/home');
}

6.3 页面手动采集

API

sendPV 方法将发送一条页面 PV 日志，其 API 定义如下：

const { aplus } = 小程序平台环境变量 //如微信wx、支付宝my、字节tt、百度 swan等

aplus.sendPV($pageEventConfig, $properties
)

其中

• $pageEventConfig 为页面事件的配置，只需要写死{ is_auto: false } 即可

• $properties 为本次页面事件的扩展参数，其取值为一个object类型，不能多层嵌套，若无可传空对象'{}'

  • duration：其中duration作为预制字段，用于手动PV功能下记录本次页面浏览的页面停留时长，计算duration的逻辑需要开发者根据业务场景自行设计实现。自动PV功能下，duration计算逻辑由sdk内部实现

示例

// 一个简单的demo
const { aplus } = 小程序平台环境变量; //如微信wx、支付宝my、字节tt、百度 swan等

aplus.sendPV(
  {
    is_auto: false,
  },
  {
    page_title: "首页", //默认为pageConfig中的值，如果这里设置了，则为这里设置的值 (非必传)
    page_name: "yourCurrentPageName", //默认为pageConfig中的值，如果这里设置了，则为这里设置的值 (非必传)

    //如果您设置了duration参数（单位须为毫秒），QuickTracking会做为分析时的「事件属性-时长（s）」处理
    duration: 1111111,

    //自定义事件属性
    x: 111,
    y: 222,
  }
);

注意：

页面标题（page_title）默认为pageConfig中的值，如果这里设置了，则为这里设置的值。

页面编码（page_name）默认为pageConfig中的值，如果这里设置了，则为这里设置的值。

7 事件埋点

除了页面浏览事件外的事件都使用'action':'aplus.record'进行埋点，事件需要埋点的内容有：

• 事件编码：

• 事件属性：

• 页面编码（可选）：SDK默认采集页面path，如果页面path在pageConfig中进行了映射，并设置了page_name，则取值为pageConfig中的page_name。如果在事件埋点时，在事件属性中设置了page_name，则取值为事件属性中的page_name。也就是取值优先级为：

  事件属性中的page_name > pageConfig中的page_name > 页面path

• 页面标题（可选）：SDK默认采集页面title，如果页面path在pageConfig中进行了映射，并设置了page_title，则取值为pageConfig中的page_title。如果在事件埋点时，在事件属性中设置了page_title，则取值为事件属性中的page_title。也就是取值优先级为

事件属性中的page_title > pageConfig中的page_title > 页面title

事件埋点分为SDK自动埋点（全埋点）和代码埋点两种方式，默认点击和曝光的全埋点是关闭的。

7.1 曝光事件

EXP特指曝光事件

const { aplus } = 小程序平台环境变量; //如微信wx、支付宝my、字节tt、百度 swan等

aplus.record("埋点方案中的事件编码", "EXP", {
  x: "111",
  y: "222",
  z: "333",
  page_name: "demoPageName", //您当前页面的自定义页面编码（非必传）
});

7.2 点击事件

CLK特指点击事件

const { aplus } = 小程序平台环境变量; //如微信wx、支付宝my、字节tt、百度 swan等

aplus.record("埋点方案中的事件编码", "CLK", {
  x: "111",
  y: "222",
  z: "333",
  page_name: "demoPageName", //您当前页面的自定义页面编码（非必传）
});

7.3 OTHER 其他事件埋点

OTHER特指除点击和曝光事件外的其他自定义事件

const { aplus } = 小程序平台环境变量 //如微信wx、支付宝my、字节tt、百度 swan等

aplus.record('埋点方案中的事件编码', 'OTHER', {
  x: '111',
  y: '222',
  z: "333",
  page_name: "demoPageName", //您当前页面的自定义页面编码（非必传）
});

7.4 自动曝光（全埋点）

由SDK内部帮助开发者处理曝光时机，并自动采集元素曝光行为。触发时机为控件展示在可视区域内面积超过50%，时间超过300ms。

以微信为例， UI部分：

// 页面WXML文件根节点埋点capture-bind:touchstart：
<view class="root" capture-bind:touchstart="onAplusTouch">
  
 // 待曝光节点添加class和data-tracker(对应app.js中自动点击的配置)，如:
 <view class="button-section">
    <button 
       class="auto-exposure"
       data-pagename="自定义当前事件的页面编码" 
       data-page_title="自定义当前事件的页面标题" 
       data-name="btn-navigator" 
       data-index="num1"
       bindtap="onNavigatorTap">导航</button>
   	<button 
       class="autotrack_exp" 
       data-itemName='读书' 
       data-itemzoon='abc' 
       data-itemid='a_product_id' 
       data-promotioninformation='abc' 
       data-pagename='首页'>autoExp</button>
  	<custom_component 
       class="custom_component"
       name="books"
       title="data-title"
       description="this is a custom_component"></custom_component>
  </view>
</view>

sdk 配置部分：

const aplusConfig = {
  metaInfo: {
    "aplus-auto-exp": [
      {
        cssSelector: ".auto-exposure", // 你要曝光的元素的class
        logkey: "auto-exp-id", // 埋点方案中对应的事件编码
        /** 注意：
         *  1、如果CSSSelector能匹配上多个元素则一定要在页面节点上埋data-tracker,否则aplusJS无法识别元素唯一性，进而导致一个列表多个元素只能触发一次曝光；
         *  2、目前支付宝小程序不支持该属性采集
         */
        props: ["data-name", "data-index", "data-pagename", "data-page_title"],
      },
      {
        cssSelector: ".autotrack_exp", // 你要曝光的元素的class
        logkey: "autotrack_exp", // 埋点方案中对应的事件编码
      },
    ],
    // 自动曝光的前置回调函数，用于支持定制化参数上报，如驼峰写法等（html数据属性默认只支持小写）
    // 1.9.25版本及以上支持
    "aplus-auto-exp-userfn": function (e, selector) {
      if (selector.indexOf("autotrack_exp") != -1) {
        var dataset = e.dataset;
        var obj = {};
        obj.itemID = dataset.itemid;
        obj.itemName = dataset.itemname;
        obj.itemZoon = dataset.itemzoon;
        obj.promotionInformation = dataset.promotioninformation;
        obj.pageName = dataset.pagename;
        return obj;
      }
    },
  },
};

自动曝光前置回调函数，默认值为undefined，如需开启，需设置：

const { aplus } = 小程序平台环境变量 //如微信wx、支付宝my、字节tt、百度 swan等
aplus.setMetaInfo('aplus-auto-exp-userfn', function(e， selector) { 
  /**
    * e: DOM元素
    * selector: 元素的选择器，取值为自动点击中传入的cssSelector
    * @return 自定义属性对象
    */
});

请注意：针对跨自定义组件的后代选择器，需要使用 >>> 语法，帮助SDK获取元素DOM数据，参考示例：

// 页面WXML文件根节点埋点capture-bind:touchstart：
<view class="root" capture-bind:touchstart="onAplusTouch">
	// 待曝光节点添加class和data-tracker(对应app.js中自动点击的配置)，如:
	<view class="button-section">
		<custom_component 
        class="custom_component" 
        name="books" 
        title="data-title" 
        description="this is a custom_component">
		</custom_component>
	</view>
</view>

const aplusConfig = {
  metaInfo: {
    ...
    "aplus-auto-exp": [
      {
        cssSelector: ".root >>> .custom_component",
        logkey: "exp_custom_component",
        props: [],
      },
      {
        //非shadow root控制的组件
        cssSelector: ".custom_component",
        logkey: "exp_custom_component",
        props: [],
      },
    ],
    ...
  },
};

7.5 自动点击（全埋点）

从版本1.1.0开始，为减少开发者埋点工作量，sdk也支持通过配置部分信息，让SDK自动采集页面内的点击事件。（支付宝、百度小程序需要基础库2.x版本以上才支持）

以微信为例， UI部分：

// 页面WXML文件根节点埋点catchtap：
<view catchtap="onAplusClk">
  
// 待曝光节点添加class和data-tracker(对应app.js中自动点击的配置)，如:
<view class="button-section">
  <button 
     class="auto-click" 
     data-pagename="自定义当前事件的页面编码" 
     data-page_title="自定义当前事件的页面标题" 
     bindtap="onNavigatorTap">导航</button>
  <button 
     class="autotrack_clk" 
     data-itemName='读书' 
     data-itemzoon='abc' 
     data-itemid='a_product_id' 
     data-promotioninformation='abc' 
     data-pagename='首页'>autoClk</button>
</view>

sdk 配置部分：

const aplusConfig = {
  metaInfo: {
    ...
    "aplus-auto-clk": [
      {
        cssSelector: ".auto-click",
        logkey: "demoEventCode", //埋点方案中对应的事件编码
        props: ["data-name", "data-pagename", "data-page_title"], // 埋点方案中的自定义属性
      },
      {
        cssSelector: ".autotrack_clk",
        logkey: "autotrack_clk", //埋点方案中对应的事件编码
      },
    ],
    // 自动点击事件的前置回调函数，用于支持定制化参数上报，如驼峰写法等（html数据属性默认只支持小写）
    "aplus-auto-clk-userfn": function (e, selector) {
      if (selector.indexOf("autotrack_clk") != -1) {
        var dataset = e.dataset;
        var obj = {};
        obj.itemID = dataset.itemid;
        obj.itemName = dataset.itemname;
        obj.itemZoon = dataset.itemzoon;
        // obj.promotionInformation = dataset.promotioninformation;
        obj.pageName = dataset.pagename;
        return obj;
      }
    },
    ...
  },
};

自动点击前置回调函数，默认值为undefined，如需开启，需设置：

const { aplus } = 小程序平台环境变量; //如微信wx、支付宝my、字节tt、百度 swan等

/**
 * e: DOM元素
 * selector: 元素的选择器，取值为自动点击中传入的cssSelector
 * @return 自定义属性对象
 */
aplus.setMetaInfo("aplus-auto-clk-userfn", function (e, selector) {
    
});

7.6 小程序元素点击（全埋点）

从版本 2.4.2 开始，开发者某些场景下需要采集页面内绑定事件函数的元素点击行为，为了减少7.5节开发者配置化的工作量，sdk已支持此种场景的自动采集。

默认不采集绑定事件函数元素的点击行为，如需开启需要

//以微信小程序举例
wx.aplus_queue.push({
  action: "aplus.setMetaInfo",
  arguments: ["autotrackMethodEnable", true]
});

或者 

wx.aplus.setMetaInfo("autotrackMethodEnable", true);

使用场景：

以微信小程序场景举例

//wxml
<view class="bottomTab" 
      bindtap="onClick" 
      id="my_bottom_tab"
      data-custom_property="1111" 
      data-element_type="元素类型，开发者按需补充"
      data-element_name="元素名称，开发者按需补充"
      data-element_class_name="元素class，开发者按需补充"
      data-element_content="元素内容，开发者按需补充"
      data-element_selector="css筛选器，开发者按需补充"
      data-element_path="元素路径，开发者按需补充">
  <view class="iconfont icon-dibu">底部导航</view>
</view>

//homePage.js
Page({
  // 底部tab点击
  onClick: function () {
    // 业务处理逻辑
  }
})

当用户触发onClick事件时，sdk 会上报一条事件编码为$$_mp_item_click的事件，采集字段包括：

• 事件属性

  • （默认采集）methodName:"onClick"

  • （用户自定义属性）custom_property:"1111"

• 全埋点属性

  • element_id: "my_bottom_tab"

  • element_type: "元素类型，开发者按需补充"

  • element_name: "元素名称，开发者按需补充"

  • element_class_name: "元素class，开发者按需补充"

  • element_content: "元素内容，开发者按需补充"

  • element_selector: "css筛选器，开发者按需补充"

  • element_path: "元素路径，开发者按需补充"

备注：全埋点属性仅开发者在元素上配置了数据属性data-element_xxx后生效。

8 分享裂变

分享裂变是增长黑客策略的一个关键概念，它依靠用户之间的社交联系来实现信息的相互传递，从而促进新用户的获取。

完成分享裂变的SDK功能集成，您将可以使用QuickTracking平台分享趋势模型，通过分享回流相关指标衡量营销活动的拉新效益。

1. 支持查看TOP分享用户和不同分享回流层级的分享回流效果指标。

2. 支持回流指标灵活组合配置，查看最具裂变拉新能力和分享回流转化能力的TOP用户，追踪用户分享裂变链路与分享回流关系，快速定位关键意见消费者。

获取来源分享参数

aplus.getRefShareParams();

版本要求

小程序 sdk v2.2.0版本及以上

功能

当被分享人打开小程序时，用于获取来源分享id 和来源分享 url 的 API

请求参数

无

返回参数

Object 类型

调用示例

注：考虑到小程序平台在onShareAppMessage和onShareTimeline API上的能力差异，SDK提供了两种API使用方式来请求分享参数，分别是支持Promise返回和支持函数回调方式返回。开发者请根据产品所需适配的平台自行选择。

基于支持 promise 的方式使用

/**
 *以微信小程序举例，Promise返回值场景
 */

Page({
  data: {
    // sdk 预制分享 id 字段
    $$_share_id: "",
  },
  getShareId() {
    const { $$_ref_share_url, $$_ref_share_id } = wx.aplus.getRefShareParams();

    // 方式1：在自定义函数中获取分享id
    wx.aplus
      .requestShareParams({
        title: "分享活动页",
        path: "/pages/share/shareCampaign?utm_test=test",
        campaign: "这是一个分享活动",
        shareId: $$_ref_share_id,
      })
      .then((res) => {
        const { $sid } = res;
        if ($sid) {
          this.setData({
            $$_share_id: $sid,
          });
        } else {
          // 具体报错原因，SDK DEBUG 模式下，小程序控制台会打印
          console.log("分享参数获取失败");
        }
        return res;
      });
  },

  // 监听用户点击页面内转发按钮（button 组件 open-type="share"）或右上角菜单“转发”按钮的行为并自定义转发内容
  onShareAppMessage() {
    return {
      title: "用户默认分享活动页标题",
      path: `/pages/share/shareCampaign?utm_test=test&$sid=${this.data.$$_share_id}`,
      // 必须传入，sdk预制字段，分享id
      $$_share_id: this.data.$$_share_id,
      // 按需传入，sdk预制字段，分享活动id
      $$_share_campaign_id: "这是一个自定义分享活动",
      // 必须传入，原始分享链接，切记不需要拼接分享id
      $$_share_url: `${this.route}?utm_source=分享朋友圈`,
    };
  },

  // 监听右上角菜单“分享到朋友圈”按钮的行为，并自定义分享内容。
  onShareTimeline() {
    return {
      title: "分享朋友圈",
      // 下个被分享主体打开小程序时query中的参数，切记需要拼接$sid，否则分享链会断开
      query: `$sid=${this.data.$$_share_id}`,
      // 必须传入，sdk预制字段，分享id
      $$_share_id: this.data.$$_share_id,
      // 必须传入，sdk预制字段，分享活动id
      $$_share_campaign_id: "这是一个自定义分享活动",
      // 必须传入，原始分享链接，切记不需要拼接分享id
      $$_share_url: `${this.route}?utm_source=分享朋友圈`,
    };
  },
  // 用户自定义模拟分享，如生成分享图片、生成分享剪切板内容
  userCustomShare() {
    wx.aplus.record("$$_share", "CLK", {
      // 按需传入, sdk预制字段，分享标题
      $$_share_title: "这是一个分享标题",
      // 必须传入，sdk预制字段，分享id
      $$_share_id: this.data.$$_share_id,
      // 按需传入，sdk预制字段，分享活动id
      $$_share_campaign_id: "这是一个自定义分享活动",
      // 按需传入，sdk预制字段，分享目标平台
      $$_share_type: "用户自定义分享目标平台",
      // 必须传入，原始分享链接，切记不需要拼接分享id
      $$_share_url: `${this.route}?utm_source=自定义分享`,
    });
  },
});

基于 callback 的方式使用

/**
*以微信小程序举例，Promise返回值场景
*/

Page({
  data: {
    // sdk 预制分享 id 字段
    $$_share_id: "",
  },
  getShareId() {
    const {
      $$_ref_share_url,
      $$_ref_share_id,
    } = wx.aplus.getRefShareParams();

    // 方式1：在自定义函数中获取分享id
    wx.aplus.requestShareParams({
      title: '分享活动页',
      path: '/pages/share/shareCampaign?utm_test=test',
      campaign: '这是一个分享活动',
      shareId: $$_ref_share_id,
    }).then((res) => {
      const { $sid } = res;
      if ($sid) {
        this.setData({
          $$_share_id: $sid,
        });
      } else {
        // 具体报错原因，SDK DEBUG 模式下，小程序控制台会打印
        console.log("分享参数获取失败");
      }
      return res;
    });
  },

  // 监听用户点击页面内转发按钮（button 组件 open-type="share"）或右上角菜单“转发”按钮的行为并自定义转发内容
  onShareAppMessage() {
    return {
      title: '用户默认分享活动页标题',
      path: `/pages/share/shareCampaign?utm_test=test&$sid=${this.data.$$_share_id}`,
      // 必须传入，sdk预制字段，分享id
      $$_share_id: this.data.$$_share_id,
      // 按需传入，sdk预制字段，分享活动id
      $$_share_campaign_id: "这是一个自定义分享活动",
      // 必须传入，原始分享链接，切记不需要拼接分享id
      $$_share_url: `${this.route}?utm_source=分享朋友圈`,
    };
  },

  // 监听右上角菜单“分享到朋友圈”按钮的行为，并自定义分享内容。
  onShareTimeline() {
    return {
      title: "分享朋友圈",
      // 下个被分享主体打开小程序时query中的参数，切记需要拼接$sid，否则分享链会断开
      query: `$sid=${this.data.$$_share_id}`,
      // 必须传入，sdk预制字段，分享id
      $$_share_id: this.data.$$_share_id,
      // 必须传入，sdk预制字段，分享活动id
      $$_share_campaign_id: "这是一个自定义分享活动",
      // 必须传入，原始分享链接，切记不需要拼接分享id
      $$_share_url: `${this.route}?utm_source=分享朋友圈`,
    };
  },
  // 用户自定义模拟分享，如生成分享图片、生成分享剪切板内容
  userCustomShare() {
    wx.aplus.record("$$_share", "CLK", {
      // 按需传入, sdk预制字段，分享标题
      $$_share_title: "这是一个分享标题",
      // 必须传入，sdk预制字段，分享id
      $$_share_id: this.data.$$_share_id,
      // 按需传入，sdk预制字段，分享活动id
      $$_share_campaign_id: "这是一个自定义分享活动",
      // 按需传入，sdk预制字段，分享目标平台
      $$_share_type: "用户自定义分享目标平台",
      // 必须传入，原始分享链接，切记不需要拼接分享id
      $$_share_url: `${this.route}?utm_source=自定义分享`,
    });
  }
})

请求分享参数

aplus.requestShareParams(Object params, Function callback);

版本

小程序 sdk v2.2.0版本及以上

功能

请求用于构建分享链需要的分享id

请求参数

返回参数

如果请求参数不包含 callback，返回 Promise.resolve(Object result)

调用示例

注：考虑到小程序平台在onShareAppMessage和onShareTimeline API上的能力差异，SDK提供了两种API使用方式来请求分享参数，分别是支持Promise返回和支持函数回调方式返回。开发者请根据产品所需适配的平台自行选择。

基于支持 promise 的方式使用

方式1：在自定义方法中获取分享id，然后在 onShareAppMessage \ onShareTimeline 中通过返回结果上报分享信息

Page({
  data: {
    $$_share_id: "", //sdk 预制分享 id 字段
  },
  getShareId() {
    // 方式1：在自定义函数中获取分享id
    wx.aplus.requestShareParams({
      title: '分享活动页',
      path: '/pages/share/shareCampaign?utm_test=test',
      campaign: '这是一个分享活动',
      shareId: "这是一个来源分享id"
    }).then(res => {
      const { $sid } = res;
      this.setData({
        $$_share_id: $sid
      });
      return res;
    });
  },
  //监听用户点击页面内转发按钮（button 组件 open-type="share"）或右上角菜单“转发”按钮的行为并自定义转发内容
  onShareAppMessage(options) {
    return {
      title: '用户默认分享活动页标题',
      path: `/pages/share/shareCampaign?utm_test=test&$sid=${this.data.$$_share_id}`,
      //必须传入，sdk预制字段，分享id
      $$_share_id: this.data.$$_share_id,
      //按需传入，sdk预制字段，分享活动id
      $$_share_campaign_id: "这是一个自定义分享活动",
      //必须传入，原始分享链接，切记不需要拼接分享id
      $$_share_url: `${this.route}?utm_source=分享朋友圈`, 
    }
  },
  ...
  //监听右上角菜单“分享到朋友圈”按钮的行为，并自定义分享内容。
  onShareTimeline(options) {
    return {
      title: "分享朋友圈",
      //下个被分享主体打开小程序时query中的参数，切记需要拼接$sid，否则分享链会断开
      query: `$sid=${this.data.$$_share_id}`,
      //必须传入，sdk预制字段，分享id
      $$_share_id: this.data.$$_share_id,
      //必须传入，sdk预制字段，分享活动id
      $$_share_campaign_id: "这是一个自定义分享活动",
      //必须传入，原始分享链接，切记不需要拼接分享id
      $$_share_url: `${this.route}?utm_source=分享朋友圈`, 
    }
  },
  //用户自定义模拟分享，如生成分享图片、生成分享剪切板内容
  userCustomShare() {
    wx.aplus.record("$$_share", "CLK", { 
      //按需传入, sdk预制字段，分享标题
      $$_share_title: "这是一个分享标题",
      //必须传入，sdk预制字段，分享id
      $$_share_id: this.data.$$_share_id,
      //按需传入，sdk预制字段，分享活动id
      $$_share_campaign_id: "这是一个自定义分享活动",
      //按需传入，sdk预制字段，分享目标平台
      $$_share_type: "用户自定义分享目标平台",
      //必须传入，原始分享链接，切记不需要拼接分享id
      $$_share_url: `${this.route}?utm_source=自定义分享`, 
    });
  }
})

方式2：在onShareAppMessage中调用分享参数获取API，然后在 onShareAppMessage 中通过promise返回结果上报分享信息

注：因 onShareTimeline 方法不支持 promise 返回，因此 onShareTimeline 仍需考虑通过 setState 方式获取分享 id

Page({
  ...
  onShareAppMessage(options) {
    const promise = wx.aplus.requestShareParams({
      title: '分享活动页',
      path: '/pages/share/shareCampaign?utm_test=test',
      campaign: '这是一个分享活动',
      shareId: "这是一个来源分享id"
    });

    return {
      title: '用户默认分享活动页标题',
      promise
    }
  },
  ...
  
})

基于 callback 的方式使用

Page({
  data: {
    $$_share_id: "", //sdk 预制分享 id 字段
  },
  getShareId() {
    wx.aplus.requestShareParams({
      title: '分享活动页',
      path: '/pages/share/shareCampaign?utm_test=test',
      campaign: '这是一个分享活动',
      shareId: "这是一个来源分享id"
     }, (res) => {
      const { $sid } = res;
      this.setData({
        $$_share_id: $sid
      });
    });
  },
  ...
  //监听用户点击页面内转发按钮（button 组件 open-type="share"）或右上角菜单“转发”按钮的行为并自定义转发内容
  onShareAppMessage(options) {
    return {
      title: '用户默认分享活动页标题',
      path: `/pages/share/shareCampaign?utm_test=test&$sid=${this.data.$$_share_id}`,
    	//必须传入，sdk预制字段，分享id
      $$_share_id: this.data.$$_share_id,
      //必须传入，sdk预制字段，分享活动id
      $$_share_campaign_id: "这是一个自定义分享活动",
      //必须传入，原始分享链接，切记不需要拼接分享id
      $$_share_url: `${this.route}?utm_source=分享朋友圈`, 
    }
  },
  //监听右上角菜单“分享到朋友圈”按钮的行为，并自定义分享内容。
  onShareTimeline(options) {
    return {
      title: "分享朋友圈",
      //下个被分享主体打开小程序时query中的参数，切记需要拼接$sid，否则分享链会断开
      query: `$sid=${this.data.$$_share_id}`,
      //必须传入，sdk预制字段，分享id
      $$_share_id: this.data.$$_share_id,
      //必须传入，sdk预制字段，分享活动id
      $$_share_campaign_id: "这是一个自定义分享活动",
      //必须传入，原始分享链接，切记不需要拼接分享id
      $$_share_url: `${this.route}?utm_source=分享朋友圈`, 
     }
  },

  //用户自定义模拟分享，如生成分享图片、生成分享剪切板内容
  userCustomShare() {
     wx.aplus.record("$$_share", "CLK", {
        //按需传入, sdk预制字段，分享标题
        $$_share_title: "这是一个分享标题",
        //必须传入，sdk预制字段，分享id
        $$_share_id: this.data.$$_share_id,
       	//按需传入，sdk预制字段，分享活动id
      	$$_share_campaign_id: "这是一个自定义分享活动",
        //按需传入，sdk预制字段，分享目标平台
        $$_share_type: "用户自定义分享目标平台",
        //必须传入，原始分享链接，切记不需要拼接分享id
      	$$_share_url: `${this.route}?utm_source=自定义分享`, 
      });
  }
})