Next.js وReact

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

تمنحك @blipit/nextjs أخطاء المتصفح ومؤشرات الويب الحيوية وإعادة تشغيل الجلسات وزر «أبلغ عن خطأ» من مكوّن واحد في التخطيط، وأخطاء مكوّنات الخادم ومعالجات المسارات وإجراءات الخادم من سطر واحد في instrumentation.ts. تستخدم تطبيقات React العادية @blipit/browser.

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

1التثبيت

sh
npm install @blipit/nextjs

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

سجّل الدخول في 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) ولا يمكن عرضه مرة أخرى.

3ضع المفاتيح في .env.local

أنشئ ملف .env.local في جذر المشروع يحتوي المفتاح العام للمتصفح، والمفتاح السري للخادم إذا كنت تستخدم جانب الخادم أدناه. لا تصل إلى المتصفح إلا الأسماء التي تبدأ بـ NEXT_PUBLIC_، لذا لا تمنح المفتاح السري هذه البادئة أبدًا. أعد تشغيل npm run dev بعد حفظ الملف. للإنتاج، أضف المتغيرات نفسها في منصة الاستضافة (في Vercel: Project، Settings، Environment Variables، لكل من Production وPreview) وانشر مجددًا: تُكتب قيم NEXT_PUBLIC_ داخل البناء، لذا فإن أي نشر تم قبل إضافتها يحمل مفتاحًا فارغًا.

.env.local
NEXT_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key

4جهة المتصفح

أضف المكوّن مرة واحدة في التخطيط الجذري. يقرأ المفتاح العام من NEXT_PUBLIC_BLIPIT_KEY. إذا كان المتغير فارغًا، فلن يبدأ أي شيء وسيذكر ذلك في وحدة تحكم المتصفح.

app/layout.tsx
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_.

instrumentation.ts
export { captureRequestError as onRequestError } from "@blipit/nextjs/server";
app/api/orders/route.ts
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 مع استدعاءاته لقاعدة البيانات والخدمات الخارجية، ويُرسل بعد الرد دون أن يؤخره.

instrumentation.ts
export { captureRequestError as onRequestError, register } from "@blipit/nextjs/server";
app/api/orders/route.ts
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).

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

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

9سياسة أمان المحتوى

إذا كان موقعك يرسل 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 مصدرك بدلًا من الحزمة المصغّرة، ارفع الخرائط لكل إصدار من خطوة البناء لديك.

sh
BLIPIT_KEY=<secret key> npx @blipit/cli sourcemaps upload .next/static --release "$VERCEL_GIT_COMMIT_SHA"

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

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

app/layout.tsx
<Blipit
  publicKey={process.env.NEXT_PUBLIC_BLIPIT_KEY!}
  feedbackWidget={{
    position: "bottom-left",
    style: "icon",
    text: "Report Issue",
    color: "#E11D48",
    shortcut: "ctrl+shift+b",
  }}
/>
زر «أبلغ عن خطأ» الافتراضي، أسفل اليمين.
زر «أبلغ عن خطأ» الافتراضي، أسفل اليمين.
نافذة الإبلاغ: لقطة شاشة عليها علامات، والعنوان، وما حدث.
نافذة الإبلاغ: لقطة شاشة عليها علامات، والعنوان، وما حدث.

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

ضع الزر الرسمي في أي مكان باستخدام <BlipitReportButton />، حتى في مكوّنات الخادم: يعرض أيقونة Blipit وعبارة أبلغ عن خطأ بلغة الزائر ويفتح نافذة الإبلاغ. تفضّل تصميمك الخاص؟ يجب أن يكون المكوّن الذي يستدعي openReport مكوّن عميل، لذا ضع "use client" في أعلى ملفه. يجب أن يكون <Blipit /> موجودًا بالفعل في app/layout.tsx. تستورد تطبيقات React التي لا تستخدم Next.js الزر من @blipit/nextjs/react وopenReport من @blipit/browser.

app/header.tsx
import { BlipitReportButton } from "@blipit/nextjs";

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton />
    </header>
  );
}
React بدون Next.js
import { BlipitReportButton } from "@blipit/nextjs/react";

<BlipitReportButton variant="outline" size="sm" />
app/report-issue.tsx
"use client";

import { openReport } from "@blipit/nextjs";

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

export function ReportIssue() {
  return <button onClick={() => openReport()}>Report Issue</button>;
}
زر أبلغ عن خطأ الرسمي في ترويسة موقع.
زر أبلغ عن خطأ الرسمي في ترويسة موقع.
تطبيق Next.js: زر Report Issue المخصص في الترويسة فتح نافذة الإبلاغ في Blipit.
تطبيق Next.js: زر Report Issue المخصص في الترويسة فتح نافذة الإبلاغ في Blipit.

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

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

app/layout.tsx
<Blipit publicKey={process.env.NEXT_PUBLIC_BLIPIT_KEY!} feedbackWidget={false} />

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

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

app/blipit-user.tsx
"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، أو زرًا يرمي خطأ، وانقر عليه: يظهر الحدث ضمن «المشكلات» خلال ثوانٍ.

tsx
"use client";
import { captureMessage } from "@blipit/nextjs";

export function TestBlipit() {
  return <button onClick={() => captureMessage("Hello from Next.js")}>Send a test event</button>;
}

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

  • افتح وحدة تحكم المتصفح وابحث عن الأسطر التي تبدأ بـ [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] من وحدة التحكم.

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

  • 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.