> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Browser SDK لـ ClickStack - حزمة Observability من ClickHouse

# JavaScript للمتصفح

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

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

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

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

<div id="getting-started">
  ## البدء
</div>

<br />

<Tabs>
  <Tab title="استيراد الحزمة">
    **ثبّت عبر استيراد الحزمة (موصى به)**

    استخدم الأمر التالي لتثبيت [حزمة المتصفح](https://www.npmjs.com/package/@hyperdx/browser).

    ```shell theme={null}
    npm install @hyperdx/browser
    ```

    **أعِدّ ClickStack**

    ```javascript theme={null}
    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)
    });
    ```
  </Tab>

  <Tab title="وسم Script">
    **ثبّت عبر وسم Script (بديل)**

    يمكنك أيضًا تضمين البرنامج النصي وتثبيته عبر وسم script بدلًا من
    التثبيت عبر NPM. سيؤدي ذلك إلى إتاحة المتغير العام `HyperDX`، ويمكن
    استخدامه بالطريقة نفسها المستخدمة مع حزمة NPM.

    يُنصح بهذا إذا كان موقعك لا يُبنى حاليًا باستخدام أداة تجميع.

    ```html theme={null}
    <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>
    ```
  </Tab>
</Tabs>

<div id="options">
  ### الخيارات
</div>

* `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`)

<div id="additional-configuration">
  ## تهيئة إضافية
</div>

<div id="attach-user-information-or-metadata">
  ### إرفاق معلومات المستخدم أو البيانات الوصفية
</div>

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

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

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

<div id="auto-capture-react-error-boundary-errors">
  ### الالتقاط التلقائي لأخطاء حدود الأخطاء في React
</div>

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

```javascript theme={null}
// 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);
```

<div id="send-custom-actions">
  ### إرسال الإجراءات المخصّصة
</div>

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

مثال:

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

<div id="enable-network-capture-dynamically">
  ### تفعيل التقاط حركة الشبكة ديناميكيًا
</div>

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

```javascript theme={null}
HyperDX.enableAdvancedNetworkCapture();
```

<div id="enable-resource-timing-for-cors-requests">
  ### تفعيل توقيت الموارد لطلبات CORS
</div>

إذا كان تطبيق الواجهة الأمامية لديك يُجري طلبات إلى واجهة برمجة تطبيقات على نطاق مختلف، فيمكنك
اختياريًا تفعيل إرسال ترويسة `Timing-Allow-Origin`[header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Timing-Allow-Origin) مع الطلب. يتيح ذلك لـ ClickStack التقاط
معلومات دقيقة عن توقيت الموارد للطلب، مثل استعلام DNS وتنزيل
الاستجابة وغير ذلك، عبر [`PerformanceResourceTiming`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming).

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

```javascript theme={null}
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());
```