أي موقع إلكتروني

التثبيت npm install @blipit/browser

حجم حزمة SDK للمتصفح من Blipit هو 10 KB. تلتقط الأخطاء غير الملتقطة ورفض الـ promise غير المعالج والطلبات الفاشلة، وتحتفظ بالنقرات والطلبات التي أدت إلى كل خطأ، وتسجّل مؤشرات الويب الحيوية، وتضع زر «أبلغ عن خطأ» في كل صفحة، ويمكنها تسجيل إعادة تشغيل للجلسة عند حدوث خطأ. ثبّتها من npm في تطبيق مجمّع، أو أضف وسم script واحدًا إلى أي صفحة.

الصقها في Claude Code أو Cursor أو أي مساعد برمجة بالذكاء الاصطناعي. تحتوي على الخطوات والشيفرة. في app.blipit.io ضمن مفاتيح API تجد التعليمات نفسها مع مفتاحك مكتوباً فيها.
فيديو: ثبّت Blipit في أي تقنية، من 0:32

1احصل على مفاتيحك

سجّل الدخول في app.blipit.io وافتح «مفاتيح API» في الشريط الجانبي، ثم مشروعك. لكل مشروع مفتاحان. يبدأ المفتاح العام بـ blipit_pk_: يوضع في كود المتصفح والتطبيقات، ولا يستطيع سوى إرسال الأحداث، ومن الآمن أن يراه أي شخص. يبدأ المفتاح السري بـ blipit_sk_: يبقى على خادمك أو في Odoo، وليس في متصفح أبدًا، لأنه يستطيع أيضًا قراءة المشكلات وتغييرها. يُعرض المفتاح السري مرة واحدة فقط، فور إنشائه، لذا انسخه حينها؛ وإذا فقدته، فاضغط «إنشاء مفتاح سري جديد»، فيتوقف القديم عن العمل فورًا. تحتاج بعض حزم SDK أيضًا إلى معرّف المشروع، المعروض في الصفحة نفسها.

مفاتيح API في app.blipit.io: المفتاح العام (blipit_pk_) لكود المتصفح، والمفتاح السري (blipit_sk_) للخوادم وOdoo.
مفاتيح API في app.blipit.io: المفتاح العام (blipit_pk_) لكود المتصفح، والمفتاح السري (blipit_sk_) للخوادم وOdoo.
يُعرض المفتاح السري الجديد مرة واحدة. انسخه الآن: يُخزّن مجزّأً (hashed) ولا يمكن عرضه مرة أخرى.
يُعرض المفتاح السري الجديد مرة واحدة. انسخه الآن: يُخزّن مجزّأً (hashed) ولا يمكن عرضه مرة أخرى.

2عبر npm

استدعِ init مرة واحدة في ملف الدخول، قبل عرض التطبيق، بالمفتاح العام. مع Vite (React وVue وSvelte)، احتفظ بالمفتاح في .env باسم VITE_BLIPIT_KEY؛ فلا تصل إلى المتصفح إلا متغيرات VITE_، ولا يقرأ خادم التطوير ملف .env إلا عند بدء تشغيله.

sh
npm install @blipit/browser
.env
VITE_BLIPIT_KEY=blipit_pk_your_public_key
src/main.js
import * 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> كل صفحة، أو في خانة الكود المخصص في منصتك، مع كتابة مفتاحك العام فيه. لا بأس بذلك: فالمفتاح العام لا يستطيع سوى إرسال الأحداث.

html
<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»، واضغط «إنشاء مفتاح سري جديد»، والصق المفتاح الجديد في كل مكان كان يُستخدم فيه القديم: يتوقف المفتاح القديم عن العمل فورًا.

.gitignore
.env
.env.local
.env.*.local

5أخبر Blipit من هو المستخدم (اختياري)

بعد تسجيل الدخول، أرفق المستخدم لتُظهر المشكلات من تأثر ويمكن العثور على إعادات التشغيل حسب المستخدم.

js
Blipit.setUser({ id: "42", email: "ana@example.com" });

6React وVue وAngular وSvelte: أبلغ عن الأخطاء الملتقطة

تلتقط أطر العمل الأخطاء داخل المكوّنات قبل أن يراها المتصفح، لذا مرّرها إلى Blipit أيضًا. أما الأخطاء غير الملتقطة في أي مكان آخر فيُبلَّغ عنها تلقائيًا.

React 19 (src/main.tsx)
createRoot(document.getElementById("root")!, {
  onCaughtError: (error) => Blipit.captureException(error),
  onUncaughtError: (error) => Blipit.captureException(error),
}).render(<App />);
أو، React 18 وما قبله: حدّ أخطاء (error boundary)
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;
  }
}
Vue (src/main.ts)
const app = createApp(App);
app.config.errorHandler = (err) => Blipit.captureException(err);
app.mount("#app");
Angular (app.config.ts)
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 }] };
SvelteKit (src/hooks.client.ts)
import * as Blipit from "@blipit/browser";
import type { HandleClientError } from "@sveltejs/kit";

export const handleError: HandleClientError = ({ error }) => {
  Blipit.captureException(error);
};

7بلاغات الأخطاء: زر «أبلغ عن خطأ»

بمجرد أن تبدأ SDK بمفتاحك العام، يظهر زر «أبلغ عن خطأ» في الزاوية السفلية اليمنى من كل صفحة، بلغة الزائر. تفتح النقرة نافذة الإبلاغ: لقطة شاشة للصفحة لوضع العلامات عليها، وأداة لاختيار عنصر، وتسجيل اختياري للشاشة، وعنوان ووصف. غيّر الموضع والشكل والنص واللون واختصار لوحة المفاتيح في الكود كما هو موضح أدناه، أو لكل المواقع دفعة واحدة في app.blipit.io، «إعدادات المشروع»، «أداة تقارير الأخطاء»؛ والأولوية لخيارات الكود. يعرض دليل زر الإبلاغ عن الأخطاء كل خيار مع لقطات شاشة وعرض تجريبي مباشر.

js
Blipit.init({
  key: import.meta.env.VITE_BLIPIT_KEY,
  feedbackWidget: {
    position: "bottom-left",
    style: "icon",
    text: "Report Issue",
    color: "#E11D48",
    shortcut: "ctrl+shift+b",
  },
});
زر «أبلغ عن خطأ» الافتراضي، أسفل اليمين.
زر «أبلغ عن خطأ» الافتراضي، أسفل اليمين.
نافذة الإبلاغ: لقطة شاشة عليها علامات، والعنوان، وما حدث.
نافذة الإبلاغ: لقطة شاشة عليها علامات، والعنوان، وما حدث.

8فتح نافذة الإبلاغ من زرك الخاص

لوضع زر أبلغ عن خطأ في ترويسة موقعك أو قائمتك، استخدم الزر الرسمي: تُرجع Blipit.reportButton() زرًا جاهزًا فيه أيقونة Blipit وعبارة أبلغ عن خطأ بلغة الزائر، ويمكن لتطبيقات React عرض <BlipitReportButton /> من @blipit/nextjs/react (npm install @blipit/nextjs). تفضّل تصميمك الخاص؟ استدعِ openReport() من أي معالج نقر، أو attachReport(element) لربط عنصر موجود بالفعل. في الحالتين تُفتح نافذة الإبلاغ تمامًا كما تُفتح من الزر العائم. لا يجوز استخدام أيقونة Blipit إلا بجانب عبارة أبلغ عن خطأ، كما يظهر في الزر الرسمي.

الزر الرسمي، HTML عادي
<nav id="help-menu"></nav>
<script>
  document.getElementById("help-menu").append(Blipit.reportButton());
</script>
الزر الرسمي، React
import { BlipitReportButton } from "@blipit/nextjs/react";

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton variant="outline" size="sm" />
    </header>
  );
}
الزر الرسمي، Vue
<script setup>
import { onMounted, ref } from "vue";
import { reportButton } from "@blipit/browser";

const slot = ref();
onMounted(() => slot.value.append(reportButton({ variant: "outline", size: "sm" })));
</script>

<template>
  <span ref="slot"></span>
</template>
HTML عادي
<button id="report-issue">Report Issue</button>
<script>
  Blipit.attachReport(document.getElementById("report-issue"));
</script>

<button onclick="Blipit.openReport()">Report Issue</button>
React
import { openReport } from "@blipit/browser";

export function ReportIssue() {
  return <button onClick={() => openReport()}>Report Issue</button>;
}
Vue
<script setup>
import { openReport } from "@blipit/browser";
</script>

<template>
  <button @click="openReport()">Report Issue</button>
</template>
زر أبلغ عن خطأ الرسمي في ترويسة موقع.
زر أبلغ عن خطأ الرسمي في ترويسة موقع.
زر Report Issue مخصص في ترويسة الصفحة يفتح نافذة الإبلاغ في Blipit.
زر Report Issue مخصص في ترويسة الصفحة يفتح نافذة الإبلاغ في Blipit.

9إخفاء الزر الافتراضي

للاحتفاظ بزرك الخاص فقط، أوقف الزر العائم باستخدام feedbackWidget: false في الكود (feedbackWidget={false} على <Blipit />)، أو أوقف «إظهار زر الإبلاغ عن الأخطاء» في إعدادات «أداة تقارير الأخطاء» للمشروع لإخفائه في كل موقع يستخدم المفتاح. تستمر openReport() وattachReport() في العمل في الحالتين.

js
Blipit.init({ key: import.meta.env.VITE_BLIPIT_KEY, feedbackWidget: false });

10املأ نافذة الإبلاغ مسبقًا وأضف السياق

استدعِ setUser بعد تسجيل الدخول: يُملأ اسم المُبلِّغ وبريده تلقائيًا، ويصله بريد عندما ترد أو تغيّر الحالة. تضيف setReportMetadata حقولك الخاصة، مثل الخطة أو حجم سلة التسوق، إلى كل بلاغ؛ وتعمل عند إرسال البلاغ، لذا تكون القيم محدّثة.

js
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 شغّل السطر أدناه في وحدة تحكم المتصفح. يظهر ضمن «المشكلات» خلال ثوانٍ.

js
Blipit.captureMessage("Hello from " + location.host, "info");

13إذا لم يظهر الزر أو الأحداث

  • افتح وحدة تحكم المتصفح وابحث عن الأسطر التي تبدأ بـ [blipit]. فعّل debug (debug: true في init، أو debug على <Blipit />) لترى هل عُرض الزر، أم أُوقف في الكود، أم أخفاه إعداد المشروع.
  • لا يرسل Next.js إلى المتصفح إلا المتغيرات التي تبدأ أسماؤها بـ NEXT_PUBLIC_، لذا استخدم NEXT_PUBLIC_BLIPIT_KEY. ولا يرسل Vite إلا متغيرات VITE_، لذا استخدم VITE_BLIPIT_KEY. مع أي اسم آخر يكون المفتاح فارغًا في المتصفح ولا يبدأ Blipit.
  • أعد تشغيل خادم التطوير بعد إضافة .env أو .env.local أو تغييرهما، فهو لا يقرؤهما إلا عند بدء تشغيله.
  • في Vercel أو أي منصة استضافة أخرى، أضف المتغير نفسه في متغيرات البيئة للمشروع وانشر مجددًا. تُكتب قيم NEXT_PUBLIC_ وVITE_ داخل البناء، لذا لا يرى النشر الجاري أبدًا قيمة أُضيفت لاحقًا.
  • استخدم المفتاح العام (blipit_pk_). يُرفض المفتاح السري (blipit_sk_) في المتصفح مع خطأ في وحدة التحكم؛ وإذا ظهر مفتاح سري في صفحة يومًا، فأنشئ مفتاحًا سريًا جديدًا.
  • في Next.js، يوضع <Blipit /> في ملف app/layout.tsx الجذري (أو pages/_app.tsx) ليعمل في كل صفحة. في التطبيقات الأخرى، استدعِ init مرة واحدة في ملف الدخول، قبل عرض التطبيق.
  • يجب أن يكون «إظهار زر الإبلاغ عن الأخطاء» مفعّلًا في app.blipit.io، «إعدادات المشروع»، «أداة تقارير الأخطاء»، ويجب ألا يمرّر كودك feedbackWidget: false. تحتفظ SDK بإعدادات المشروع لمدة تصل إلى ساعة، لذا اختبر أي تغيير في نافذة خاصة.
  • قد تحظر أدوات حظر الإعلانات وإضافات الخصوصية in.blipit.io. جرّب نافذة خاصة مع إيقاف الإضافات.
  • إذا كان موقعك يرسل Content Security Policy، فاسمح بـ script-src https://blipit.io وبـ connect-src https://in.blipit.io وبـ img-src data: وبـ media-src blob:. يُحمَّل محرر نافذة الإبلاغ من blipit.io/sdk عند أول نقرة، وتُرسم لقطة الشاشة من صورة data:، وتُرفع تسجيلات الشاشة أيضًا إلى in.blipit.io. عند تفعيل debug تذكر وحدة التحكم متى منعت السياسة لقطة الشاشة. لتسجيل الصوت مع تسجيل الشاشة، يجب أن تسمح ترويسة Permissions-Policy في موقعك بـ microphone=(self)، وبـ display-capture=(self) لتسجيل الشاشة؛ ومع microphone=() تعمل التسجيلات دون صوت.
  • تحقق من الإصدار المثبّت باستخدام npm ls @blipit/browser @blipit/nextjs (أو pnpm list @blipit/browser @blipit/nextjs) وقارنه بسجل التغييرات. ينتظر pnpm 11 يومًا قبل أن يثبّت إصدارًا جديدًا (minimum-release-age)، لذلك يثبّت pnpm add في يوم الإصدار الإصدار السابق دون أي تنبيه. للحصول على الإصدار الجديد فورًا: pnpm add @blipit/browser@<version> @blipit/nextjs@<version> --config.minimum-release-age=0.
  • ما زلت عالقًا؟ راسل support@blipit.io مع أسطر [blipit] من وحدة التحكم.

من المفيد معرفته

  • الخيارات: 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.