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

npm i @openreplay/tracker

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

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

إذا كان موقعك الإلكتروني هو Single Page Application (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)

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

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

خلاف ذلك، إذا كان تطبيق الويب الخاص بك Server-Side-Rendered (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 تجزئة الجلسة الأولية. هذا مفيد عندما تنتقل الجلسات عبر نطاقات فرعية مختلفة في تطبيق الويب الخاص بك ولكنك تريد دمجها في تسجيل واحد. في حالة عدم إمكانية متابعة الجلسة (غير موجودة أو منتهية)، سيبدأ المتتبع تلقائيًا جلسة جديدة. يتم إرجاعه أيضًا عند 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: مفيد للحالات ذات العدد المحدود من التغييرات و/أو عندما يتم ترطيب أوراق الأنماط على العميل بعد العرض الأولي. يُطبق على كل ورقة أنماط بشكل فردي. يجب أن تكون القيمة = 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.

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