معزول بـShadow DOM
الزرّ وأداة الالتقاط يُركَّبان داخل Shadow DOM مع تصفير all:initial للمضيف، فلا CSS عندك يقدر
ينسّقهما ولا أنماطهما توصل لصفحتك. أمّا جافاسكربت فقصّة ثانية: شوف وش يلمسه الودجت بصفحتك تحت.
سنيبت الموقع هو سطح الالتقاط الأساسي في uMarker. تلصق وسم <script> واحد في موقعك — وبعد ما يكون
المشروع منشوراً والمضيف مسجّلاً بقائمة نطاقاته — يظهر زرّ الملاحظات لـكل زائر، بلا تسجيل دخول
ولا تثبيت ولا حساب. الزائر ينقر الزرّ، يأشّر على الخلل، يكتب جملة، ويرسل. والتقرير ينزل بالوارد
عندك ومعه اللقطة والدبابيس المرقّمة والملاحظات المكتوبة فيها ورابط الصفحة والجهاز، كلّها مرفقة أصلاً.
ولو كان المشروع على وضع الالتقاط التقني،
تجي معه رسائل الكونسول والطلبات اللي فشلت وباقي السجلّ التقني.
ابدأ من هنا. المشروع ما يخدم إلا النطاقات اللي تسجّلها فيه، والمشروع بلا نطاقات ما يخدم في أي مكان، والسنيبت بيسكت على كل صفحة تلصقه فيها. وهذا مو إعداد أمان تقدر تتركه فاضي: النطاق هو الوحدة اللي تحسبها باقتك، ونفس القائمة هي اللي تستخدمها إضافة المتصفّح عشان تعرف الصفحة تتبع أي مشروع.
افتح مشروعك ← تبويب الودجت ← الإعداد.
ضِف كل نطاق بتجمع منه ملاحظات، واحد بكل صفّ، اسم المضيف فقط:
example.comwww.example.comstaging.example.comاحفظ. وما تقدر تنشر مشروعاً قائمته فاضية.
النشر هو اللي يخلّي الودجت مباشراً: والمشروع اللي بـمسودّة ما يعرض شيئاً بأي مكان. ومبدّل النشر موجود بترويسة المشروع وبقائمة المشاريع، وترجيعه لمسودّة يطفّي الودجت بكل مكان بدون ما تلمس السنيبت الموجود بموقعك.
والنشر شرط لازم، مو شرط كافٍ. يمكن يكون المشروع مكتوب بترويسته «منشور» وهو ما يخدم شيئاً، لثلاثة أسباب ترجع لها هذي الصفحة: مفتاح السنيبت في الودجت ← السنيبت مطفّي، أو ما بقي عنده نطاق مباشر، أو تخفيض باقة أوقف المشروع.
والنشر يسكّ المفتاح العام للمشروع لو ما كان عنده واحد، وهو معرّف يبدأ بـmd_ وبعده 40 محرفاً:
md_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXالمفتاح عام بالتصميم (موجود بمصدر صفحتك)، وهو ليس اعتماد صلاحية أبداً. وظيفته إنه يحدّد الصفحة تتبع أي مشروع، ويفتح أسطح الودجت العامة لهذا المشروع وحده: الملاحظات والاستبيانات والإعلانات. والخادم يعيد فحص الأصل والباقة وكل حقل عند الاستقبال. وترجيع المشروع لمسودّة يحتفظ بالمفتاح، عشان السنيبت المُضمَّن بموقعك ما ينكسر لمّا تنشر من جديد.
انسخ السنيبت من الودجت ← السنيبت بدل هذا المثال، فهو أصلاً فيه مفتاحك.
<script> (function(w,d){ var t=0;try{t=w.localStorage.getItem('md_mode_md_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')==='technical';}catch(e){} if(t&&!w.__mdCap){ w.__mdCap=1; var L=w.__mdLogs=w.__mdLogs||[]; var rec=function(lvl,msg){try{L.push({level:lvl,message:String(msg).slice(0,2000)});if(L.length>200)L.shift();}catch(e){}}; ['log','info','warn','error'].forEach(function(k){var o=console[k];if(o)console[k]=function(){try{rec(k,Array.prototype.map.call(arguments,String).join(' '));}catch(e){}return o.apply(console,arguments);};}); w.addEventListener('error',function(e){rec('error',(e.message||'Script error')+' @ '+(e.filename||'')+':'+(e.lineno||''));},true); w.addEventListener('unhandledrejection',function(e){var m='Unhandled promise rejection';try{var r=e&&e.reason;m+=': '+((r&&(r.stack||r.message))||String(r));}catch(x){}rec('error',m);}); } var s=d.createElement('script'); s.async=1; s.src='https://api.umarker.com/widget/v1.js'; s.setAttribute('data-umarker-key','md_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'); (d.head||d.documentElement).appendChild(s); })(window,document);</script>السنيبت يسوّي شيئين. أولاً، الجزء المضمّن يشيك على وضع التقاط المشروع زي ما شافه هالمتصفّح آخر مرّة
(الودجت يخزّنه باسم md_mode_<مفتاحك> مع كل تحميل). ولو كان تقنياً بس، يبدأ فوراً بتخزين مخرجات
الكونسول والأخطاء، فالعطل اللي يصير قبل ما يكمل الودجت تحميله يوصل مع التقرير برضه. أمّا لمشروع على
العادي، وفي أول تحميل صفحة للزائر، فما يسجّل شي. وبعدين يضيف الملفّ الحقيقي بـasync، فما يعطّل أول
رسم لصفحتك أبداً.
وخاصيّتان تحملان كل شي:
| الخاصيّة | القيمة | وش تسوّي |
|---|---|---|
src |
https://api.umarker.com/widget/v1.js |
ملفّ الودجت. والودجت يقرأ عنوان الـAPI من أصل هذا السكربت نفسه، فلازم يكون مضيف الـAPI. |
data-umarker-key |
مفتاحك md_… |
يحدّد التقرير يتبع أي مشروع. |
معزول بـShadow DOM
الزرّ وأداة الالتقاط يُركَّبان داخل Shadow DOM مع تصفير all:initial للمضيف، فلا CSS عندك يقدر
ينسّقهما ولا أنماطهما توصل لصفحتك. أمّا جافاسكربت فقصّة ثانية: شوف وش يلمسه الودجت بصفحتك تحت.
يسكت ولا يكسر
لو كان المفتاح مجهولاً أو مسحوباً، أو الأصل مو بقائمة النطاقات، أو المشروع مسودّة، أو الملفّ محجوب، فالودجت ببساطة ما يُركَّب. وما يرمي خطأ في صفحتك أبداً.
غير معطّل
الملفّ يتحمّل بـasync، وما ينضاف شي لصفحتك إلا بعد ما يرجع نداء الإعدادات حقّه — فما يزاحم
أول رسم لصفحتك أبداً.
ما يتكرّر
حارس window.__umarkerLoaded يخلّي النسخة الثانية من السنيبت ترجع فوراً، فما يشوف المُبلِّغ
زرّين. وهو «الأول يكسب» وما يقارن المفاتيح إطلاقاً: شيل السنيبت القديم، لا تلصق الجديد
جنبه. ولو كانت إضافة المتصفّح شغّالة على نفس الصفحة، تتولّى هي وتشيل زرّ السنيبت.
الـShadow DOM يعزل الوسوم والأنماط، وما يسوّي شي لجافاسكربت. وفي الوضع التقني الودجت فعلاً يلمس ثلاثة متغيّرات عامّة بصفحتك — عن قصد، لأنّ هذي هي الطريقة اللي توصل فيها رسائل الكونسول والطلبات الفاشلة للتقرير. وفي الوضع العادي ما يغلّف ولا واحد منها:
console.log/info/warn/error تُغلَّف عشان تُسجَّل مخرجاتها، وبعدين تُنادى الأصلية بنفس الوسائط.fetch وXMLHttpRequest تُغلَّفان عشان تُسجَّل الطلبات اللي تسوّيها صفحتك: الطريقة والرابط (مع تفريغ
القيم اللي شكلها أسرار) والحالة والتوقيت، والفاشل موسوم. والترويسات والأجسام ما تُقرأ أبداً. وكودك أنت ما
يحسّ بأي فرق: كائن Response الأصلي يرجع لك، والخطأ الأصلي يُرمى من جديد بدون أي تغيير.ومتغيّراته هو محجوزة باسمه: window.uMarker ومفاتيح window.__md… / window.__umarker…. وما
يتغيّر شي ثاني بصفحتك.
كل شي يروح لأصل الـAPI وبس. تسع نقاط، كلّها مفتوحة لأي أصل (CORS) ومحدودة المعدّل على الخادم. وثلاثة طلبات GET تنطلق مع كل تحميل صفحة — اسمح للثلاثة عند الوكيل أو الـWAF، وإلا تموت الاستبيانات وخلاصة «ما الجديد» بصمت:
GET /api/public/widget/{key}/config: إعدادات المشروع، ومعها
الاستهداف اللي يُقيَّم قبل التركيب.GET /api/public/widget/{key}/survey: الاستبيان الوحيد المؤهَّل لهذي الصفحة،
لو فيه واحد.GET /api/public/widget/{key}/feed: الإعلانات المباشرة
ومدخلات «ما الجديد».والباقي كلّه POST. فـPOST …/feedback (تقرير) وPOST …/survey/{id}/respond (إجابة استبيان)
يحتاجان الزائر يسوّي شيئاً. أمّا إشارات المشاهدة/الإغلاق/النقر الأربع فلا: الاستبيان أو الإعلان
المباشر يُطلق إشارة present / seen أول ما ينرسم، مرّة وحدة لكل زائر لكل عنصر. فاسمح بالـPOST
كمان، وإلا انحجب إعلان مباشر على صفحة ما نقر فيها أحد.
والحدود الافتراضية، وكلّها قابلة للضبط من مشغّل المنصّة: التقارير وإجابات الاستبيانات تتقاسم 20 بالدقيقة لكل مفتاح و30 بالدقيقة لكل عنوان IP؛ والقراءات الثلاث لها 600 بالدقيقة لكل عنوان IP، ومثلها للإشارات في دلو مستقلّ.
لو موقعك يرسل CSP صارمة، اسمح للودجت بثلاثة أشياء. وكل اللي يحمّله يجي من أصل واحد؛ ما فيه أي CDN طرف ثالث بالمسار:
script-src: السكربت المضمّن (بـnonce أو hash، أو 'unsafe-inline')، وapi.umarker.com
لـ/widget/v1.js ولأداة الالتقاط المشتركة ولمكتبة اللقطات، وهذي مستضافة ذاتياً تحت
/widget/vendor/ على نفس الأصل.connect-src: api.umarker.com، لكل طلب مذكور في نقاط النهاية فوق.img-src: اسمح بـdata: عشان تنرسم اللقطة وتنعرض داخل المتصفّح.uMarker ما يعطي الزائر أي هويّة من عنده: تقرير السنيبت المجهول يُكتب بلا مستخدم وبلا بريد. لكن لو موقعك أصلاً يعرف مين الزائر، ألحِق بريده وأي بيانات إضافية عشان تجيك التقارير منسوبة.
وهذا كلام عن حقولنا نحن، مو عن التقرير ككلّ. في الوضع التقني رسائل الكونسول وروابط الطلبات تُلتقط مع كل تقرير، ومنها المجهولة، وتحمل اللي حطّه تطبيقك فيها — بريد مستخدم مسجّل داخل سطر تصحيح، أو معرّف حساب داخل مسار طلب فاشل. شغّل الإخفاء في الودجت ← الإعداد فيُموَّه الاثنان داخل المتصفّح قبل ما يطلع أي شي. شوف السياق التقني وإخفاء البيانات.
وناد identify() قبل تحميل السنيبت متى ما قدرت، لسببين. أوّلاً إنها تدمج ولا تستبدل — النداء
المتأخّر يكتب فوق الحقول اللي مرّرتها بس ويترك الباقي مكانه، فما فيه طريقة تمسح فيها الهويّة عند
تسجيل الخروج غير إعادة تحميل الصفحة. وثانياً إنّ قاعدة المستخدمون المعرَّفون فقط تُقرَّر
أوّل مرّة لحظة ما يوصل ردّ الإعدادات: الهويّة اللي توصل بعدها تنحسب، لكن الودجت ما يطلع إلا لمّا
توصل، فالتعريف البدري يوفّر عليك تأخيراً ملحوظاً.
<script> window.uMarker = window.uMarker || []; window.uMarker.push(['identify', { email: 'visitor@example.com', data: { plan: 'pro', userId: 42, appVersion: '3.1.0' } }]);</script>وبعد ما يتحمّل الملفّ، window.uMarker.identify('visitor@example.com', { … }) تسوّي نفس الشي.
ولازم يكون email بريداً إلكترونياً حقيقياً أو null، وdata كائناً ما يتجاوز 16 كيلوبايت من
JSON. والاثنان يُتحقَّق منهما لمّا يُرسَل التقرير، مو لمّا تنادي identify() — فتمرير معرّف
مستخدم داخلي مكان البريد يرفض التقرير كامل، ويروح معه كلام الزائر ودبابيسه ولقطته. استخدم حقل
البريد الحقيقي عندك، أو خلّه null.
وكائن data يُخزَّن مع التقرير. أمّا عرضه في صفحة التقرير فما يصير إلا
للمفاتيح اللي يقابلها حقل مخصّص معرَّف على المساحة — والمفتاح اللي ما له حقل مقابل يُحفَظ وما
يُعرَض أبداً، والحقول المخصّصة ميزة باقة احترافي وفوق.
الودجت يوفّر نداءين، عشان تقدر تحطّ الملاحظات خلف عنصر بقائمتك أو رابط مساعدة بدل زرّنا وحده. واحرسهما — النداءان معرَّفان بآخر التركيب، يعني ما يوجدان إلا بعد ما يتركّب الودجت فعلاً على هذي الصفحة:
if (window.uMarker?.open) window.uMarker.open(); // يفتح أداة الالتقاطif (window.uMarker?.hasDraft) window.uMarker.hasDraft(); // true لو فيه تقرير غير مُرسَل هنافما واحد منهما معرَّف وقت ما يكون نداء الإعدادات ما زال طائراً، ولا على صفحة تستثنيها قواعد
الاستهداف، ولا بعد ما ينتهي سقف التكرار، ولا لمّا تتولّى إضافة
المتصفّح الصفحة. وبدون حارس، النداء يرمي TypeError داخل سكربتك أنت. أمّا طابور identify فوقه فما
عنده هذي المشكلة: window.uMarker مصفوفة تنشئها أنت بنفسك، والملفّ يفرّغها ويستبدلها بالكائن
الحقيقي أوّل ما يشتغل — قبل كل هذا بكثير.
افتح صفحة على أحد نطاقاتك المسموحة. يظهر الزرّ بالزاوية اللي حدّدتها في التخصيص، وهي أسفل اليمين افتراضياً.
انقره. تتولّى أداة الالتقاط الصفحة: مرّر على عنصر فيضيء مع نموذج الصندوق حقّه. انقر عشان ينزل دبوس مرقّم واكتب فيه ملاحظتك.
اضغط مراجعة — وهنا بالضبط تخفي الأداة نفسها وتاخذ اللقطة — ثم إرسال للمراجعة عشان ترسل. ويطلع بعدها تأكيد وصلت ملاحظتك.
في الودجت ← السنيبت، تنقلب اللوحة من بانتظار ودجت موقعك إلى ودجت موقعك مباشر من نفسها؛ هي تسأل الخادم كل بضع ثوانٍ، فما تحتاج تعيد التحميل. أمّا الوقت النسبي لآخر ظهور فمكانه النظرة العامة للمشروع.
والكشف نفسه إشارة حضور تقريبية: أول تحميل يُختَم فوراً واللوحة تلتقطه خلال ثوانٍ، وبعدها يُحدَّث الختم مرّة كل ساعة على الأكثر — فـ«آخر ظهور» بالنظرة العامة ممكن يتأخّر لساعة.
افتح الوارد: التقرير موجود. وقائمة الوارد ما تقول من وين جا التقرير — افتحه، ويبيّن لك صفّ المُبلِّغ بريد الزائر، أو «زائر عام» لو ما أعطى بريداً.
الطلب المرفوض (انقطاع، شبكة متذبذبة، خطأ 5xx أثناء نشر) يُكتب التقرير في متصفّح الزائر نفسه لمدّة
سبعة أيام، ويُدفَع مرّة وحدة بهدوء بزيارته الجاية. ولو كان التخزين ممتلئاً ما يسع، تُسقَط اللقطة
ويبقى الكلام: الصورة تنلتقط من جديد، واللي كتبه الزائر لا.
أمّا الرفض الدائم (مفتاح مسحوب، ودجت مطفّى، بيانات غير صالحة) فما يُحفَظ، لأنّ إعادة المحاولة بتفشل
للأبد. والاستثناء الوحيد 429: كلٌّ من حدّ الدقيقة والحدّ اليومي ينجح بمحاولة لاحقة، فيُحفَظ.
في الودجت ← السنيبت منطقة خطرة:
410.والاثنان يرجّعان حالة التثبيت إلى غير مُثبَّت، لأنّ السنيبت القديم ميت والجديد ما بلّغ بعد.
وبما أنّ المفتاح عام بالتصميم، فالتدوير هو ردّك على مفتاح مسحوب من الصفحة أو مُساء استخدامه. وبين هذا وذاك، اللي يحميك فعلاً هو فحص النطاق المسموح، وحدود المعدّل لكل مفتاح ولكل IP، وسقوف الحمولة.
مفروضة على الخادم. في الملاحظة التقنية، رسائل الكونسول والطلبات الفاشلة وباقي السجلّ التقني
تُقصَّر لآخر المدخلات بدل ما تُرفض — فالصفحة الثرثارة ترسل برضه. والملاحظة العادية ما تحمل منها شي. وأي شي ثاني فوق السقف يُرفض، والزائر يشوف ردّ الخادم نفسه حرفياً. وهذي
الردود جُمل واضحة بلغة العلامة: اللقطة اللي تتجاوز السقف تنقال بالكلام مو بعدد محارف، والملاحظة أو
ملاحظة الدبوس اللي تتجاوز حدّها تتسمّى زي ما يعرفها الزائر، مو بمسار حقلها. والتقرير المرفوض ما يُحفَظ
كمسودّة أبداً؛ اللي يُحفَظ هو 429 و5xx فقط.
| الحقل | الحدّ |
|---|---|
| التعليق | 5,000 محرف، مطلوب |
| الدبابيس بالتقرير | 50 دبوساً، كل واحد بملاحظة حتى 5,000 محرف |
| اللقطة | 12 ميغابايت بعد فكّ الترميز |
| رسائل الكونسول (تقني) | آخر 200 رسالة |
| الطلبات الفاشلة (تقني) | آخر 20 طلباً |
البيانات المخصّصة (identify) |
16 كيلوبايت من JSON |
page_url |
رابط http/https، حتى 2,048 محرفاً |
| التقارير اليومية (الباقة المجانية) | 5 تقارير من السطح العام المجهول |