@wxobs/replay-sdk
v0.1.45
Published
## 概述
Downloads
7
Keywords
Readme
#播放器 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();