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

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

# JavaScript للمتصفح

export const ClickStackIntegrates = ({signals = []}) => {
  const list = Array.isArray(signals) ? signals : String(signals).split(",");
  const supported = list.map(s => String(s).trim().toLowerCase());
  const pillStyle = {
    display: "inline-flex",
    alignItems: "center",
    padding: "0.125rem 0.625rem",
    borderRadius: "9999px",
    fontSize: "0.8125rem",
    fontWeight: 500,
    lineHeight: 1.6,
    color: "#161517",
    backgroundColor: "#faff69",
    border: "1px solid rgba(0, 0, 0, .1)",
    marginRight: "0.5rem"
  };
  return <div style={{
    margin: "0 0 1.25rem"
  }}>
      <span style={{
    marginRight: "0.5rem"
  }}>يتكامل هذا الدليل مع:</span>
      {supported.includes("logs") && <span style={pillStyle}>السجلات</span>}
      {supported.includes("metrics") && <span style={pillStyle}>المقاييس</span>}
      {supported.includes("traces") && <span style={pillStyle}>التتبعات</span>}
    </div>;
};

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

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

<ClickStackIntegrates signals={['logs', 'traces']} />

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

<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: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
        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: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
        apiKey: '<YOUR_INGESTION_API_KEY>', // احذفها عند استخدام Managed ClickStack
        service: 'my-frontend-app',
        tracePropagationTargets: [/api.myapp.domain/i], // حدّده لربط التتبعات من الواجهة الأمامية بطلبات الواجهة الخلفية
      });
    </script>
    ```
  </Tab>
</Tabs>

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

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

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

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

سيتيح لك إرفاق معلومات المستخدم البحث في الجلسات والأحداث وتصفيتها
في واجهة مستخدم 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...
});
```

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

إذا كنت تستخدم 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);
```

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

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

مثال:

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

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

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

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

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

إذا كان تطبيق الواجهة الأمامية لديك يُجري طلبات إلى واجهة برمجة تطبيقات على نطاق مختلف، فيمكنك
اختياريًا تفعيل إرسال ترويسة `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());
```