الانتقال إلى المحتوى الرئيسي
باختصاريشرح هذا الدليل كيفية تزويد تطبيق ويب بإمكانات إعادة تشغيل الجلسات باستخدام ClickStack Browser SDK. وعلى عكس مجموعات البيانات النموذجية الأخرى التي تحمّل بيانات مُولَّدة مسبقًا، يوفّر هذا العرض التوضيحي تطبيقًا تفاعليًا تنشئ فيه بيانات الجلسة من خلال تفاعلاتك الخاصة.الوقت المطلوب: 10-15 دقيقة

​
نظرة عامة

يُعد التطبيق التجريبي لإعادة تشغيل الجلسات مستكشفًا للوثائق مبنيًا باستخدام JavaScript الخام. ويوضح مدى بساطة إضافة instrumentation لإعادة تشغيل الجلسات — إذ يكفي وسم script واحد واستدعاء تهيئة واحد لالتقاط جميع تفاعلات المستخدم تلقائيًا. يتضمن المستودع فرعين:
  • main — مُعدّ بالكامل ومزوّد بالـ instrumentation وجاهز للاستخدام فورًا
  • pre-instrumented — نسخة نظيفة من دون instrumentation، مع تعليقات في الشيفرة توضّح مواضع إضافتها
يستخدم هذا الدليل فرع main أولًا لمشاهدة إعادة تشغيل الجلسات أثناء العمل، ثم يستعرض شيفرة الـ instrumentation حتى تتمكن من تطبيق النمط نفسه على تطبيقك. للاطلاع على مزيد من الخلفية حول إعادة تشغيل الجلسات وكيف تندرج ضمن ClickStack، راجع صفحة ميزة Session Replay.

​
المتطلبات الأساسية

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

​
تشغيل العرض التوضيحي

1

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

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

​
ابدأ ClickStack

docker-compose up -d clickstack
3

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

  1. افتح HyperDX على http://localhost:8080
  2. أنشئ حسابًا أو سجّل الدخول إذا لزم الأمر
  3. انتقل إلى Team Settings → API Keys
  4. انسخ مفتاح API للاستيعاب الخاص بك
  1. عيّنه كمتغير بيئة:
export CLICKSTACK_API_KEY='your-api-key-here'
4

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

docker-compose --profile demo up demo-app
تأكد من تشغيل هذا الأمر في الطرفية نفسها التي صدّرت فيها المتغير CLICKSTACK_API_KEY.
افتح http://localhost:3000 في متصفحك وتفاعل مع التطبيق — ابحث عن الموضوعات، وصفِّ حسب الفئة، واستعرض أمثلة الشيفرة، وأضف العناصر إلى الإشارات المرجعية.تُلتقط جميع التفاعلات تلقائيًا بواسطة ClickStack Browser SDK.
5

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

ارجع إلى 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.

​
استكشاف الأخطاء وإصلاحها

​
عدم ظهور الجلسات في HyperDX

  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)

​
أخطاء 401 Unauthorized

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

​
التنظيف

أوقِف الخدمات: 
docker-compose down
احذف جميع البيانات: 
docker-compose down -v

​
تعرّف على المزيد

آخر تعديل في ٢٥ يونيو ٢٠٢٦