التثبيت حسب المنصة
Next.js وReact
التثبيت npm install @blipit/nextjs
تمنحك @blipit/nextjs أخطاء المتصفح ومؤشرات الويب الحيوية وإعادة تشغيل الجلسات وزر «أبلغ عن خطأ» من مكوّن واحد في التخطيط، وأخطاء مكوّنات الخادم ومعالجات المسارات وإجراءات الخادم من سطر واحد في instrumentation.ts. تستخدم تطبيقات React العادية @blipit/browser.
1التثبيت
npm install @blipit/nextjs2احصل على مفاتيحك
سجّل الدخول في app.blipit.io وافتح «مفاتيح API» في الشريط الجانبي، ثم مشروعك. لكل مشروع مفتاحان. يبدأ المفتاح العام بـ blipit_pk_: يوضع في كود المتصفح والتطبيقات، ولا يستطيع سوى إرسال الأحداث، ومن الآمن أن يراه أي شخص. يبدأ المفتاح السري بـ blipit_sk_: يبقى على خادمك أو في Odoo، وليس في متصفح أبدًا، لأنه يستطيع أيضًا قراءة المشكلات وتغييرها. يُعرض المفتاح السري مرة واحدة فقط، فور إنشائه، لذا انسخه حينها؛ وإذا فقدته، فاضغط «إنشاء مفتاح سري جديد»، فيتوقف القديم عن العمل فورًا. تحتاج بعض حزم SDK أيضًا إلى معرّف المشروع، المعروض في الصفحة نفسها.
3ضع المفاتيح في .env.local
أنشئ ملف .env.local في جذر المشروع يحتوي المفتاح العام للمتصفح، والمفتاح السري للخادم إذا كنت تستخدم جانب الخادم أدناه. لا تصل إلى المتصفح إلا الأسماء التي تبدأ بـ NEXT_PUBLIC_، لذا لا تمنح المفتاح السري هذه البادئة أبدًا. أعد تشغيل npm run dev بعد حفظ الملف. للإنتاج، أضف المتغيرات نفسها في منصة الاستضافة (في Vercel: Project، Settings، Environment Variables، لكل من Production وPreview) وانشر مجددًا: تُكتب قيم NEXT_PUBLIC_ داخل البناء، لذا فإن أي نشر تم قبل إضافتها يحمل مفتاحًا فارغًا.
NEXT_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key4جهة المتصفح
أضف المكوّن مرة واحدة في التخطيط الجذري. يقرأ المفتاح العام من NEXT_PUBLIC_BLIPIT_KEY. إذا كان المتغير فارغًا، فلن يبدأ أي شيء وسيذكر ذلك في وحدة تحكم المتصفح.
import { Blipit } from "@blipit/nextjs";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<Blipit
publicKey={process.env.NEXT_PUBLIC_BLIPIT_KEY!}
environment={process.env.NEXT_PUBLIC_VERCEL_ENV ?? "development"}
release={process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA}
replay={{ onErrorSampleRate: 1 }}
/>
{children}
</body>
</html>
);
}5جهة الخادم
يستدعي Next.js 15 وما بعده onRequestError لأخطاء مكوّنات الخادم ومعالجات المسارات وإجراءات الخادم. سطر واحد في instrumentation.ts يربطه بـ Blipit. بدءًا من @blipit/nextjs 0.2.1 يعمل السطر نفسه أيضًا في التطبيقات التي تحتوي على middleware.ts وفي مسارات Edge (runtime = "edge"): يُبنى التطبيق، وتُبلَّغ أخطاء middleware وEdge أيضًا. لا يحتوي Next.js 14 على onRequestError، لذا غلّف كل معالج مسار وكل إجراء خادم بـ withBlipit كما في المثال الثاني: فهو يبلّغ عن الخطأ ثم يرميه من جديد، ويتجاهل عمليات إعادة التوجيه وnotFound(). اضبط BLIPIT_SECRET_KEY في بيئة الخادم، وليس أبدًا كـ NEXT_PUBLIC_.
export { captureRequestError as onRequestError } from "@blipit/nextjs/server";import { withBlipit } from "@blipit/nextjs/server";
export const GET = withBlipit(async (request: Request) => {
return Response.json(await loadOrders());
});6الخدمات المرتبطة وصحة الخادم
بدءًا من @blipit/nextjs 0.3، صدّر register أيضًا ليبدأ Blipit عند تشغيل الخادم. عندها يسجل طلبات قاعدة البيانات والخدمات الخارجية في صفحة الخدمات المرتبطة، والمعالج والذاكرة وحلقة الأحداث للخادم في صفحة صحة الخوادم. لا يفعل شيئًا في بيئة Edge. على Vercel قد لا يرى register الطلب الوارد: منذ @blipit/nextjs 0.4، غلّف معالجات المسارات وإجراءات الخادم بـ withBlipit فيصبح كل منها طلباً في صفحة Pulse مع استدعاءاته لقاعدة البيانات والخدمات الخارجية، ويُرسل بعد الرد دون أن يؤخره.
export { captureRequestError as onRequestError, register } from "@blipit/nextjs/server";import { withBlipit } from "@blipit/nextjs/server";
export const GET = withBlipit(async (request: Request) => Response.json(await loadOrders()));7الأخطاء التي يلتقطها error.tsx
الأخطاء التي تلتقطها حدود الأخطاء في error.tsx أو global-error.tsx لا تصل أبدًا إلى معالج أخطاء المتصفح، لذا أبلغ عنها من داخل حدود الخطأ. كلا الملفين مكوّنا عميل (client components).
"use client";
import { useEffect } from "react";
import { captureException } from "@blipit/nextjs";
export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
useEffect(() => {
captureException(error);
}, [error]);
return (
<div>
<p>Something went wrong.</p>
<button onClick={() => reset()}>Try again</button>
</div>
);
}"use client";
import { useEffect } from "react";
import { captureException } from "@blipit/nextjs";
export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
useEffect(() => {
captureException(error);
}, [error]);
return (
<html>
<body>
<p>Something went wrong.</p>
</body>
</html>
);
}8أبقِ المفاتيح خارج git
احتفظ بالمفاتيح في متغيرات البيئة أو في الإعدادات السرية لمنصة الاستضافة، وليس أبدًا في كود تودعه في المستودع، وأضف ملفات .env إلى .gitignore. وجود مفتاح عام في صفحة ويب أمر طبيعي. إذا انتهى مفتاح سري يومًا في git أو صفحة عامة أو لقطة شاشة أو محادثة، فافتح «مفاتيح API»، واضغط «إنشاء مفتاح سري جديد»، والصق المفتاح الجديد في كل مكان كان يُستخدم فيه القديم: يتوقف المفتاح القديم عن العمل فورًا.
.env
.env.local
.env.*.local9سياسة أمان المحتوى
إذا كان موقعك يرسل 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=() تعمل التسجيلات دون صوت.
10خرائط المصدر (اختياري)
لتعرض الـ stack traces مصدرك بدلًا من الحزمة المصغّرة، ارفع الخرائط لكل إصدار من خطوة البناء لديك.
BLIPIT_KEY=<secret key> npx @blipit/cli sourcemaps upload .next/static --release "$VERCEL_GIT_COMMIT_SHA"14املأ نافذة الإبلاغ مسبقًا وأضف السياق
استدعِ setUser بعد تسجيل الدخول: يُملأ اسم المُبلِّغ وبريده تلقائيًا، ويصله بريد عندما ترد أو تغيّر الحالة. تضيف setReportMetadata حقولك الخاصة، مثل الخطة أو حجم سلة التسوق، إلى كل بلاغ؛ وتعمل عند إرسال البلاغ، لذا تكون القيم محدّثة.
"use client";
import { useEffect } from "react";
import { setReportMetadata, setUser } from "@blipit/nextjs";
export function BlipitUser({ user }: { user: { id: string; name: string; email: string; plan: string } }) {
useEffect(() => {
setUser({ id: user.id, username: user.name, email: user.email });
setReportMetadata(() => ({ plan: user.plan }));
}, [user]);
return null;
}15تحقق من أنه يعمل
أعد تحميل التطبيق. يظهر زر «أبلغ عن خطأ» في الزاوية السفلية اليمنى، وخلال دقيقة يظهر عرض الصفحة ضمن «مؤشرات الويب الحيوية» في app.blipit.io. ثم أضف زرًا يستدعي captureMessage، أو زرًا يرمي خطأ، وانقر عليه: يظهر الحدث ضمن «المشكلات» خلال ثوانٍ.
"use client";
import { captureMessage } from "@blipit/nextjs";
export function TestBlipit() {
return <button onClick={() => captureMessage("Hello from Next.js")}>Send a test event</button>;
}من المفيد معرفته
- React عادي بدون Next.js: npm install @blipit/browser واستدعِ Blipit.init قبل العرض؛ راجع «أي موقع إلكتروني».
- تأخذ environment وrelease افتراضيًا قيمتي VERCEL_ENV وVERCEL_GIT_COMMIT_SHA على الخادم عند تركهما.
- إبقاء 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.





