Skip to content

k.analytics ​

站点访问、静态资源、异常错误查询与自定义目标事件追踪

适用上下文前置条件典型用途
Api / CodeBlock / <script env="server">站点已开启统计采集;track() 需已在后台配置对应自定义目标名称查询访客流量、静态资源与错误报表,或在请求中上报转化目标

快速上手 ​

js
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 提供服务端统计查询与事件追踪能力,开发者无需依赖后台界面即可读取站点访问概况、近期静态资源请求明细、错误报告,或触发自定义转化目标事件。

后台对应功能

站点统计数据的采集开关、可视化报表及目标配置位于 Kooboo 后台的访问统计、资源守护与 A/B 测试。

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 不会暴露给脚本。

参数:

参数类型必填默认值说明
filterVisitorLogFilter否{}过滤条件对象
filter.startDatestring否本周一起始日期(yyyy-MM-dd)
filter.endDatestring否当日结束日期(yyyy-MM-dd)
filter.typestring否"all"访客类型:"all"、"human"、"bot"、"error"(无效值抛错)
filter.isMobileboolean否-是否移动端访问
filter.statusCodenumber否-精确 HTTP 状态码
filter.keywordstring否-按 URL、页面名、Referer、国家/城市、UA、UTM 或匿名 IP 搜索
filter.pageIndexnumber否1页码(从 1 开始)
filter.pageSizenumber否20每页条数(1–200)

返回: PagedResult<VisitorLogItem>。

js
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() ​

按日期区间聚合访客访问量、独立访客数、机器人占比、按日趋势及各维度排行榜。

参数:

参数类型必填默认值说明
filterAnalyticsSummaryFilter否{}摘要过滤对象
filter.startDatestring否本周一起始日期(yyyy-MM-dd)
filter.endDatestring否当日结束日期(yyyy-MM-dd)
filter.topnumber否20各排行/分布返回最大条目数(1–200)
filter.includeDimensionsboolean否true是否填充 dimensions 聚合数组

返回: VisitorSummary。

js
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()。

参数:

参数类型必填默认值说明
filterResourceLogFilter否{}资源日志过滤条件
filter.startDatestring否本周一起始日期(yyyy-MM-dd)
filter.endDatestring否当日结束日期(yyyy-MM-dd)
filter.typestring否"all"资源类型:"all"、"image"、"css"、"javascript"(兼容别名 "js")、"file"、"system"、"unknown"
filter.isBotboolean否-是否机器人请求
filter.isProtectedboolean否-是否触发资源防盗链保护
filter.statusCodenumber否-精确 HTTP 状态码
filter.keywordstring否-按 URL、Referer、国家代码、UA 或匿名 IP 搜索
filter.pageIndexnumber否1页码(从 1 开始)
filter.pageSizenumber否20每页条数(1–200)

返回: PagedResult<ResourceLogItem>(isPartial 为 true)。

js
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/受保护资源关系分析。

参数:

参数类型必填默认值说明
filterResourceSummaryFilter否{}资源摘要过滤条件
filter.startDatestring否本周一起始日期(yyyy-MM-dd)
filter.endDatestring否当日结束日期(yyyy-MM-dd)
filter.topnumber否20各排行/分布返回最大条目数(1–200)
filter.includeDimensionsboolean否true是否返回 dimensions 维度数组
filter.includeRelationsboolean否true是否返回 foundRelations、notFoundRelations、protectedRelations

返回: ResourceSummary。

js
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 或自定义异常明细。

参数:

参数类型必填默认值说明
filterErrorLogFilter否{}错误日志过滤条件
filter.startDatestring否本周一起始日期(yyyy-MM-dd)
filter.endDatestring否当日结束日期(yyyy-MM-dd)
filter.typestring否"all"错误类型:"all"、"page"、"api"、"custom"
filter.isBotboolean否-是否机器人触发
filter.statusCodenumber否-精确 HTTP 状态码
filter.keywordstring否-按 URL、错误消息、级别、Referer、IP 或 UA 搜索
filter.pageIndexnumber否1页码(从 1 开始)
filter.pageSizenumber否20每页条数(1–200)

返回: PagedResult<ErrorLogItem>。

js
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() ​

聚合日期区间内的错误总数、受影响访客数、按日分布、错误类型占比及高频错误排行。

参数:

参数类型必填默认值说明
filterAnalyticsSummaryFilter否{}摘要过滤对象
filter.startDatestring否本周一起始日期(yyyy-MM-dd)
filter.endDatestring否当日结束日期(yyyy-MM-dd)
filter.topnumber否20高频错误与维度最大条目数(1–200)
filter.includeDimensionsboolean否true是否返回 dimensions 维度数组

返回: ErrorSummary。

js
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 转化统计;否则调用同步返回且不产生报错。

参数:

参数类型必填说明
customNamestring是自定义目标事件名称,需与站点目标配置中的自定义事件名匹配
parameterany否可选参数。传入大于 0 的数值、数字字符串,或包含 revenue、amount、value、total、price 键的对象时,将提取作为转化金额记录

返回: void(脚本运行时表达式值为 undefined)。

js
// 仅记录事件触发
k.analytics.track("newsletter_subscribe")

// 传入对象并附带转化金额
k.analytics.track("checkout_complete", {
    revenue: 199.5,
    plan: "pro"
})

TypeScript 定义 ​

展开完整 TypeScript 定义
ts
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;
}

相关文档 ​