سيؤدي تنفيذ السطر التالي إلى تثبيت المُتتبع وبالتالي الـ 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 تمكين هذا الخيار لإعادة تعيين معرف الجلسة عند فتح علامة تبويب جديدة من تطبيقك. يؤدي هذا إلى استبدال طريقة window.open لتجنب تكرار معرّفات الجلسة بسبب تخزين الجلسات المشترك بين علامات التبويب في المتصفح. الافتراضي: false.
• forceSingleTab: boolean يعطل قدرة التسجيل في علامات تبويب متعددة التي تدمج جلسات المستخدم، التي تتم عبر علامات تبويب متعددة، في إعادة تشغيل واحدة. بدلاً من ذلك، عند تمكين هذا الخيار، سيتم تسجيل الجلسات الملتقطة في علامات تبويب مختلفة من المتصفح في تسجيلات منفصلة. الافتراضي: false.
• disableStringDict: boolean يعطل منطق قاموس السلاسل (لتحسين التخزين) في التسجيلات. الافتراضي: false.
• fixedCanvasScaling: boolean يفرض تقديم صور canvas بكثافة بكسل تساوي 1 بدلاً من devicePixelRatio. (يقلل من الجودة المحتملة للصورة لجعل النتيجة النهائية أصغر حجماً). الافتراضي: false.
• disableCanvas?: boolean يعطل تسجيل عناصر canvas. الافتراضي: false.
• assistSocketHost?: string يمكن استخدامه لتعيين مضيف محدد لاتصال إضافة assist. القيمة الافتراضية هي قيمة ingestPoint.

• respectDoNotTrack?: boolean لا يبدأ المُتتبع إذا كان علم عدم التتبع مفعلاً في متصفح المستخدم. الافتراضي: false.
• obscureTextEmails?: boolean يخفي البريد الإلكتروني في عناصر النص. سيتم تحويل البريد الإلكتروني إلى سلسلة عشوائية من النجوم. الافتراضي: true.
• obscureTextNumbers?: boolean يخفي الأرقام في عناصر النص. ستتحول الأرقام إلى سلسلة عشوائية من النجوم. الافتراضي: false.
• obscureInputEmails?: boolean يخفي البريد الإلكتروني في حقول الإدخال. ستتحول قيم البريد الإلكتروني إلى سلسلة عشوائية من النجوم. الافتراضي: true.
• 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 رد نداء يُستخدم لتنفيذ إجراء بمجرد تحميل 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.