# 接入

要使用产品体验分析，需先接入数据采集模块。

# 小程序项目

# 自动接入

在控制台新建项目时，勾选自动接入模式，开发平台将自动为相应小程序接入并启用数据采集。对于已存在的项目，可以进入项目，在“设置->采集配置->采集模式”选择自动采集模式。

注意：

基础库版本 > 2.32.2，当用户退出小程序至后台超过 30 分钟，再回到小程序 (且场景值不为1089) 后，系统会自动结束上次采集，重新开启新的采集。在管理端将看到两条不同的回放。

# SDK 接入模式

# 安装与使用

安装：在小程序代码根目录下执行 npm install @wxobs/miniprogram-sdk
构建：在微信开发者工具中，点击左上角菜单栏中“工具” -> “构建npm”
使用：在 app.js 文件中引入 setup 函数，并在 onLaunch 中执行即可启动采集。

示例代码：

import wxobs from '@wxobs/miniprogram-sdk';

App({
  onLaunch: function () {
    wxobs.setup({
      maskMode: 'all-mask'
    })
  },
});

# API

# setup

配置并启动数据采集。参数：

{
  maskMode?: 'all-mask' | 'no-mask' // 可选，默认值 'all-mask'，'all-mask'表示采集时默认遮罩所有元素，'no-mask'表示不遮罩。使用 'no-mask' 模式时，请注意遵守《个人隐私保护法》等法规，在用户同意的情况下采集隐私数据。
  isWhitelistMaskMode?: boolean // [已弃用] 可选，默认值 true。true 表示以白名单模式遮罩小程序中的元素，false表以黑名单模式遮罩小程序中的元素。不可和 maskMode 同时使用。
  attrs?: Record<string, string> // 对回放添加属性，在管理端可通过属性筛选回访
  captureDataAttrs?: boolean // 可选，默认为 true。采集 webview 中的元素时，是否采集以 data-* 为开头的属性
  shouldCapturePage?: (page: string, query: Record<string, string>) => boolean // 可选。用于控制是否采集某页面的回调，page 和 query 是该页面的属性，默认为全部采集。
}

Promise<{
  sessionId?: string // 该回放 Id，正常启动采集时不为空
  errMsg?: string // 启动异常时的错误消息
}>

# teardown

停止采集
参数：无
返回：

Promise<void>

# setAttrs

注意：下面的任何api都必须在setup返回的promise resolve之后再执行

# setAttrs

已废弃

# param

attrs: Record<string, string> // 属性的键值对

~~向当前回放添加键值对属性，回放端可通过该属性筛选回放。~~ 0.3.0版本后废弃，推荐使用event, identify, 替代

# example

setAttrs({
  gender: 'male',
  age: '18',
})

# event

# param

function event(
  eventName: string, // 事件名
  eventProperties: Record<string, string| number>, // 事件属性
): boolean

触发一个自定义事件，管理端可以通过这个动作，找到对应回放、分析转化等...
eventName的长度需要小于50个字符，eventProperties的属性需要少于10个，每个属性的key需要少于50个字符，value需要少于255字符，若value为数字请自己保证不要超过js长度限制，请不要传入浮点数，否则可能出现不符合预期的行为。函数的返回值为是否通过校验，若不通过则会返回false，反之true

# example

假设用户在你的小程序上发生了一次购买动作，可以通过如下代码触发一次自定义事件（购买）的上报

event(
  'buy_goods',
  {
    good_id: 'abcdefg123',
    order_id: 'xxxxxxx',
    price: 1024
  }
)

# identify

# param

function identify(
  uid: string,
  props: Record<string, string | number>,
): boolean

设定当前用户的id，属性，管理端可以通过这个用户的id、属性，找到对应回放、并依据人的维度进行转化分析等...
uid的长度需要小于80个字符，props的属性需要少于10个，每个属性的key需要少于50个字符，value需要少于255字符，若value为数字请自己保证不要超过js长度限制，请不要传入浮点数，否则可能出现不符合预期的行为。函数的返回值为是否通过校验，若不通过则会返回false，反之true

在一次回放中，identify如被多次调用，只会取第一次调用的结果，如需更改props，可通过调用updateUserProperties实现。uid不可更改。当然我们也建议对于同一个用户不要更改uid，否则会导致同一用户的数据无法连贯

# example

假设有用户的openid

identify(
  openid,
  {
    vip_level:1
    age: 18,
    name: 'klaus'
  }
)

# updateUserProperties

# param

function updateUserProperties(
  props: Record<string, string | number>,
): boolean

更新用户的props...
props的属性需要少于10个，每个属性的key需要少于50个字符，value需要少于255字符，若value为数字请自己保证不要超过js长度限制，请不要传入浮点数，否则可能出现不符合预期的行为。函数的返回值为是否通过校验，若不通过则会返回false，反之true

一条回放中，props会以最后一次的为准。如需要记录一个用户的属性变化，可以通过自定义属性触发

# example

updateUserProperties(
  {
    vip_level:2
  }
)

# 隐私

# 屏蔽

为保护用户隐私，采集模块屏蔽了以下数据：

所有 input 事件
open-data
小程序插件内容

此外，我们也向开发者提供自定义屏蔽元素的方法：在元素上添加类"wxobs-exclude", 该元素将将不会被采集。例如：

<view class="wxobs-exclude">
	...
</view>

# 遮罩

采集模块提供了对图片、视频、文本内容的遮罩功能。对需要遮罩的图片和视频，采集模块会将原图片或视频替换成骨架图上报，文本则替换成星号。

开发者可根据需要，在 setup 时配置 isWhitelistMaskMode 来选择白名单遮罩模式或黑名单遮罩模式。

在白名单模式下，SDK 会默认遮罩所有的元素，开发者可以在元素上添加类 "wxobs-unmask" 来解除该元素及其子元素的遮罩。如

<view class="wxobs-unmask">
	...
</view>

在黑名单模式下，所有元素默认不遮罩。开发者可以针对敏感元素，在元素上添加类 "wxobs-mask" 来遮罩该元素及其子元素。如

<view class="wxobs-mask">
	...
</view>

# Web 项目

新建 Web 项目后，进入项目，选择“设置->采集配置”，即可看到接入代码，将接入代码写入到要接入 web 项目的 index.html 文件中即可。

以下是接入代码样例（注：样例代码不能直接使用，如需接入，请使用“设置->采集配置”中的接入代码）

<script>
(function () {
  'use strict';
  const SCRIPT_URL = 'https://dldir1.qq.com/WechatWebDev/devPlatform/px.min.js';
  const param = {
      maskMode: 'all-mask', // 隐私策略, all-mask 或 no-mask, 详见：https://www.npmjs.com/package/@wxobs/miniprogram-sdk#%E6%96%87%E6%A1%A3
      recordCanvas: false, // 若要采集canvas, 设为true
      projectId: xxxxx, // 项目 ID，需替换为体验分析项目 ID
      attrs: {}, // 对回放添加自定义属性，在管理端可通过属性筛选回放 (对象中 key 和 value 类型必须为 string)
  };
  const scriptEle = document.createElement('script');
  scriptEle.type = 'text/javascript';
  scriptEle.async = true;
  scriptEle.onload = function () {
      window.__startPX(param); // 启动采集，返回 Promise<{ sessionId: string }>
  };
  scriptEle.src = SCRIPT_URL;
  document.getElementsByTagName('script')[0].parentNode.appendChild(scriptEle);

})();
</script>

停止采集:

window.___wxobs___.teardown()

设置自定义属性

window.___wxobs___.setAttrs({
    a: 1,
    b: 2
})

# 联合采集

如果要在小程序中采集 web-view 中的内容，需使用联合采集功能。使用方式：

创建小程序项目 A 和 web 项目 B
在小程序内 h5 中，启动 web 端采集 (B 项目）
在小程序（基础库版本>=2.29.1）中，使用 sdk(>=0.1.4) 方式采集（A 项目），调用 setup 函数时，函数将返回一个类型为 string 的 uuid
在使用 web-view 组件时，将步骤 3 中的 uuid 作为 url query 填入到 src 中，例如：

<web-view src="https://www.qq.com?wxobsId={{id}}"></web-view>

在管理端的小程序项目（项目 A）中，进入【设置-联合录制】配置子项目，将子项目配置为 B 项目