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

npm i @openreplay/tracker

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

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

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

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,
});
//...
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 هاش الجلسة الأولية. هذا مفيد عندما تعبر الجلسات عبر نطاقات فرعية مختلفة في تطبيق الويب الخاص بك، لكنك ترغب في دمجها في تسجيل واحد. في حالة عدم إمكانية الاستمرار في الجلسة (غير موجودة أو منتهية)، سيبدأ المُتتبع تلقائياً جلسة جديدة. كما يتم إرجاعها عند استدعاء 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 لالتقاط جميع الإطارات (iFrames) ذات النطاق نفسه في تطبيق الويب الخاص بك. إذا كنت ترغب في تتبع إطار محدد، فما عليك سوى إضافة السمة HTML data-openreplay-capture إلى علامة <iframe>. الافتراضي: true.
• disableClickmaps?: boolean لتعطيل حساب محددات CSS (المستخدمة في خرائط النقر). الافتراضي: false.
• verbose?: boolean لتمكين السجلات. الافتراضي: false.
• autoResetOnWindowOpen?: boolean فعّل هذا الخيار لإعادة تعيين sessionID عند فتح علامة تبويب جديدة من تطبيقك. هذا يعيد كتابة طريقة window.open لتجنب تكرار sessionID بسبب تخزين الجلسات المشترك بين علامات تبويب المتصفح. الافتراضي: false.
• forceSingleTab: boolean يعطل إمكانية التسجيل عبر علامات تبويب متعددة، والتي تدمج جلسات المستخدم التي تُجرى عبر علامات تبويب متعددة في تسجيل واحد. وبدلاً من ذلك، عند تمكين هذا الخيار، سيتم تسجيل الجلسات الملتقطة في علامات تبويب مختلفة في المتصفح في تسجيلات منفصلة. الافتراضي: false.
• disableStringDict: boolean يعطل منطق قاموس السلاسل (لتحسين التخزين) في التسجيلات. الافتراضي: false.
• fixedCanvasScaling: boolean يفرض تقديم صور canvas بكثافة بكسل تساوي 1 بدلاً من devicePixelRatio. (يقلل من الجودة المحتملة للصورة لجعل النتيجة النهائية أصغر حجماً). الافتراضي: false.
• disableCanvas?: boolean يعطل تسجيل عناصر canvas. الافتراضي: false.
• assistSocketHost?: string يمكن استخدامه لتعيين مضيف محدد لاتصال إضافة assist. يأخذ افتراضياً قيمة ingestPoint.

• respectDoNotTrack?: boolean لا يبدأ المُتتبع إذا كان علم do-not-track مفعلاً في متصفح المستخدم. الافتراضي: false.
• obscureTextEmails?: boolean يخفي البريد الإلكتروني في عناصر النص. سيتم تحويل البريد الإلكتروني إلى سلسلة عشوائية من علامات النجمة. الافتراضي: true.
• obscureTextNumbers?: boolean يخفي الأرقام في عناصر النص. سيتم تحويل الأرقام إلى سلسلة عشوائية من علامات النجمة. الافتراضي: false.
• obscureInputEmails?: boolean يخفي البريد الإلكتروني في حقول الإدخال. سيتم تحويل قيم البريد الإلكتروني إلى سلسلة عشوائية من علامات النجمة. الافتراضي: true.
• 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 يحسب مقاييس تقديم الصفحة مثل Speed Index أو Visually Complete أو Time To Interactive. يتطلب captureResourceTimings = true. الافتراضي: true.

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

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

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

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

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

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

يتعلق خيار crossdomain بالتقاط الإطارات (iFrames) من نطاقات مختلفة. ويُستخدم بالاقتران مع خيار 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
	}

راجع تتبع الإطارات (iFrame) عبر النطاقات لمزيد من التفاصيل حول كيفية التقاط إطار (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 رد نداء (callback) يُستخدم لتنفيذ إجراء بمجرد تحميل feature flags (في كل مرة).

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

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

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