سيقوم السطر التالي بتثبيت المتتبع ومعه الـ SDK لتتمكن من الاستفادة من جميع ميزات المتتبع.

npm i @openreplay/tracker

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

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

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

import { tracker } from '@openreplay/tracker'

tracker.configure({
	projectKey: PROJECT_KEY,
  ingestPoint: "https://openreplay.mydomain.com/ingest", // when dealing with the self-hosted version of OpenReplay
})

tracker.start() // returns a promise with session info (sessionID, sessionHash, userUUID)

بدلاً من ذلك، يمكنك إنشاء مثيل جديد للفئة (class):

import OpenReplay from '@openreplay/tracker';
//...
const tracker = new OpenReplay({
  projectKey: PROJECT_KEY
});
tracker.start(); // returns a promise with session info (sessionID, sessionHash, userUUID)

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

import OpenReplay from '@openreplay/tracker/cjs';
//...
const tracker = new OpenReplay({
      projectKey: PROJECT_KEY,
      ingestPoint: "https://openreplay.mydomain.com/ingest", // when dealing with the self-hosted version of OpenReplay
});
//...
function MyApp() {
  useEffect(() => { // use componentDidMount in case of React Class Component
    tracker.start(); // returns a promise with session info (sessionID, sessionHash, userUUID)
  }, [])
}

import OpenReplay from '@openreplay/tracker/cjs';
//...
const tracker = new OpenReplay({
      projectKey: PROJECT_KEY,
      ingestPoint: "https://openreplay.mydomain.com/ingest", // when dealing with the self-hosted version of OpenReplay
      capturePerformance: true,
      __DISABLE_SECURE_MODE: true // for local testing
});

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

• projectKey: string معرف المشروع الذي تقوم بتتبعه.
• sessionHash?: string تجزئة (hash) الجلسة الأولية. هذا مفيد عندما تنتقل الجلسات عبر نطاقات فرعية مختلفة في تطبيق الويب الخاص بك ولكنك تريد دمجها في تسجيل واحد. في حالة عدم إمكانية متابعة الجلسة (غير موجودة أو منتهية)، سيبدأ المتتبع تلقائيًا جلسة جديدة. كما يتم إرجاعه عند stop(). مزيد من التفاصيل حول هذا هنا.
• ingestPoint?: string نطاق OpenReplay الخاص بك (مثل https://openreplay.mydomain.com/ingest)، والذي سيرسل المتتبع الأحداث إليه. هذا اختياري لمستخدمي OpenReplay Cloud. الافتراضي: https://api.openreplay.com/ingest (الذي يشير إلى OpenReplay Cloud).
• revID?: string معرف المراجعة لتطبيق الويب الخاص بك. مفيد عند البحث عن مشكلات تحدث في إصدار محدد.
• resourceBaseHref?: string يشير إلى النطاق المتاح للعموم حيث يمكن لـ OpenReplay جلب الأصول (الأنماط، الخطوط، والرموز). نظرًا لأنها مطلوبة لإعادة تشغيل الجلسة بشكل صحيح، فإن هذا الخيار مفيد لتجاوز قيد استضافة موقعك (وبالتالي الأصول) في نطاق خاص. مثال: https://mypublicsite.com/assets/.
• captureIFrames?: boolean لالتقاط جميع إطارات iFrame من نفس النطاق في تطبيق الويب الخاص بك. إذا كنت ترغب في تتبع إطار iFrame محدد، فما عليك سوى إضافة سمة HTML data-openreplay-capture إلى وسم <iframe>. الافتراضي: true.
• disableClickmaps?: boolean لتعطيل حساب محددات CSS (المستخدمة في خرائط النقر). الافتراضي: false.
• __debug__: number لتمكين سجلات التصحيح. الافتراضي: 0 (معطل).
  • 2: الأخطاء.
  • 3: الأخطاء والتحذيرات.
  • 4: الأخطاء والتحذيرات والسجلات.
  • 5: مفصّل.
• autoResetOnWindowOpen?: boolean قم بتمكين هذا الخيار لإعادة تعيين sessionID عند فتح علامة تبويب جديدة من تطبيقك. هذا يستبدل طريقة window.open لتجنب sessionIDs المكررة بسبب تخزين الجلسة المشترك بين علامات تبويب المتصفح. الافتراضي: false.
• forceSingleTab: boolean يعطّل إمكانية التسجيل في علامات تبويب متعددة والتي تدمج جلسات المستخدم، التي تتم عبر علامات تبويب متعددة، في إعادة تشغيل واحدة. بدلاً من ذلك، عند تمكين هذا الخيار، سيتم تسجيل الجلسات التي تم التقاطها في علامات تبويب المتصفح المختلفة في تسجيلات منفصلة. الافتراضي: false.
• disableStringDict: boolean يعطّل منطق قاموس السلاسل (لتحسين التخزين) في التسجيلات. الافتراضي: false.
• fixedCanvasScaling: boolean يجبر صور canvas على أن تُرسم بكثافة بكسل 1 بدلاً من devicePixelRatio. (يقلل من الجودة المحتملة للصورة لجعل النتيجة النهائية أصغر في الحجم). الافتراضي: false.
• disableCanvas?: boolean يعطّل تسجيل عناصر canvas. الافتراضي: false.
• assistSocketHost?: string يمكن استخدامه لتعيين مضيف محدد لاتصال إضافة assist. الافتراضي هو قيمة ingestPoint.
• nodes?: { maintainer: MaintainerOptions } يساعد خيار nodes.maintainer الجديد في إدارة الذاكرة وتنظيف عقد DOM التي لم تعد قيد الاستخدام. لديه المعلمات التالية:
  • interval: number: الفاصل الزمني (بالملي ثانية) بين عمليات التنظيف. الافتراضي: 30 * 1000 (30 ثانية).
  • batchSize: number: عدد العقد التي يتم التحقق منها خلال كل عملية تنظيف. الافتراضي: 2500.
  • enabled: boolean: تمكين أو تعطيل مدير العقد. الافتراضي: true.

• inlineCss: number: يجبر المتتبع على تسجيل أوراق الأنماط البعيدة وإرسالها كرسائل عادية بدلاً من تخزينها مؤقتًا في الخلفية. هذا مفيد عندما تكون ملفات CSS خاصة، وبالتالي لا يمكن تخزينها مؤقتًا بواسطة خلفية OpenReplay. يمكن أن تكون القيم:
  • 0: يتم تخزين ملف CSS مؤقتًا بواسطة الخلفية. السلوك الافتراضي.
  • 1: سيحاول تسجيل ملف css المرتبط ككائن AdoptedStyleSheet.
  • 2: جلب الملف، ثم محاكاة سلوك AdoptedStyleSheets لإعادة التشغيل.
  • 3: جلب الملف، ثم حفظه كـ css عادي داخل عقدة <style> — استخدم هذا الخيار إذا كان لديك الكثير من الخصائص المختصرة في ملفات CSS الخاصة بك (يغطي خللاً في مواصفة CSSOM).
• css: CssRulesOptions: يوفر دعمًا أفضل للتطبيقات المبنية بمكتبة emotion-js (مثل مكونات MUI). يأتي بالمعلمات التالية:
  • scanInMemoryCSS: boolean: قم بتشغيل هذا إذا واجهت مشكلات مع الأنماط التي تم إنشاؤها بواسطة emotionjs. الافتراضي: false.
  • checkCssInterval: number: عدد مرات مسح أوراق الأنماط المتتبَّعة التي تحتوي على قواعد فارغة. الافتراضي: 200 (مللي ثانية).
  • checkLimit: number: مفيد للحالات التي يكون فيها عدد التغييرات محدودًا و/أو عندما تتم ترطيب (hydrated) أوراق الأنماط على العميل بعد العرض الأولي. يُطبَّق على كل ورقة أنماط على حدة. يجب أن تكون القيمة = X/checkCssInterval حيث X هي مدة المراقبة بالملي ثانية. الافتراضي: 0 (معطل).

• respectDoNotTrack?: boolean لا تبدأ المتتبع إذا تم تمكين علامة do-not-track في متصفح المستخدم. الافتراضي: false.
• obscureTextEmails?: boolean يخفي عناوين البريد الإلكتروني في عناصر النص. سيتم تحويل عناوين البريد الإلكتروني إلى سلسلة عشوائية من النجوم. الافتراضي: true.
• obscureTextNumbers?: boolean يخفي الأرقام في عناصر النص. سيتم تحويل الأرقام إلى سلسلة عشوائية من النجوم. الافتراضي: false.
• obscureInputEmails?: boolean يخفي عناوين البريد الإلكتروني في حقول الإدخال. سيتم تحويل قيم البريد الإلكتروني إلى سلسلة عشوائية من النجوم. الافتراضي: true.
• obscureInputNumbers?: boolean يخفي الأرقام في حقول الإدخال. سيتم تحويل القيم الرقمية إلى سلسلة عشوائية من النجوم. في حال تعطيله، تأكد من تنظيف حقول الإدخال التي قد تحتوي على بيانات حساسة مثل الرموز البريدية أو تفاصيل بطاقات الائتمان. الافتراضي: true.
• obscureInputDates?: boolean يخفي التواريخ في حقول الإدخال. سيتم تحويل قيم التواريخ إلى سلسلة عشوائية من النجوم. الافتراضي: false.
• defaultInputMode?: 0 | 1 | 2 وضع الالتقاط الافتراضي لقيم الإدخال. على التوالي: عادي، مخفي، أو متجاهَل. الافتراضي: 2 (متجاهَل).
• urls: يتيح لك تخصيص كيفية تسجيل أحداث موقع الصفحة عبر الخيارات التالية:
  • urlSanitizer?: (url: string) => string يتيح لك تنظيف عنوان url للصفحة (لإزالة رموز الاستخدام على سبيل المثال).
  • titleSanitizer?: (title: string) => string يتيح لك تنظيف عنوان الصفحة.
• resourceNameSanitizer?: (url: string) => string يتيح لك تنظيف عناوين URL لموارد الشبكة المسجلة.

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

• 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 يحسب مقاييس عرض الصفحة مثل Speed Index أو Visually Complete أو Time To Interactive. يتطلب captureResourceTimings = true. الافتراضي: true.

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

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

network?: {
    failuresOnly: boolean;
    sessionTokenHeader: string;
    ignoreHeaders: Array<string> | boolean;
    capturePayload: boolean; // make sure you sanitize your data before enabling it
    sanitizer: (RequestResponseData) => RequestResponseData | null;
		captureInIframes: boolean;
  	axiosInstances: AxiosInstance[];
    useProxy?: boolean;
		tokenUrlMatcher?: (url: string) => boolean;
  }

راجع Network Options للحصول على أمثلة ومزيد من التفاصيل حول كيفية تنقيح البيانات الحساسة.

يتعلق خيار canvas بالتقاط عناصر canvas/WebGL:

canvas?: {
  disableCanvas?: boolean
  fixedCanvasScaling?: boolean
  useAnimationFrame?: boolean
  fileExt?: 'webp' | 'png' | 'jpeg' | 'avif'
}

راجع Canvas and WebGL لمعرفة كيفية تمكين هذه القدرة ومزيد من التفاصيل حول الخيارات المتاحة.

يتعلق خيار crossdomain بالتقاط إطارات iFrame من نطاقات مختلفة. يُستخدم جنبًا إلى جنب مع خيار captureIFrames الذي يجب تعيينه على true.

	crossdomain?: {
		/**
		 * Enable cross-domain tracking
		 * @default false
		 * */
		enabled?: boolean
		/**
		 * Used to specify the parent domain, will be '*' by default
		 * (Check your CSP settings)
		 * @default '*'
		 * */
		parentDomain?: string
	}

اعتبارًا من إصدار المتتبع 14.0.10، لم تعد سمة data-domain مطلوبة على عناصر HTML عند العمل مع إطارات iFrame عبر النطاقات.

راجع Cross-domain iFrame Tracking للحصول على مزيد من التفاصيل حول كيفية التقاط iFrame من نطاق مختلف.

يتعلق خيار 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.

• onFlagsLoad رد اتصال يُستخدم لأداء إجراء بمجرد تحميل أعلام الميزات (في كل مرة).

 flags?: {
 	onFlagsLoad?: (flags: IFeatureFlag[]) => void
 } 

// ...
interface IFeatureFlag {
  key: string
  is_persist: boolean
  value: string | boolean
  payload: string
}

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