📖 接入文档

三步快速接入云星统计平台，开始收集您的网站数据

1 注册账号

在云星统计平台注册一个账号，用于管理您的网站统计数据。

立即注册

已有账号？登录后直接进入仪表盘添加域名。

2 添加域名并验证所有权

登录后进入仪表盘，在"域名管理"区域点击"添加域名"，输入您要统计的网站域名。

💡 提示： 域名格式为 example.com，不需要加 https:// 或 www. 前缀。

提交域名后，系统会要求您验证域名所有权。请在您的网站根目录下创建 yxsverify.txt 文件，内容填入系统提供的验证码。

验证文件示例 
# 在您的网站根目录创建文件：yxsverify.txt
# 文件内容为系统提供的 16 位验证码，例如：
a1b2c3d4e5f6g7h8

创建完成后，确保可以通过 https://您的域名/yxsverify.txt 或 http://您的域名/yxsverify.txt 在浏览器中直接访问到该文件，然后点击"验证"按钮完成所有权验证。

⚠ 注意： 验证码有效期为 30 分钟，过期后需重新发起验证。验证通过后可以删除该文件。如果验证失败，请检查文件内容是否完全一致（不含多余空格或换行）。
🔄 备用验证方式（推荐用于热铁盒/CDN 用户）： 如果您的网站也托管在热铁盒网页托管，或使用了 Cloudflare 等 CDN 服务，系统服务器可能因安全机制无法直接访问 yxsverify.txt（返回 403）。此时请在网站根目录额外创建 verify_helper.php 文件，系统将自动通过该云函数读取验证文件内容。
verify_helper.php（备用验证辅助文件） 
<?php
/**
 * 云星统计域名验证辅助文件
 * 读取本地的 yxsverify.txt 验证文件并返回内容
 * 请将此文件放在网站根目录
 */
header('Content-Type: application/json; charset=utf-8');
header('Access-Control-Allow-Origin: *');

// 只接受 POST 请求
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    echo json_encode(['success' => false, 'message' => '仅支持 POST 请求']);
    exit;
}

// 验证请求参数
$input = json_decode(file_get_contents('php://input'), true);
if (!$input) $input = $_POST;
if (($input['verify'] ?? '') !== '1') {
    http_response_code(403);
    echo json_encode(['success' => false, 'message' => '参数无效']);
    exit;
}

// 读取本地验证文件
$filePath = __DIR__ . '/yxsverify.txt';
if (!file_exists($filePath)) {
    http_response_code(404);
    echo json_encode(['success' => false, 'message' => '验证文件不存在']);
    exit;
}

$content = file_get_contents($filePath);
// 去除 BOM 和空白字符
$bom = "\xEF\xBB\xBF";
if (strncmp($content, $bom, 3) === 0) $content = substr($content, 3);
$content = trim($content);

if (empty($content)) {
    http_response_code(500);
    echo json_encode(['success' => false, 'message' => '验证文件内容为空']);
    exit;
}

echo json_encode(['success' => true, 'content' => $content]);

备用验证流程： 系统先尝试直接访问 yxsverify.txt，如果失败（如返回 403），会自动调用 verify_helper.php 云函数来获取验证码内容，无需您手动干预。

3 嵌入 SDK

验证通过后，将以下代码复制到您网站的 <head> 或 <body> 中，将 data-site 的值替换为您的域名。

HTML 
<script src="https://statistics.kscm.top/sdk.js" data-site="your-domain.com"></script>
✅ 完成！ 嵌入后，SDK 将自动开始收集数据，无需任何额外配置。返回仪表盘即可查看实时统计数据。

🔧 SDK 自动采集功能

SDK 加载后会自动执行以下采集，无需任何手动调用：

采集项 说明
页面浏览 (PV) 自动记录每次页面加载，包含 URL、页面标题、来源页
停留时长 记录用户在页面上的停留时间，页面关闭或切换时上报
前端错误 自动捕获 window.onerror 和未处理的 Promise 拒绝
用户环境 浏览器、操作系统、屏幕分辨率、语言偏好

🖥 手动上报后端错误

SDK 提供了 window.yxstat.reportBackendError() 方法，供您在网站后端接口调用失败时手动上报错误。

方法签名

JavaScript 
yxstat.reportBackendError(message, code)

参数说明

参数 类型 说明
message string 错误描述信息（必填）
code string 错误代码，如 ERR_001（可选）

示例

JavaScript 
// 在 API 请求失败时调用
fetch('/api/data')
  .then(res => res.json())
  .catch(err => {
    yxstat.reportBackendError(err.message, 'API_ERR');
  });

// 或在服务端返回错误时调用
yxstat.reportBackendError('数据库连接超时', 'DB_TIMEOUT');

📝 自定义事件

SDK 还提供了 yxstat.track() 方法，用于上报自定义事件。

JavaScript 
// 上报自定义事件
yxstat.track({
  type: 'custom',
  url: '/checkout',
  action: 'purchase',
  value: 'completed',
  ts: Date.now()
});

❓ 常见问题

SDK 会影响网站性能吗？

不会。SDK 体积小巧（约 6KB），所有数据采集都是异步的，不影响页面加载性能。数据上报使用 sendBeacon 在页面空闲时发送。

数据多久能在仪表盘看到？

数据上报后即可在仪表盘查看。页面嵌入 SDK 后，用户访问页面时数据会自动收集并上报。

一个账号可以添加多个域名吗？

可以。在仪表盘的"域名管理"区域可以添加、删除多个域名，每个域名的统计数据独立存储。

数据会保存多久？

每个域名最多保留 60 条数据记录，超出时会自动覆盖最旧的数据，确保始终保留最新的统计信息。

⚠ 注意： 请确保 data-site 属性值与您在仪表盘添加的域名完全一致，否则数据将无法被接收。