@wxobs/replay-sdk

#播放器 SDK 文档

概述

微信小程序回放 SDK 为开发者提供了一种在自己的系统中集成微信小程序的可回溯能力。通过使用此 SDK，可以拉取回放列表并播放相应的回放。

1. 鉴权

为了使用 SDK，您需要通过我们提供的 SPACE_APPID 和 SPACE_SECRET 进行鉴权。通过如下请求，换取临时的 access_token:

curl --location 'http://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=${SPACE_APPID}&secret=${SPACE_SECRET}'

access_token 将用于后续 SDK 的使用。

2. 安装与引入

安装依赖：

npm install @wxobs/replay-sdk

在 js 中引用

import * as sdk from '@wxobs/replay-sdk'

3. 回放列表拉取

使用 sdk.getSessionList 方法拉取回放列表：

function getSessionList(
  param: {
    projectKey: string;
    beginTime: number;
    endTime: number;
    advanceFilter: IAdvanceFilter;
  },
  token: string // access_token
): Promise<ISessionList>

参数说明

param: 筛选参数对象，包含以下属性：

• projectKey: 项目 Key。
• beginTime: 开始时间（Unix 时间戳，单位秒）。
• endTime: 结束时间（Unix 时间戳，单位秒）。
• advanceFilter: 高级筛选器对象，支持时间、路径、query、sdk 版本、小程序版本、自定义事件、自定义属性、网络、系统、点击等条件。支持多个条件通过与或组合筛选。

token: 鉴权获取的 access_token。

返回值说明

ISessionList 类型对象，包含符合筛选条件的回放 id 列表及回放数量：

interface ISessionList {
  sessionList: SessionList;
  sessionCount: number;
}

type SessionList = ISessionIndex[];

interface ISessionIndex {
  uuid: string;
  beginTime: string;
  endTime: string;
  pathArr: string;
  pathSeq: string;
  sdkVersion: string;
  timeGap: number;
  eventCount: number;
  activeTime: number;
  eventSeq: string;
}

示例

使用筛选器拉取回放列表：

const filter: IAdvanceFilterParam = {
  advanceFilter: {
    conditions: [
      {
        conditions: [
          {
            id: 1,
            type: IConditionType.Path,
            op: IConditionOpType.MultiplexContainLike,
            input: {
              path: "/example/path",
              query: [
                {
                  type: IConditionType.Query,
                  op: IConditionOpType.Is,
                  input: {
                    key: "param1",
                    value: "value1",
                  },
                },
              ],
            },
          },
          {
            id: 2,
            type: IConditionType.SdkVersion,
            op: IConditionOpType.GreaterThan,
            input: "1.0.0",
          },
        ],
        id: 1,
      },
    ],
    order: "bd",
  },
  beginTime: 1623614400,
  endTime: 1623700800,
};

const sessionList = await sdk.getSessionList(filter, token.access_token);
console.log(sessionList);
[{
    uuid: "202306131630/577f1-7cc9-a33b-9ca7-3dbd1",
    beginTime: "2023-06-10 09:39:53",
    endTime: "2023-06-10 09:49:31"
}, ...]

筛选器详细定义见 types/filter.d.ts

4. 播放回放

要播放回放，您需要创建一个播放器实例，并传入一个容器。我们将加载相应的数据并播放。一个小程序回放由多个页面的数据构成，您可以根据自己的需求选择平铺多个页面播放，或按照用户交互时的页面栈播放。

创建播放器

function createPlayer(options: ICreatePlayerOptions) => Promise<IPlayer>

interface ICreatePlayerOptions {
  container?: HTMLDivElement;
  projectKey: string;
  sessionId: string;
  mode?: 'stack' | 'tile';
  token: string; // access_token
  subProjectKey?: string; // 使用联合回放时的子项目
  customWording?: {
    ReplayHidden?: string; // 小程序 onAppHide 时的蒙版文案
    ReplayNotCollect?: string; // 小程序出现未采集页面时的蒙版文案
    InThirdMiniprogram?: string; // 用户在使用第三方小程序时的蒙版文案
  }
}

播放器 API

播放器实例提供了以下 API 可供使用：

interface IPlayer {
  play(): void;
  pause(): void;
  seek(time: number): void;
  setPlayerSpeed(rate: number): void;
  onTimeChange(callback: (currentTime: number, unloadedTime: number[]) => void): () => void;
  // unloadedTime 指资源还没完全加载好的时间段，此时是不可播放的
  onPlayStateChange(
    callback: (paused: boolean, reachEnd?: boolean) => void,
  ): () => void;
  getInfo(): IPlayerInfo;
  destroy(): void;
  getPages(): IPageInfo[];
}

interface IPlayerInfo {
  startTime: number;
  endTime: number;
  totalTime: number;
  inactiveInterval: [number, number][];
  appConfig: AppConfig; // 小程序的各种元数据，如基础库版本、屏幕尺寸
    customAttrs: {
    key: string | null | undefined;
    value: string | null | undefined;
  }[]; // 自定义属性
  routeEvents: {
    timestamp: number;
    typeStr: "Start" | "NavigateTo" | "RedirectTo" | "NavigateBack" | "SwitchTab" | "AppLaunch" | "ReLaunch" | "AutoReLaunch"
    type: number
    data: {
      path?: string // Start类型不存在path，其它均有path
      shouldCapture: boolean // 该页面是否被采集
    }
  }[];
  appserviceEvents: eventWithTime[] // 所有逻辑层事件。事件定义在 types/events.ts 中
}

interface IPageInfo {
  path: string;
  query: { [key: string]: string };
  container: HTMLDivElement;
  webviewId: number;
  mount: (parent: HTMLElement) => void; // 该方法用于将某个页面放到给定的元素中播放
}

使用示例

const projectKey = 'xxxx';

const token = await getToken(); // 从后端获取 access_token
const data = await getSessionList({
  projectKey,
  beginTime: Math.floor(Date.now() / 1000) - 60 * 24 * 7,
  endTime: Math.floor(Date.now() / 1000),
  advanceFilter: {
    conditions: [],
    order: 'bd',
  },
},
token.access_token,
); // 获取回放列表
console.log(data.sessionCount, data.sessionList);


const container = document.createElement('div');
document.body.appendChild(container);
const player = await createPlayer({
    container,
    projectKey,
    sessionId: data.sessionList[0].uuid,
    mode: 'tile',
    token: token.access_token,
});
player.play();