跳转到主要内容

​
概述

本指南帮助您解决 Flashduty RUM 使用过程中可能遇到的常见问题，包括数据采集异常、SDK 配置问题和性能优化等方面。

​
数据采集验证

如果您在 RUM 平台上看不到数据，请按以下步骤进行检查。

​
SDK 安装检查

1

检查脚本引入

确认 RUM SDK 是否正确引入：
<script
  src="https://static.flashcat.cloud/browser-sdk/v0/flashcat-rum.js"
  type="text/javascript"
></script>
<script>
  window.FC_RUM &&
    window.FC_RUM.init({
      applicationId: "您的应用ID",
      clientToken: "您的客户端令牌",
      service: "<SERVICE_NAME>",
      env: "<ENV_NAME>",
      version: "1.0.0",
      sessionSampleRate: 10
    });
</script>
2

检查控制台

打开浏览器开发者工具（F12），查看 Console 面板是否有 JavaScript 报错。
3

验证配置

确认应用 ID 和客户端令牌是否与 RUM 控制台中的配置一致。

​
网络请求检查

  1. 打开浏览器开发者工具的 Network 面板
  2. 筛选 browser.flashcat.cloud 的请求
  3. 确认请求状态码为 200
  4. 如果请求失败，查看具体错误信息
如果看到 CORS 错误，请检查您的 CSP 配置是否正确。

​
浏览器兼容性

确认您使用的浏览器版本是否受支持：
浏览器最低版本
Chrome60+
Firefox60+
Safari12+
Edge15+
Internet Explorer11（部分功能受限）

​
广告拦截器影响

部分广告拦截插件可能会阻止 RUM SDK 的运行。建议将您的域名和 browser.flashcat.cloud 加入白名单。

​
常见问题解决

问题：已完成 SDK 配置，但平台上没有数据。解决方案：
  1. 等待数据同步：数据一般在 2-5 分钟内显示
  2. 检查初始化时机：确保 SDK 在页面加载时就完成初始化
  3. 检查采样率：确认采样率设置合理 
flashcatRum.init({
  // ... 其他配置
  sessionSampleRate: 100  // 设为 100 表示采集所有会话
});
  1. 检查用户授权：确认用户跟踪授权状态
flashcatRum.setTrackingConsent("granted");
问题：用户行为数据不完整。解决方案：
  1. 启用行为跟踪：
flashcatRum.init({
  // ... 其他配置
  trackUserInteractions: true
});
  1. 为自定义元素添加标记：
<button data-action-name="提交表单">提交</button>
  1. 手动记录复杂交互：
flashcatRum.addAction("click", "自定义按钮点击");
问题：JavaScript 异常未被记录。解决方案：
  1. 启用异常跟踪：
flashcatRum.init({
  // ... 其他配置
  trackErrors: true
});
  1. 手动上报 try-catch 中的异常：
try {
  // 可能出错的代码
} catch (error) {
  console.error(error);
  flashcatRum.addError(error);
}
  1. 配置 Source Map：便于定位生产环境的问题，详见 Source Mapping
问题：担心 RUM SDK 影响网站性能。解决方案：
  1. 只启用必要的功能：
flashcatRum.init({
  // ... 其他配置
  trackResources: true,
  trackLongTasks: false,  // 关闭不需要的功能
  trackErrors: true,
  trackUserInteractions: true
});
  1. 调整采样率：
flashcatRum.init({
  // ... 其他配置
  sessionSampleRate: 50  // 只采集 50% 的会话
});
  1. 过滤非关键资源：
flashcatRum.init({
  // ... 其他配置
  beforeSend: (event) => {
    // 过滤掉非关键资源
    if (event.type === 'resource' && event.resource.url.includes('/static/')) {
      return false;
    }
    return true;
  }
});
问题：CSP 策略阻止 RUM SDK 运行。解决方案：在您的 CSP 配置中添加以下规则：
script-src 'self' https://static.flashcat.cloud;
connect-src 'self' https://browser.flashcat.cloud;
问题：SPA 应用的路由切换未被记录。解决方案：
import { useEffect } from "react";
import { useLocation } from "react-router-dom";

function RumRouteTracker() {
  const location = useLocation();

  useEffect(() => {
    flashcatRum.startView({
      name: location.pathname,
      url: location.pathname + location.search
    });
  }, [location]);

  return null;
}

// 在 App 组件中使用
function App() {
  return (
    <Router>
      <RumRouteTracker />
      {/* 其他路由 */}
    </Router>
  );
}

​
高级调试

​
启用调试模式

开启调试模式可在控制台获取详细日志： 
flashcatRum.init({
  // ... 其他配置
  debug: true
});

​
强制数据采集

测试时可强制开启全量数据采集： 
flashcatRum.init({
  // ... 其他配置
  sessionSampleRate: 100,
  sessionReplaySampleRate: 100
});
请勿在生产环境使用 100% 采样率，以避免产生过多数据和费用。

​
控制台调试命令

在浏览器控制台中可使用以下命令： 
// 获取 RUM 内部上下文
window.FC_RUM.getInternalContext();

// 获取当前会话 ID
window.FC_RUM.getSessionId();

// 获取当前页面 ID  
window.FC_RUM.getViewId();

// 手动发送测试事件
window.FC_RUM.addAction('test', 'debug_action');

​
网络请求分析

  1. 打开开发者工具 Network 面板
  2. 筛选 browser.flashcat.cloud 请求
  3. 查看请求 Payload 确认数据内容
  4. 检查 Response 确认上报成功

​
常见问题解答

一般在 2-5 分钟内显示，高峰期可能稍有延迟。
支持 iOS Safari 和 Android Chrome 等主流移动端浏览器，但部分高级功能（如 Long Tasks 监控）可能受限。
可以根据 URL 条件判断是否初始化：
// 排除管理后台页面
if (!window.location.pathname.startsWith("/admin")) {
  flashcatRum.init({
    // ... 配置
  });
}
需要以下配置：
  1. 使用相同的应用 ID 和客户端令牌
  2. 设置一致的用户标识
  3. 启用跨域跟踪：
flashcatRum.init({
  // ... 其他配置
  allowedTracingUrls: [
    "https://example.com",
    "https://app.example.com",
    "https://shop.example.com"
  ]
});
可以通过以下方式：
  1. 降低采样率：设置 sessionSampleRate 为 10-50
  2. 关闭不必要的功能：如 trackLongTasks: false
  3. 排除特定页面：不在管理后台等内部页面初始化
  4. 配置数据过滤：使用 beforeSend 过滤非关键数据

​
联系技术支持

如果按上述步骤排查后仍有问题，请联系我们的技术支持团队。
1

准备诊断信息

请收集以下信息：
  • 应用 ID
  • 浏览器类型和版本
  • SDK 版本
  • 控制台错误截图
  • Network 面板请求截图
  • 问题复现步骤
2

联系支持