JavaScript للمتصفح

يتيح لك Browser SDK الخاص بـ ClickStack تضمين أدوات الرصد في تطبيق الواجهة الأمامية لديك لإرسال الأحداث إلى ClickStack. وهذا يتيح لك عرض طلبات الشبكة والاستثناءات إلى جانب أحداث الواجهة الخلفية ضمن خط زمني واحد.

بالإضافة إلى ذلك، سيلتقط تلقائيًا بيانات إعادة تشغيل الجلسة ويربطها، بحيث يمكنك استعراض ما كان يراه المستخدم بصريًا خطوة بخطوة واستكشاف المشكلات أثناء استخدامه لتطبيقك.

يدمج هذا الدليل ما يلي:

• سجلات وحدة التحكم
• إعادات تشغيل الجلسات
• طلبات XHR/Fetch/Websocket
• الاستثناءات

npm install @hyperdx/browser

import HyperDX from '@hyperdx/browser';

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', //احذفها عند استخدام Managed ClickStack
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i], // حدّده لربط التتبعات من الواجهة الأمامية بطلبات الواجهة الخلفية
    consoleCapture: true, // التقاط سجلات وحدة التحكّم (القيمة الافتراضية false)
    advancedNetworkCapture: true, // التقاط الرؤوس والمحتوى الكامل لطلبات HTTP واستجاباته (القيمة الافتراضية false)
});

<script src="//www.unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>
<script>
  window.HyperDX.init({
    url: 'http://localhost:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', //احذفها عند استخدام Managed ClickStack
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i], // حدّده لربط التتبعات من الواجهة الأمامية بطلبات الواجهة الخلفية
  });
</script>

• apiKey - مفتاح واجهة برمجة تطبيقات للإدخال الخاص بك في ClickStack.
• service - اسم الخدمة الذي ستظهر به الأحداث في واجهة مستخدم HyperDX.
• tracePropagationTargets - قائمة بأنماط Regex لمطابقتها مع طلبات HTTP لربط تتبعات الواجهة الأمامية والخلفية، وسيضيف ذلك ترويسة traceparent إضافية إلى جميع الطلبات التي تطابق أيًا من الأنماط. يجب ضبط هذا على نطاق واجهة برمجة تطبيقات للواجهة الخلفية لديك (مثلًا api.yoursite.com).
• consoleCapture - (اختياري) التقاط جميع سجلات وحدة التحكّم (القيمة الافتراضية false).
• advancedNetworkCapture - (اختياري) التقاط رؤوس الطلبات/الاستجابات كاملةً والأجسام (القيمة الافتراضية false).
• url - (اختياري) عنوان URL لـ OpenTelemetry Collector، وهو مطلوب فقط للمثيلات المستضافة ذاتيًا.
• maskAllInputs - (اختياري) ما إذا كان يجب إخفاء جميع حقول الإدخال في إعادة تشغيل الجلسة (القيمة الافتراضية false).
• maskAllText - (اختياري) ما إذا كان يجب إخفاء كل النصوص في إعادة تشغيل الجلسة (القيمة الافتراضية false).
• disableIntercom - (اختياري) ما إذا كان يجب تعطيل تكامل Intercom (القيمة الافتراضية false)
• disableReplay - (اختياري) ما إذا كان يجب تعطيل إعادة تشغيل الجلسة (القيمة الافتراضية false)

سيتيح لك إرفاق معلومات المستخدم البحث في الجلسات والأحداث وتصفيتها في واجهة مستخدم HyperDX. يمكن استدعاء ذلك في أي وقت أثناء جلسة العميل. وسترتبط جلسة العميل الحالية وجميع الأحداث المُرسلة بعد هذا الاستدعاء بمعلومات المستخدم.

ستملأ userEmail وuserName وteamName واجهة الجلسات بالقيم المقابلة، ولكن يمكن حذفها. ويمكن أيضًا تحديد أي قيم إضافية واستخدامها للبحث عن الأحداث.

HyperDX.setGlobalAttributes({
  userId: user.id,
  userEmail: user.email,
  userName: user.name,
  teamName: user.team.name,
  // Other custom properties...
});

إذا كنت تستخدم React، فيمكنك تلقائيًا التقاط الأخطاء التي تحدث داخل حدود الأخطاء في React من خلال تمرير مكوّن حدّ الأخطاء الخاص بك إلى الدالة attachToReactErrorBoundary.

// Import your ErrorBoundary (we're using react-error-boundary as an example)
import { ErrorBoundary } from 'react-error-boundary';

// This will hook into the ErrorBoundary component and capture any errors that occur
// within any instance of it.
HyperDX.attachToReactErrorBoundary(ErrorBoundary);

لتتبّع حدث معيّن في التطبيق بشكل صريح (مثل التسجيل أو الإرسال وغير ذلك)، يمكنك استدعاء الدالة addAction مع اسم الحدث وبيانات وصفية اختيارية له.

مثال:

HyperDX.addAction('Form-Completed', {
  formId: 'signup-form',
  formName: 'Signup Form',
  formType: 'signup',
});

لتفعيل أو تعطيل التقاط حركة الشبكة ديناميكيًا، ما عليك سوى استدعاء الدالة enableAdvancedNetworkCapture أو disableAdvancedNetworkCapture حسب الحاجة.

HyperDX.enableAdvancedNetworkCapture();

إذا كان تطبيق الواجهة الأمامية لديك يُجري طلبات إلى واجهة برمجة تطبيقات على نطاق مختلف، فيمكنك اختياريًا تفعيل إرسال ترويسة Timing-Allow-Originheader مع الطلب. يتيح ذلك لـ ClickStack التقاط معلومات دقيقة عن توقيت الموارد للطلب، مثل استعلام DNS وتنزيل الاستجابة وغير ذلك، عبر PerformanceResourceTiming.

إذا كنت تستخدم express مع حزم cors، فيمكنك استخدام المقتطف التالي لتفعيل الترويسة:

var cors = require('cors');
var onHeaders = require('on-headers');

// ... all your stuff

app.use(function (req, res, next) {
  onHeaders(res, function () {
    var allowOrigin = res.getHeader('Access-Control-Allow-Origin');
    if (allowOrigin) {
      res.setHeader('Timing-Allow-Origin', allowOrigin);
    }
  });
  next();
});
app.use(cors());