Session Replay Demo

يُعد التطبيق التجريبي لإعادة تشغيل الجلسات مستكشفًا للوثائق مبنيًا باستخدام JavaScript الخام. ويوضح مدى بساطة إضافة instrumentation لإعادة تشغيل الجلسات — إذ يكفي وسم script واحد واستدعاء تهيئة واحد لالتقاط جميع تفاعلات المستخدم تلقائيًا.

يتضمن المستودع فرعين:

• main — مُعدّ بالكامل ومزوّد بالـ instrumentation وجاهز للاستخدام فورًا
• pre-instrumented — نسخة نظيفة من دون instrumentation، مع تعليقات في الشيفرة توضّح مواضع إضافتها

يستخدم هذا الدليل فرع main أولًا لمشاهدة إعادة تشغيل الجلسات أثناء العمل، ثم يستعرض شيفرة الـ instrumentation حتى تتمكن من تطبيق النمط نفسه على تطبيقك.

للاطلاع على مزيد من الخلفية حول إعادة تشغيل الجلسات وكيف تندرج ضمن ClickStack، راجع صفحة ميزة Session Replay.

• تثبيت Docker وDocker Compose
• توفّر المنافذ 3000 و4317 و4318 و8080

استنسخ المستودع

git clone https://github.com/ClickHouse/clickstack-session-replay-demo
cd clickstack-session-replay-demo

ابدأ ClickStack

docker-compose up -d clickstack

احصل على مفتاح API الخاص بك

1. افتح HyperDX على http://localhost:8080
2. أنشئ حسابًا أو سجّل الدخول إذا لزم الأمر
3. انتقل إلى Team Settings → API Keys
4. انسخ مفتاح API للاستيعاب الخاص بك

5. عيّنه كمتغير بيئة:

export CLICKSTACK_API_KEY='your-api-key-here'

ابدأ التطبيق التجريبي

docker-compose --profile demo up demo-app

افتح http://localhost:3000 في متصفحك وتفاعل مع التطبيق — ابحث عن الموضوعات، وصفِّ حسب الفئة، واستعرض أمثلة الشيفرة، وأضف العناصر إلى الإشارات المرجعية.

تُلتقط جميع التفاعلات تلقائيًا بواسطة ClickStack Browser SDK.

شاهد إعادة تشغيل جلستك

ارجع إلى HyperDX على http://localhost:8080 وانتقل إلى Client Sessions من الشريط الجانبي الأيسر.

يُفترض أن تظهر جلستك في القائمة مع مدتها وعدد الأحداث فيها. انقر على الزر ▶️ لإعادة تشغيلها.

بدّل بين وضعي Highlighted وAll Events لضبط مستوى التفاصيل في المخطط الزمني.

يوضح التطبيق التجريبي مدى قلة الشيفرة المطلوبة لتفعيل إعادة تشغيل الجلسة. وكل ما يلزم هو إضافتان إلى التطبيق:

1. تضمين SDK (app/public/index.html):

<script src="https://unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>

2. هيّئ ClickStack (app/public/js/app.js):

window.HyperDX.init({
  url: 'http://localhost:4318',
  apiKey: window.CLICKSTACK_API_KEY,
  service: 'clickhouse-session-replay-demo',
  consoleCapture: true,
  advancedNetworkCapture: true,
});

وكل ما عدا ذلك هو مجرد كود تطبيق عادي. يلتقط SDK تلقائيًا جميع تفاعلات المستخدم، وسجلات وحدة التحكم، وطلبات الشبكة، والأخطاء — لذلك لا حاجة إلى أي إعداد إضافي للرصد.

لإضافة إمكانات الرصد إلى التطبيق من الصفر، بدّل إلى الفرع pre-instrumented:

git checkout pre-instrumented

يحتوي هذا الفرع على التطبيق نفسه ولكن من دون أي تهيئة لجمع بيانات الرصد الخاصة بـ ClickStack. تشير تعليقات الشيفرة في app/public/index.html وapp/public/js/app.js بدقة إلى الموضع الذي ينبغي فيه إضافة مقتطعي الشيفرة المذكورين أعلاه. بعد إضافتهما، أعد تشغيل التطبيق التجريبي وستبدأ تفاعلاتك بالظهور في ClickStack.

1. تحقّق من وحدة تحكم المتصفح بحثًا عن أخطاء
2. تأكّد من أن ClickStack قيد التشغيل: docker-compose ps
3. تأكّد من ضبط مفتاح API: echo $CLICKSTACK_API_KEY
4. اضبط النطاق الزمني في عرض Client Sessions (جرّب آخر 15 دقيقة)
5. أجرِ إعادة تحميل كاملة للمتصفح: Cmd+Shift+R (Mac) أو Ctrl+Shift+R (Windows/Linux)

لم يتم ضبط مفتاح API بشكل صحيح. تأكد من أنك:

1. صدّرته في الطرفية: export CLICKSTACK_API_KEY='your-key'
2. بدأت التطبيق التجريبي في نفس الطرفية التي صدّرته فيها
3. حصلت على المفتاح من HyperDX UI (وليس سلسلة أُنشئت عشوائيًا)

أوقِف الخدمات:

docker-compose down

احذف جميع البيانات:

docker-compose down -v

• Session Replay — نظرة عامة على الميزة، وخيارات SDK، وعناصر التحكّم في الخصوصية
• مرجع Browser SDK — خيارات SDK الكاملة والتهيئة المتقدمة
• بدء استخدام ClickStack — انشر ClickStack وأدخِل أولى بياناتك
• جميع مجموعات البيانات التجريبية — مجموعات بيانات تجريبية وأدلّة أخرى