التثبيت حسب المنصة
أي موقع إلكتروني
التثبيت npm install @blipit/browser
حجم حزمة SDK للمتصفح من Blipit هو 10 KB. تلتقط الأخطاء غير الملتقطة ورفض الـ promise غير المعالج والطلبات الفاشلة، وتحتفظ بالنقرات والطلبات التي أدت إلى كل خطأ، وتسجّل مؤشرات الويب الحيوية، وتضع زر «أبلغ عن خطأ» في كل صفحة، ويمكنها تسجيل إعادة تشغيل للجلسة عند حدوث خطأ. ثبّتها من npm في تطبيق مجمّع، أو أضف وسم script واحدًا إلى أي صفحة.
1احصل على مفاتيحك
سجّل الدخول في app.blipit.io وافتح «مفاتيح API» في الشريط الجانبي، ثم مشروعك. لكل مشروع مفتاحان. يبدأ المفتاح العام بـ blipit_pk_: يوضع في كود المتصفح والتطبيقات، ولا يستطيع سوى إرسال الأحداث، ومن الآمن أن يراه أي شخص. يبدأ المفتاح السري بـ blipit_sk_: يبقى على خادمك أو في Odoo، وليس في متصفح أبدًا، لأنه يستطيع أيضًا قراءة المشكلات وتغييرها. يُعرض المفتاح السري مرة واحدة فقط، فور إنشائه، لذا انسخه حينها؛ وإذا فقدته، فاضغط «إنشاء مفتاح سري جديد»، فيتوقف القديم عن العمل فورًا. تحتاج بعض حزم SDK أيضًا إلى معرّف المشروع، المعروض في الصفحة نفسها.
2عبر npm
استدعِ init مرة واحدة في ملف الدخول، قبل عرض التطبيق، بالمفتاح العام. مع Vite (React وVue وSvelte)، احتفظ بالمفتاح في .env باسم VITE_BLIPIT_KEY؛ فلا تصل إلى المتصفح إلا متغيرات VITE_، ولا يقرأ خادم التطوير ملف .env إلا عند بدء تشغيله.
npm install @blipit/browserVITE_BLIPIT_KEY=blipit_pk_your_public_keyimport * as Blipit from "@blipit/browser";
Blipit.init({
key: import.meta.env.VITE_BLIPIT_KEY,
environment: import.meta.env.MODE,
release: "2026.09.28",
replay: { onErrorSampleRate: 1 },
});3بدون أداة حزم: وسم script واحد
الصق هذا في <head> كل صفحة، أو في خانة الكود المخصص في منصتك، مع كتابة مفتاحك العام فيه. لا بأس بذلك: فالمفتاح العام لا يستطيع سوى إرسال الأحداث.
<script src="https://blipit.io/sdk/blipit.js"></script>
<script>
Blipit.init({ key: "blipit_pk_your_public_key", environment: "production", release: "2026.09.28", replay: { onErrorSampleRate: 1 } });
</script>4أبقِ المفاتيح خارج git
احتفظ بالمفاتيح في متغيرات البيئة أو في الإعدادات السرية لمنصة الاستضافة، وليس أبدًا في كود تودعه في المستودع، وأضف ملفات .env إلى .gitignore. وجود مفتاح عام في صفحة ويب أمر طبيعي. إذا انتهى مفتاح سري يومًا في git أو صفحة عامة أو لقطة شاشة أو محادثة، فافتح «مفاتيح API»، واضغط «إنشاء مفتاح سري جديد»، والصق المفتاح الجديد في كل مكان كان يُستخدم فيه القديم: يتوقف المفتاح القديم عن العمل فورًا.
.env
.env.local
.env.*.local5أخبر Blipit من هو المستخدم (اختياري)
بعد تسجيل الدخول، أرفق المستخدم لتُظهر المشكلات من تأثر ويمكن العثور على إعادات التشغيل حسب المستخدم.
Blipit.setUser({ id: "42", email: "ana@example.com" });6React وVue وAngular وSvelte: أبلغ عن الأخطاء الملتقطة
تلتقط أطر العمل الأخطاء داخل المكوّنات قبل أن يراها المتصفح، لذا مرّرها إلى Blipit أيضًا. أما الأخطاء غير الملتقطة في أي مكان آخر فيُبلَّغ عنها تلقائيًا.
createRoot(document.getElementById("root")!, {
onCaughtError: (error) => Blipit.captureException(error),
onUncaughtError: (error) => Blipit.captureException(error),
}).render(<App />);class ErrorBoundary extends React.Component<{ children: React.ReactNode }, { failed: boolean }> {
state = { failed: false };
static getDerivedStateFromError() {
return { failed: true };
}
componentDidCatch(error: Error) {
Blipit.captureException(error);
}
render() {
return this.state.failed ? <p>Something went wrong.</p> : this.props.children;
}
}const app = createApp(App);
app.config.errorHandler = (err) => Blipit.captureException(err);
app.mount("#app");import { ErrorHandler } from "@angular/core";
import * as Blipit from "@blipit/browser";
class BlipitErrorHandler implements ErrorHandler {
handleError(error: unknown) {
Blipit.captureException(error);
console.error(error);
}
}
export const appConfig = { providers: [{ provide: ErrorHandler, useClass: BlipitErrorHandler }] };import * as Blipit from "@blipit/browser";
import type { HandleClientError } from "@sveltejs/kit";
export const handleError: HandleClientError = ({ error }) => {
Blipit.captureException(error);
};10املأ نافذة الإبلاغ مسبقًا وأضف السياق
استدعِ setUser بعد تسجيل الدخول: يُملأ اسم المُبلِّغ وبريده تلقائيًا، ويصله بريد عندما ترد أو تغيّر الحالة. تضيف setReportMetadata حقولك الخاصة، مثل الخطة أو حجم سلة التسوق، إلى كل بلاغ؛ وتعمل عند إرسال البلاغ، لذا تكون القيم محدّثة.
Blipit.setUser({ id: "42", username: "Ana Lima", email: "ana@example.com" });
Blipit.setReportMetadata(() => ({ plan: "pro", cartItems: cart.length }));11كل الخيارات والدوال
- key: المفتاح العام (blipit_pk_). مطلوب.
- environment وrelease: يظهران على كل حدث؛ ويتيح release اكتشاف التراجعات وخرائط المصدر. القيمة الافتراضية لـ environment هي production.
- debug: true يسجّل ما تفعله SDK في وحدة التحكم، في أسطر تبدأ بـ [blipit].
- تتحكم sampleRate (من 0 إلى 1) وignoreErrors (نصوص أو أنماط) وbeforeSend (عدّل حدثًا، أو أرجع null لإسقاطه) في ما يُرسل. يُسقط autoMuteExtensions (مفعّل افتراضيًا) الأخطاء القادمة من إضافات المتصفح فقط.
- webVitals (مفعّل افتراضيًا)، وreplay ({ sessionSampleRate, onErrorSampleRate })، وautoSessionTracking (معدلات الخلو من الأعطال، ويحتاج إلى release).
- feedbackWidget: false يخفي زر «أبلغ عن خطأ»، أو يغيّره كائن يحتوي position وstyle وtext وcolor وfont وmatch وshortcut. يحدد theme: "light" أو "dark" أو "auto" مظهر نافذة الإبلاغ.
- يملأ user ({ id, name, email }) وcompany (اسم أو { id, name }) نافذة الإبلاغ ويُضافان إلى البلاغات.
- endpoint: فقط لخادم استقبال مستضاف ذاتيًا؛ القيمة الافتراضية https://in.blipit.io/api/v1/events.
- الدوال: captureException(error)، وcaptureMessage(text, level)، وsetUser، وsetTag(key, value)، وaddBreadcrumb({ category, message })، وopenReport()، وattachReport(element)، وreportButton(options)، وupdateWidget(options)، وsetReportMetadata(fn)، وshowFeedback()، وflush() التي تُرجع promise بعد إرسال الأحداث المنتظرة في الطابور.
- تصل تغييرات إعدادات الأداة في لوحة التحكم إلى المتصفحات خلال ساعة، لأن SDK تحتفظ بها طوال هذه المدة؛ وتعرض النافذة الخاصة التغيير فورًا.
12تحقق من أنه يعمل
أعد تحميل موقعك. يظهر زر «أبلغ عن خطأ» في الزاوية السفلية اليمنى، وخلال دقيقة يظهر عرض الصفحة ضمن «مؤشرات الويب الحيوية» في app.blipit.io. ثم أرسل حدثًا تجريبيًا: استدعِ captureMessage مرة واحدة من كودك، أو مع وسم script شغّل السطر أدناه في وحدة تحكم المتصفح. يظهر ضمن «المشكلات» خلال ثوانٍ.
Blipit.captureMessage("Hello from " + location.host, "info");من المفيد معرفته
- الخيارات: sampleRate (من 0 إلى 1)، وignoreErrors (سلاسل نصية أو أنماط)، وbeforeSend لإسقاط حدث أو تعديله، وmaxBreadcrumbs، وwebVitals (مفعّل افتراضيًا)، وautoSessionTracking لمعدلات الخلو من الأعطال (يحتاج إلى release).
- يقدّم blipit.io/sdk/blipit.js دائمًا أحدث إصدار (0.3.23). توجد الإصدارات المثبّتة في blipit.io/sdk/0.3.23/blipit.js إذا أردت التحكم في الترقيات.
- إذا كان موقعك يرسل Content Security Policy، فاسمح بـ script-src https://blipit.io (وسم السكربت، ومحرر نافذة الإبلاغ وإضافة إعادة التشغيل اللذان يُحمَّلان من blipit.io/sdk/<version>/ عند أول استخدام)، وبـ connect-src https://in.blipit.io (تذهب الأحداث ولقطات الشاشة وتسجيلات الشاشة كلها إلى in.blipit.io)، وبـ img-src data: (تُرسم لقطة الشاشة من صورة للصفحة)، وبـ media-src blob: (تُعرض التسجيلات داخل نافذة الإبلاغ). تعيد لقطة الشاشة تحميل صور الصفحة وخطوطها، لذا أضف نطاقاتها إلى connect-src أيضًا، وإلا ظهرت فارغة. لا حاجة لأي تغيير في style-src. مع وسم السكربت، استدعِ Blipit.init من ملف .js خاص بك أو أعطِ السكربت المضمّن nonce، لأن السياسة الصارمة تمنع السكربتات المضمّنة. لتسجيل الصوت مع تسجيل الشاشة، يجب أن تسمح ترويسة Permissions-Policy في موقعك بـ microphone=(self)، وبـ display-capture=(self) لتسجيل الشاشة؛ ومع microphone=() تعمل التسجيلات دون صوت.
- إبقاء Blipit محدّثًا: يشرح دليل إبقاء Blipit محدّثًا (docs.blipit.io/updates) لافتة التحديث، ورسائل البريد للإصدارات المهمة، والتنبيه في وحدة تحكم التطوير، وأمر التحديث لهذه المنصة.
- مشروع واحد لكل تطبيق ومنصة: يختار كل مشروع منصته عند إنشائه (Android أو iOS أو React Native أو Flutter أو Web أو Backend أو Odoo)، ويرفض Blipit البيانات القادمة من أي منصة أخرى مع رسالة خطأ واضحة، لذلك يحتاج تطبيق iOS وتطبيق Android إلى مشروعين بمفتاحين. الإصدارات والنسخ ومعدلات الأعطال وإصدارات المتاجر تختلف من منصة لأخرى، وخلطها في مشروع واحد يجعلها كلها خاطئة. يقبل مشروع Web أيضًا جانب الخادم من تطبيق الويب نفسه (خادم Next.js أو Node)، ويقبل مشروع React Native أو Flutter أيضًا تقارير الأعطال الأصلية الخاصة به على Android وiOS.
هل واجهتك مشكلة؟ راسل support@blipit.io. المفاتيح ومعرّف كل مشروع موجودة تحت مفاتيح API في app.blipit.io.





