JavaScript SDK ⁠-⁠ تهيئة الـ SDK

سيؤدي تنفيذ السطر التالي إلى تثبيت المُتتبع وبالتالي الـ SDK لتتمكن من الاستفادة من جميع ميزات المُتتبع.

npm i @openreplay/tracker

عند إنشاء نسخة من مُتتبع OpenReplay، هناك العديد من خيارات التهيئة التي يمكنك توفيرها لتخصيص العديد من جوانب التسجيل وتجربة التسجيل.

يجب عليك تحديد خيار projectKey في المُنشئ. يمكنك الحصول على هذه القيمة من لوحة تحكم OpenReplay تحت ‘التفضيلات > المشاريع’.

إذا كان موقعك الإلكتروني عبارة عن تطبيق ذو صفحة واحدة (SPA)، استخدم الكود التالي:

import OpenReplay from '@openreplay/tracker';
//...
const tracker = new OpenReplay({
projectKey: PROJECT_KEY
});
tracker.start(); // يعود بوعد بمعلومات الجلسة (sessionID, sessionHash, userUUID)

وإلا، إذا كان تطبيقك الويبي مُقدماً من الخادم (SSR) (مثل NextJS، NuxtJS)، استخدم الشظية البرمجية أدناه. تأكد من استدعاء tracker.start() بمجرد بدء التطبيق (في useEffect أو componentDidMount).

import OpenReplay from '@openreplay/tracker/cjs';
//...
const tracker = new OpenReplay({
projectKey: PROJECT_KEY,
});
//...
function MyApp() {
useEffect(() => { // استخدم componentDidMount في حالة مكون React الفئوي
tracker.start(); // يعود بوعد بمعلومات الجلسة (sessionID, sessionHash, userUUID)
}, [])
}

import OpenReplay from '@openreplay/tracker/cjs';
//...
const tracker = new OpenReplay({
projectKey: PROJECT_KEY,
ingestPoint: "https://openreplay.mydomain.com/ingest", // عند التعامل مع النسخة المستضافة ذاتياً من OpenReplay
capturePerformance: true,
__DISABLE_SECURE_MODE: true // للاختبار المحلي
});

هناك مجموعة من الخيارات التي يمكنك تمريرها إلى المُنشئ. يُعد projectKey هو الخيار الوحيد المطلوب.

• projectKey: string معرّف المشروع الذي تقوم بتتبعه.
• sessionHash?: string هاش الجلسة الأولية. هذا مفيد عندما تعبر الجلسات عبر نطاقات فرعية مختلفة في تطبيقك الويبي، لكنك ترغب في دمجها في تسجيل واحد. في حالة عدم إمكانية الاستمرار في الجلسة (غير موجودة أو منتهية)، سيبدأ المتتبع تلقائياً جلسة جديدة. يتم أيضاً إرجاعها عند استدعاء stop(). المزيد من التفاصيل هنا.
• ingestPoint?: string نطاق OpenReplay الخاص بك (مثل https://openreplay.mydomain.com/ingest)، الذي سيقوم المتتبع بإرسال الأحداث إليه. هذا اختياري لمستخدمي OpenReplay Cloud. الافتراضي: https://api.openreplay.com/ingest (يشير إلى OpenReplay Cloud).
• revID?: string معرّف الإصدار لتطبيق الويب الخاص بك. مفيد عند البحث عن المشاكل التي تحدث في إصدار معين من الإصدار.
• resourceBaseHref?: string يشير إلى النطاق العام الذي يمكن الوصول إليه حيث يمكن لـ OpenReplay جلب الأصول (الأنماط، الخطوط والأيقونات). نظراً لأنها ضرورية لإعادة تشغيل الجلسة بشكل صحيح، فإن هذا الخيار مفيد للتغلب على القيود المتعلقة باستضافة موقعك (وبالتالي الأصول) في نطاق خاص. مثال: https://mysitepublic.com/assets/.
• captureIFrames?: boolean لالتقاط جميع الإطارات (iFrames) ذات النطاق المشترك في تطبيقك الويبي. إذا كنت ترغب في تتبع إطار محدد، فقط أضف السمة HTML data-openreplay-capture إلى علامة <iframe>. الافتراضي: true.
• disableClickmaps?: boolean لتعطيل خرائط النقر. الافتراضي: true.
• verbose?: boolean لتمكين السجلات. الافتراضي: false.
• autoResetOnWindowOpen?: boolean تمكين هذا الخيار لإعادة تعيين معرف الجلسة عند فتح علامة تبويب جديدة من تطبيقك. هذا يعدل طريقة window.open لتجنب تكرار معرّفات الجلسة بسبب تخزين الجلسات المشترك بين علامات التبويب في المتصفح. الافتراضي: false.
• forceSingleTab: boolean يعطل قدرات التسجيل في عدة علامات تبويب. الافتراضي: false.
• disableStringDict: boolean يعطل منطق قاموس السلاسل (لتحسين التخزين) في التسجيلات. الافتراضي: false.

• respectDoNotTrack?: boolean لا يبدأ المُتتبع إذا كان علم عدم التتبع مفعلاً في متصفح المستخدم. الافتراضي: false.
• obscureTextEmails?: boolean يخفي البريد الإلكتروني في عناصر النص. سيتم تحويل البريد الإلكتروني إلى سلسلة عشوائية من النجوم. الافتراضي: true.
• obscureTextNumbers?: boolean يخفي الأرقام في عناصر النص. ستتحول الأرقام إلى سلسلة عشوائية من النجوم. الافتراضي: false.
• obscureInputNumbers?: boolean يخفي الأرقام في حقول الإدخال. ستتحول قيم الأرقام إلى سلسلة عشوائية من النجوم. الافتراضي: false.
• obscureInputDates?: boolean يخفي التواريخ في حقول الإدخال. ستتحول قيم التواريخ إلى سلسلة عشوائية من النجوم. الافتراضي: false.
• defaultInputMode?: 0 | 1 | 2 الوضع الافتراضي لالتقاط قيم الإدخال. على التوالي: واضح، مُخفى أو مُهمل. الافتراضي: 1 (مُخفى).

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

• consoleMethods?: Array<'log' | 'info' | 'warn' | 'error' 'debug' | 'assert'> | null يحدد قائمة طرق وحدة التحكم لالتقاط. الافتراضي: ['log', 'info', 'warn', 'error', 'debug', 'assert']
• consoleThrottling?: number الحد الأقصى لعدد إدخالات وحدة التحكم الملتقطة في الثانية. الافتراضي: 30.

• captureExceptions?: boolean يلتقط استثناءات JavaScript وتتبعات المكدس. الافتراضي: true.

• captureResourceTimings?: boolean يسجل توقيتات الموارد. الافتراضي: true.
• capturePageLoadTimings?: boolean يسجل توقيتات تحميل الصفحة. الافتراضي: true.
• capturePageRenderTimings?: boolean يحسب مقاييس تقديم الصفحة مثل مؤشر السرعة والاكتمال البصري أو الوقت حتى التفاعل. يتطلب captureResourceTimings = true. الافتراضي: true.

• capturePerformance?: boolean لالتقاط مقاييس الأداء مثل معدل الإطارات واستهلاك وحدة المعالجة المركزية والذاكرة. الافتراضي: true.

تتعلق خيارات network بالتقاط الطلبات والحمولات الشبكية لـ fetch و XHR.

network?: {
failuresOnly: boolean;
sessionTokenHeader: string;
ignoreHeaders: Array<string> | boolean;
capturePayload: boolean; // تأكد من تنقية بياناتك قبل تمكينها
sanitizer: (RequestResponseData) => RequestResponseData | null;
captureInIframes: boolean;
axiosInstances: AxiosInstance[];
useProxy?: boolean;
tokenUrlMatcher?: (url: string) => boolean;
}

راجع خيارات الشبكة للاطلاع على الأمثلة ومزيد من التفاصيل حول كيفية تحرير البيانات الحساسة.

تتعلق خيارات mouse بالتقاط المحددات للنقرات لإنشاء خرائط النقر.

mouse?:
{
disableClickmaps?: boolean
minSelectorDepth?: number
nthThreshold?: number
maxOptimiseTries?: number
}

• disableClickmaps?: boolean يعطل حساب المحدد تماماً. الافتراضي: false.
• minSelectorDepth?: number الحد الأدنى لطول المحدد المُحسّن (افتراضي 2). مثال: body > div > div > p => body > p
• nthThreshold?: number عدد محاولات المحدد قبل اللجوء إلى محددات nth-child. هذه عملية مكلفة وقد تؤدي إلى تكاليف إضافية كبيرة، لا تضعها أعلى من 2000. الافتراضي: 1000.
• maxOptimiseTries?: number عدد المحاولات لتحسين وتقصير المحدد. الافتراضي: 10 000.

• connAttemptCount?: number الحد الأقصى لعدد محاولات إعادة الاتصال عندما تفشل طلبات HTTP للمُتتبع في الوصول إلى الخلفية. الافتراضي: 10.
• connAttemptGap?: number المدة بين كل محاولة إعادة اتصال (مُعبّر عنها بالمللي ثانية). الافتراضي: 8000.

• __DISABLE_SECURE_MODE?: boolean للسماح بالاتصال غير الآمن بين المتتبع والخلفية على المواقع بدون SSL. يجب استخدام هذا لأغراض التطوير فقط. الافتراضي: false.