k.analytics
站点访问、静态资源、异常错误查询与自定义目标事件追踪
| 适用上下文 | 前置条件 | 典型用途 |
|---|---|---|
Api / CodeBlock / <script env="server"> | 站点已开启统计采集;track() 需已在后台配置对应自定义目标名称 | 查询访客流量、静态资源与错误报表,或在请求中上报转化目标 |
快速上手
k.api.get("analytics-quick", () => {
const visitors = k.analytics.visitor.summary({ top: 5 })
const errors = k.analytics.error.summary({ top: 5 })
// 若站点配置了自定义目标事件,可同步记录本次转化
k.analytics.track("api_health_check")
return {
range: visitors.startDate + " ~ " + visitors.endDate,
pageViews: visitors.pageViews,
uniqueVisitors: visitors.uniqueVisitors,
totalErrors: errors.totalErrors
}
})方法速查
| 方法 / 属性 | 说明 | 返回值 |
|---|---|---|
k.analytics.visitor.list(filter?) | 分页查询匿名化 IP 访客明细日志 | PagedResult<VisitorLogItem> |
k.analytics.visitor.summary(filter?) | 按日期区间聚合访客流量、趋势与维度排行 | VisitorSummary |
k.analytics.resource.list(filter?) | 查询近期有界环形缓冲中的静态资源请求明细 | PagedResult<ResourceLogItem> |
k.analytics.resource.summary(filter?) | 获取完整日期区间的资源请求、带宽与防盗链汇总 | ResourceSummary |
k.analytics.error.list(filter?) | 分页查询页面、API 与自定义异常明细 | PagedResult<ErrorLogItem> |
k.analytics.error.summary(filter?) | 按日期区间汇总错误总数、受影响访客与高频错误 | ErrorSummary |
k.analytics.track(customName, parameter?) | 为当前 HTTP 请求记录自定义目标转化或 A/B 事件 | void |
概述
k.analytics 提供服务端统计查询与事件追踪能力,开发者无需依赖后台界面即可读取站点访问概况、近期静态资源请求明细、错误报告,或触发自定义转化目标事件。
list() 运行时返回结构说明
在编辑器的 TypeScript 智能提示中,三个 list(filter?) 方法的返回类型均显示为 any。在运行时,它们统一返回分页结果对象 PagedResult<T>(包含 items、totalCount、pageIndex、pageSize、totalPages、hasPreviousPage、hasNextPage、isPartial 与 notice 字段)。
日期范围与通用参数规则
所有 list() 和 summary() 方法共用以下时间窗与边界约束:
- 日期格式:
startDate与endDate为闭区间,格式必须为yyyy-MM-dd;统计日界线为站点本地时间每日04:00。格式无效或startDate > endDate会抛出异常。 - 默认区间:省略日期参数时,默认查询当前统计周的周一至当前统计日(例如某周六查询时为周一至周六共 6 天)。
- 最大跨度:单次查询跨度不得超过
366天,否则抛出异常。 - 分页与排行上限:
pageIndex最小为1;pageSize与top默认为20(传入<= 0时回退到20),最大为200(超出会被截断为200)。
visitor 访客统计
visitor.list()
分页查询指定日期区间内的访客访问明细日志。
隐私保护
明细中的 ip 字段仅返回匿名化处理后的 IP 地址,原始未脱敏 IP 不会暴露给脚本。
参数:
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
filter | VisitorLogFilter | 否 | {} | 过滤条件对象 |
filter.startDate | string | 否 | 本周一 | 起始日期(yyyy-MM-dd) |
filter.endDate | string | 否 | 当日 | 结束日期(yyyy-MM-dd) |
filter.type | string | 否 | "all" | 访客类型:"all"、"human"、"bot"、"error"(无效值抛错) |
filter.isMobile | boolean | 否 | - | 是否移动端访问 |
filter.statusCode | number | 否 | - | 精确 HTTP 状态码 |
filter.keyword | string | 否 | - | 按 URL、页面名、Referer、国家/城市、UA、UTM 或匿名 IP 搜索 |
filter.pageIndex | number | 否 | 1 | 页码(从 1 开始) |
filter.pageSize | number | 否 | 20 | 每页条数(1–200) |
返回: PagedResult<VisitorLogItem>。
k.api.get("visitor-logs", () => {
const page = k.analytics.visitor.list({
type: "human",
isMobile: false,
statusCode: 200,
pageIndex: 1,
pageSize: 20
})
return {
totalCount: page.totalCount,
pageIndex: page.pageIndex,
pageSize: page.pageSize,
totalPages: page.totalPages,
items: page.items
}
})visitor.summary()
按日期区间聚合访客访问量、独立访客数、机器人占比、按日趋势及各维度排行榜。
参数:
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
filter | AnalyticsSummaryFilter | 否 | {} | 摘要过滤对象 |
filter.startDate | string | 否 | 本周一 | 起始日期(yyyy-MM-dd) |
filter.endDate | string | 否 | 当日 | 结束日期(yyyy-MM-dd) |
filter.top | number | 否 | 20 | 各排行/分布返回最大条目数(1–200) |
filter.includeDimensions | boolean | 否 | true | 是否填充 dimensions 聚合数组 |
返回: VisitorSummary。
k.api.get("visitor-summary", () => {
const currentWeek = k.analytics.visitor.summary()
const customReport = k.analytics.visitor.summary({
startDate: currentWeek.startDate,
endDate: currentWeek.endDate,
top: 10,
includeDimensions: true
})
return {
range: customReport.startDate + " ~ " + customReport.endDate,
pageViews: customReport.pageViews,
uniqueVisitors: customReport.uniqueVisitors,
botVisits: customReport.botVisits,
daysCount: customReport.days.length,
topPages: customReport.topPages
}
})resource 静态资源统计
resource.list()
查询最近记录的静态资源请求明细列表。
近期有界环形缓冲说明
k.analytics.resource.list() 仅读取站点近期定容环形缓冲区(最多保留近期约 102,400 条资源请求记录),因此返回结果的 isPartial 恒为 true,notice 固定为 "Resource detail is read from the bounded recent resource ring. Use summary() for complete date-range totals."。如需任意日期区间的完整带宽与数量统计,请使用 k.analytics.resource.summary()。
参数:
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
filter | ResourceLogFilter | 否 | {} | 资源日志过滤条件 |
filter.startDate | string | 否 | 本周一 | 起始日期(yyyy-MM-dd) |
filter.endDate | string | 否 | 当日 | 结束日期(yyyy-MM-dd) |
filter.type | string | 否 | "all" | 资源类型:"all"、"image"、"css"、"javascript"(兼容别名 "js")、"file"、"system"、"unknown" |
filter.isBot | boolean | 否 | - | 是否机器人请求 |
filter.isProtected | boolean | 否 | - | 是否触发资源防盗链保护 |
filter.statusCode | number | 否 | - | 精确 HTTP 状态码 |
filter.keyword | string | 否 | - | 按 URL、Referer、国家代码、UA 或匿名 IP 搜索 |
filter.pageIndex | number | 否 | 1 | 页码(从 1 开始) |
filter.pageSize | number | 否 | 20 | 每页条数(1–200) |
返回: PagedResult<ResourceLogItem>(isPartial 为 true)。
k.api.get("resource-logs", () => {
const page = k.analytics.resource.list({
type: "js",
isBot: false,
isProtected: false,
pageIndex: 1,
pageSize: 10
})
return {
isPartial: page.isPartial,
notice: page.notice,
totalCount: page.totalCount,
items: page.items
}
})resource.summary()
按日期区间获取完整的静态资源请求量、按文件类型分布的带宽统计、外部引用域名与 404/受保护资源关系分析。
参数:
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
filter | ResourceSummaryFilter | 否 | {} | 资源摘要过滤条件 |
filter.startDate | string | 否 | 本周一 | 起始日期(yyyy-MM-dd) |
filter.endDate | string | 否 | 当日 | 结束日期(yyyy-MM-dd) |
filter.top | number | 否 | 20 | 各排行/分布返回最大条目数(1–200) |
filter.includeDimensions | boolean | 否 | true | 是否返回 dimensions 维度数组 |
filter.includeRelations | boolean | 否 | true | 是否返回 foundRelations、notFoundRelations、protectedRelations |
返回: ResourceSummary。
k.api.get("resource-summary", () => {
const report = k.analytics.resource.summary({
top: 10,
includeDimensions: true,
includeRelations: true
})
return {
startDate: report.startDate,
endDate: report.endDate,
totalRequests: report.totalRequests,
totalBytes: report.totalBytes,
protectedCount: report.protectedCount,
bandwidthByFileType: report.bandwidthByFileType
}
})error 错误统计
error.list()
分页查询站点运行过程中记录的页面、API 或自定义异常明细。
参数:
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
filter | ErrorLogFilter | 否 | {} | 错误日志过滤条件 |
filter.startDate | string | 否 | 本周一 | 起始日期(yyyy-MM-dd) |
filter.endDate | string | 否 | 当日 | 结束日期(yyyy-MM-dd) |
filter.type | string | 否 | "all" | 错误类型:"all"、"page"、"api"、"custom" |
filter.isBot | boolean | 否 | - | 是否机器人触发 |
filter.statusCode | number | 否 | - | 精确 HTTP 状态码 |
filter.keyword | string | 否 | - | 按 URL、错误消息、级别、Referer、IP 或 UA 搜索 |
filter.pageIndex | number | 否 | 1 | 页码(从 1 开始) |
filter.pageSize | number | 否 | 20 | 每页条数(1–200) |
返回: PagedResult<ErrorLogItem>。
k.api.get("error-logs", () => {
const page = k.analytics.error.list({
type: "all",
pageIndex: 1,
pageSize: 10
})
return {
totalCount: page.totalCount,
items: page.items.map((item) => ({
id: item.id,
time: item.time,
errorType: item.errorType,
statusCode: item.statusCode,
url: item.url,
message: item.message
}))
}
})error.summary()
聚合日期区间内的错误总数、受影响访客数、按日分布、错误类型占比及高频错误排行。
参数:
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
filter | AnalyticsSummaryFilter | 否 | {} | 摘要过滤对象 |
filter.startDate | string | 否 | 本周一 | 起始日期(yyyy-MM-dd) |
filter.endDate | string | 否 | 当日 | 结束日期(yyyy-MM-dd) |
filter.top | number | 否 | 20 | 高频错误与维度最大条目数(1–200) |
filter.includeDimensions | boolean | 否 | true | 是否返回 dimensions 维度数组 |
返回: ErrorSummary。
k.api.get("error-summary", () => {
const report = k.analytics.error.summary({
top: 10,
includeDimensions: true
})
return {
startDate: report.startDate,
endDate: report.endDate,
totalErrors: report.totalErrors,
affectedUsers: report.affectedUsers,
types: report.types,
highFrequencyErrors: report.highFrequencyErrors
}
})track() 自定义事件追踪
为当前 HTTP 请求记录一条自定义目标(Custom Goal)事件。
生效前提
仅当站点启用了**路径分析(Navigation Flow)**或 A/B 测试(A/B Testing),且配置了名称与 customName 完全一致的自定义目标时,调用 k.analytics.track() 才会写入目标转化与 A/B 转化统计;否则调用同步返回且不产生报错。
参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
customName | string | 是 | 自定义目标事件名称,需与站点目标配置中的自定义事件名匹配 |
parameter | any | 否 | 可选参数。传入大于 0 的数值、数字字符串,或包含 revenue、amount、value、total、price 键的对象时,将提取作为转化金额记录 |
返回: void(脚本运行时表达式值为 undefined)。
// 仅记录事件触发
k.analytics.track("newsletter_subscribe")
// 传入对象并附带转化金额
k.analytics.track("checkout_complete", {
revenue: 199.5,
plan: "pro"
})TypeScript 定义
展开完整 TypeScript 定义
interface kAnalytics {
visitor: VisitorAnalyticsModule;
resource: ResourceAnalyticsModule;
error: ErrorAnalyticsModule;
track(customName: string, parameter?: any): void;
}
interface VisitorAnalyticsModule {
list(filter?: VisitorLogFilter): any;
summary(filter?: AnalyticsSummaryFilter): VisitorSummary;
}
interface ResourceAnalyticsModule {
list(filter?: ResourceLogFilter): any;
summary(filter?: ResourceSummaryFilter): ResourceSummary;
}
interface ErrorAnalyticsModule {
list(filter?: ErrorLogFilter): any;
summary(filter?: AnalyticsSummaryFilter): ErrorSummary;
}
interface AnalyticsDateFilter {
startDate?: string; // yyyy-MM-dd,默认当前统计周的周一
endDate?: string; // yyyy-MM-dd,默认当前统计日
}
interface AnalyticsSummaryFilter extends AnalyticsDateFilter {
top?: number; // 排行榜最大条数,默认 20,上限 200
includeDimensions?: boolean; // 是否包含 dimensions 维度明细,默认 true
}
interface ResourceSummaryFilter extends AnalyticsSummaryFilter {
includeRelations?: boolean; // 是否包含资源引用关系数组,默认 true
}
interface PagedAnalyticsFilter extends AnalyticsDateFilter {
pageIndex?: number; // 页码,默认 1(小于 1 时按 1 处理)
pageSize?: number; // 每页条数,默认 20,上限 200
keyword?: string; // 不区分大小写的关键词过滤,最长 256 字符
statusCode?: number; // 精确匹配 HTTP 状态码
}
interface VisitorLogFilter extends PagedAnalyticsFilter {
type?: string; // "all" | "human" | "bot" | "error"
isMobile?: boolean;
}
interface ResourceLogFilter extends PagedAnalyticsFilter {
type?: string; // "all" | "image" | "css" | "javascript" | "js" | "file" | "system" | "unknown"
isBot?: boolean;
isProtected?: boolean;
}
interface ErrorLogFilter extends PagedAnalyticsFilter {
type?: string; // "all" | "page" | "api" | "custom"
isBot?: boolean;
}
interface PagedResult<T> {
items: T[];
totalCount: number;
pageIndex: number;
pageSize: number;
totalPages: number;
hasPreviousPage: boolean;
hasNextPage: boolean;
isPartial: boolean; // resource.list() 固定为 true
notice?: string; // resource.list() 返回缓冲说明,其余通常为 null
}
interface VisitorLogItem {
id: number;
time: Date;
url: string;
pageName: string;
objectId: string;
referrer: string;
ip: string;
city: string;
countryCode: string;
continent: string;
userAgent: string;
application: string;
browser: string;
device: string;
isMobile: boolean;
isBot: boolean;
botName: string;
statusCode: number;
size: number;
durationMs: number;
utm: string;
}
interface VisitorSummary {
startDate: string;
endDate: string;
pageViews: number;
uniqueVisitors: number;
botVisits: number;
totalVisits: number;
humanBytes: number;
botBytes: number;
totalBytes: number;
errorCount: number;
errorRate: number;
humanRate: number;
botRate: number;
days: VisitorDailySummary[];
topReferrers: AnalyticsValueItem[];
topReferrerUrls: AnalyticsValueItem[];
topApplications: AnalyticsValueItem[];
topPages: AnalyticsValueItem[];
topPageIds: AnalyticsValueItem[];
topBrowsers: AnalyticsValueItem[];
topDevices: AnalyticsValueItem[];
topCountries: AnalyticsValueItem[];
statusCodes: AnalyticsValueItem[];
ipUserTypes: AnalyticsValueItem[];
utm: AnalyticsValueItem[];
dpr: AnalyticsValueItem[];
colorSchemes: AnalyticsValueItem[];
viewportWidths: AnalyticsValueItem[];
topErrors: VisitorErrorSummaryItem[];
bots: BotSummaryReport;
countryNetwork: NetworkCountrySummary[];
connectionTypes: ConnectionTypeSummary[];
dimensions: AnalyticsDimension[];
}
interface ResourceLogItem {
id: number;
time: Date;
url: string;
resourceType: string;
referrer: string;
ip: string;
countryCode: string;
userAgent: string;
application: string;
browser: string;
device: string;
isMobile: boolean;
isBot: boolean;
botName: string;
isProtected: boolean;
statusCode: number;
size: number;
}
interface ResourceSummary {
startDate: string;
endDate: string;
humanRequests: number;
botRequests: number;
totalRequests: number;
humanBytes: number;
botBytes: number;
totalBytes: number;
errorCount: number;
errorRate: number;
protectedCount: number;
humanRate: number;
botRate: number;
days: ResourceDailySummary[];
requestsByFileType: AnalyticsValueItem[];
bandwidthByFileType: AnalyticsValueItem[];
statusCodes: AnalyticsValueItem[];
externalDomains: ResourceExternalDomainItem[];
topResources: ResourceRankItem[];
topSources: ResourceRankItem[];
topSystemRoutes: ResourceRankItem[];
notFound: ResourceNotFoundSummary;
protectedResources: ResourceUsageItem[];
foundRelations: ResourceRelationItem[];
notFoundRelations: ResourceRelationItem[];
protectedRelations: ResourceRelationItem[];
bots: BotSummaryReport;
countryNetwork: NetworkCountrySummary[];
connectionTypes: ConnectionTypeSummary[];
dimensions: AnalyticsDimension[];
}
interface ErrorLogItem {
id: number;
time: Date;
errorType: string;
level: string;
url: string;
message: string;
referrer: string;
ip: string;
userAgent: string;
application: string;
browser: string;
device: string;
isMobile: boolean;
isBot: boolean;
botName: string;
statusCode: number;
objectId: string;
}
interface ErrorSummary {
startDate: string;
endDate: string;
totalErrors: number;
errorRate: number;
affectedUsers: number;
affectedUserRate: number;
humanErrors: number;
botErrors: number;
humanRate: number;
botRate: number;
days: ErrorDailySummary[];
types: AnalyticsValueItem[];
highFrequencyErrors: ErrorFrequencyItem[];
dimensions: AnalyticsDimension[];
}
interface VisitorDailySummary {
date: string;
pageViews: number;
uniqueVisitors: number;
botVisits: number;
totalVisits: number;
humanBytes: number;
botBytes: number;
totalBytes: number;
}
interface ResourceDailySummary {
date: string;
humanRequests: number;
botRequests: number;
totalRequests: number;
humanBytes: number;
botBytes: number;
totalBytes: number;
}
interface ErrorDailySummary {
date: string;
totalErrors: number;
affectedUsers: number;
humanErrors: number;
botErrors: number;
pageErrors: number;
apiErrors: number;
customErrors: number;
}
interface AnalyticsValueItem {
name: string;
value: number;
share: number;
}
interface AnalyticsDimension {
name: string;
total: number;
items: AnalyticsValueItem[];
}
interface VisitorErrorSummaryItem {
url: string;
statusCode: number;
count: number;
}
interface BotSummaryReport {
visits: number;
trafficShare: number;
goodBotRate: number;
badBotRate: number;
items: BotSummaryItem[];
}
interface BotSummaryItem {
name: string;
status: string;
visits: number;
blockedRequests: number;
blocked: boolean;
trafficShare: number;
}
interface NetworkCountrySummary {
countryCode: string;
userCount: number;
userShare: number;
averageRtt: number;
downloadSpeedMbps: number;
}
interface ConnectionTypeSummary {
name: string;
userCount: number;
userShare: number;
}
interface ResourceRankItem {
url: string;
requests: number;
bytes: number;
}
interface ResourceExternalDomainItem {
domain: string;
requests: number;
bytes: number;
blockedRequests: number;
blockedShare: number;
isBlocked: boolean;
}
interface ResourceRelationItem {
resourceUrl: string;
sourceUrl: string;
requests: number;
}
interface ResourceReferrerItem {
sourceUrl: string;
requests: number;
}
interface ResourceUsageItem {
resourceUrl: string;
requests: number;
topReferrers: ResourceReferrerItem[];
}
interface ResourceNotFoundSummary {
resourceCount: number;
sourceCount: number;
topResources: ResourceUsageItem[];
topSources: ResourceReferrerItem[];
}
interface ErrorFrequencyItem {
rank: number;
type: string;
statusCode: number;
path: string;
count: number;
}相关文档
- k.logger — 业务代码日志记录与查询
- 访问统计(后台) — 后台流量报表与访问明细说明
- 资源守护(后台) — 资源带宽与防盗链配置
- A/B 测试(后台) — 转化目标与 A/B 实验管理