iOS وAndroid وFlutter وReact Native

التثبيت one package per platform

لكل منصة حزمة Blipit تأخذ المفتاح العام ومعرّف المشروع، وكلها مبنية على نواة Blipit الخاصة دون أي مكتبة أعطال من طرف ثالث: blipit-android v0.7.5 وblipit-swift 0.8.0 و@blipit/react-native 0.6.3 وblipit_flutter 0.5.3. يُبلّغ عن الأعطال وحالات ANR والتجمّد والاستثناءات غير الملتقطة تلقائيًا، فتُكتب على القرص أولًا وتُرسل عند التشغيل التالي، ويحتفظ طابور غير متصل بالتقارير حتى تعود الشبكة. احتفظ برموز التصحيح لأعطال الكود الأصلي، لأن ملفات الرموز لا تُقرأ بعد.

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

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

2React Native

تربط الحزمة وحدة أصلية صغيرة تشغّل حزم Blipit الخاصة لأندرويد وiOS لالتقاط الأعطال الأصلية؛ ويضيف ملف Gradle الخاص بها مستودع JitPack تلقائيًا. غلّف المكوّن الجذري حتى يُبلَّغ عن أخطاء العرض أيضًا.

sh
npm install @blipit/react-native
npx pod-install
tsx
import * as Blipit from "@blipit/react-native";

Blipit.init({ key: "<public key>", project: <project id>, environment: "production", release: "myapp@1.4.2" });

export default Blipit.wrap(App);

3Flutter

استبدل runApp في main.dart بـ Blipit.init. تشغّل الإضافة حزم Blipit الخاصة لأندرويد وiOS لالتقاط الأعطال الأصلية، ويُبلَّغ عن أخطاء إطار Flutter والأخطاء غير المتزامنة غير الملتقطة تلقائيًا.

sh
flutter pub add blipit_flutter
main.dart
import 'package:blipit_flutter/blipit_flutter.dart';

Future<void> main() async {
  await Blipit.init(
    key: '<public key>',
    project: <project id>,
    environment: 'production',
    release: 'myapp@1.4.2',
    appRunner: () => runApp(const MyApp()),
  );
}

4iOS وmacOS ‏(Swift Package)

في Xcode، اختر File ثم Add Package Dependencies، وأدخل رابط المستودع؛ أو أضفه إلى Package.swift وأضف BlipitSwift إلى الهدف. مع CocoaPods، استخدم pod باسم BlipitSwift. ثم استدعِ start مرة واحدة عند التشغيل. إذا كان المفتاح أو معرّف المشروع فارغًا، يطبع start تحذيرًا ويعيد false بدل إيقاف التطبيق.

Package.swift
.package(url: "https://github.com/blipit-io/blipit-swift", from: "0.8.0")
Podfile
pod "BlipitSwift", "~> 0.8.0"
swift
import BlipitSwift

Blipit.start(key: "<public key>", project: "<project id>", environment: "production", release: "myapp@1.4.2")

5Android

أضف JitPack إلى المستودعات في settings.gradle.kts، والاعتمادية إلى وحدة التطبيق، واستدعِ init في Application.onCreate.

settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")
    }
}
‎build.gradle.kts (app)‎
implementation("com.github.blipit-io:blipit-android:v0.7.5")
kotlin
import io.blipit.android.Blipit

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        Blipit.init(this) {
            key = "<public key>"
            project = "<project id>"
            environment = "production"
            release = "myapp@1.4.2"
        }
    }
}

6أين يوضع المفتاح في التطبيق

تتضمن التطبيقات المفتاح العام ومعرّف المشروع داخلها، ولا بأس بذلك: فالمفتاح العام لا يستطيع سوى إرسال الأحداث. لا تضع المفتاح السري في تطبيق أبدًا. مرّرهما وقت البناء حتى يبقيا خارج مستودعك.

Flutter
flutter run --dart-define=BLIPIT_KEY=blipit_pk_your_public_key --dart-define=BLIPIT_PROJECT=12
main.dart
const key = String.fromEnvironment('BLIPIT_KEY');
const project = int.fromEnvironment('BLIPIT_PROJECT');
Expo (.env)
EXPO_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
EXPO_PUBLIC_BLIPIT_PROJECT=12
Android build.gradle.kts
buildConfigField("String", "BLIPIT_KEY", "\"${project.findProperty("blipitKey")}\"")
iOS xcconfig
BLIPIT_KEY = blipit_pk_your_public_key

7بلاغات الأخطاء في التطبيقات

استدعِ showReport من عنصر قائمة في تطبيقك، أو فعّل زر الإبلاغ عن خطأ العائم. تسأل أداة الإبلاغ أولًا عن طريقة عرض المشكلة: التقاط لقطة شاشة، أو تسجيل الشاشة (iOS)، أو وصفها فقط. تُفتح لقطة الشاشة بملء الشاشة والأدوات فوقها وتحتها وليس عليها أبدًا؛ كبّر بإصبعين أو بنقرتين، وحدّد المشكلة، ثم أضف عنوانًا وما حدث وأرسل. تصل البلاغات إلى قسم بلاغات الأخطاء مع تفاصيل الجهاز. يحتاج React Native إلى react-native-view-shot لالتقاط لقطات الشاشة.

React Native
import * as Blipit from "@blipit/react-native";

export default function Root() {
  return (
    <Blipit.BlipitReporter showButton>
      <App />
    </Blipit.BlipitReporter>
  );
}

Blipit.showReport();
Flutter
appRunner: () => runApp(const BlipitReporter(showButton: true, child: MyApp())),

Blipit.showReport();
iOS
Blipit.showReportButton()

Blipit.showReport()
Android
Blipit.showReportButton()

Blipit.showReport()

8أبلغ من الشاشة التي فيها الخطأ

عنصر الإبلاغ عن خطأ في قائمة مثل الملف الشخصي يلتقط القائمة لا المشكلة. فعّل الطرق التي تبدأ من الشاشة نفسها؛ كلها متوقفة افتراضيًا ولا تطلب أي إذن. يفتح shakeToReport نموذج البلاغ عند هزّ الهاتف. يسأل screenshotToReport "هل تريد الإبلاغ عن خطأ في هذه الشاشة؟" بعد لقطة شاشة عادية ويرفق لقطة Blipit الخاصة (iOS وAndroid 14 وما بعده). يفتحه twoFingerReport بعد الضغط المطوّل بإصبعين لنحو ثانية دون أن يعيق لمسات التطبيق. يسأل reportAfterCrash عمّا كان الشخص يفعله عند أول تشغيل بعد العطل ويربط البلاغ بذلك العطل. يتيح screenPicker، المفعّل افتراضيًا، لمن يفتح نموذج البلاغ من قائمة أن يختار أي شاشة من الشاشات الأخيرة فيها الخطأ: تبقى اللقطات في ذاكرة الجهاز ولا يُرفع إلا ما يختاره. تسمّي تطبيقات Jetpack Compose وSwiftUI شاشاتها عبر setScreen.

Android
Blipit.init(this) {
    key = "<public key>"
    project = "<project id>"
    shakeToReport = true
    screenshotToReport = true
    twoFingerReport = true
    reportAfterCrash = true
}

navController.addOnDestinationChangedListener { _, destination, _ ->
    Blipit.setScreen(destination.route ?: "screen")
}
iOS
Blipit.start(key: "<public key>", project: "<project id>") { options in
    options.shakeToReport = true
    options.screenshotToReport = true
    options.twoFingerReport = true
    options.reportAfterCrash = true
}

CartView().onAppear { Blipit.setScreen("Cart") }
React Native
Blipit.init({
  key: "<public key>",
  project: <project id>,
  shakeToReport: true,
  screenshotToReport: true,
  twoFingerReport: true,
  reportAfterCrash: true,
});

<NavigationContainer ref={navigation} onReady={() => Blipit.trackNavigation(navigation)}>
Flutter
await Blipit.init(
  key: '<public key>',
  project: <project id>,
  shakeToReport: true,
  screenshotToReport: true,
  twoFingerReport: true,
  reportAfterCrash: true,
  appRunner: () => runApp(BlipitReporter(child: MaterialApp(navigatorObservers: [BlipitNavigatorObserver()], home: const Home()))),
);

9زر عائم للمختبرين فقط

في app.blipit.io افتح المشروع، ومن إعدادات زر الإبلاغ عن الأخطاء اضبط الزر العائم في تطبيقات الهاتف على الجميع أو المختبرين فقط، مع معرّف مستخدم أو بريد إلكتروني لكل مختبر. يرسل التطبيق الشخص الذي حدده عبر setUser ولا يجيب Blipit إلا بنعم أو لا، فلا تُشحن قائمة المختبرين داخل التطبيق أبدًا. استدعاء showReportButton (أو showButton في React Native وFlutter) يظل يُظهر الزر للجميع.

Android
Blipit.setUser(id = user.id, email = user.email)
iOS
Blipit.setUser(id: user.id, email: user.email)
React Native
Blipit.setUser({ id: user.id, email: user.email });
Flutter
Blipit.setUser(BlipitUser(id: user.id, email: user.email));

10رصد التطبيق عندما يتوقف

بعض الأعطال لا تسبب انهيارًا أبدًا: تبقى شاشة البدء تدور، أو لا يعود تسجيل الدخول. فعّل waitForReady واستدعِ reportReady عند ظهور أول شاشة قابلة للاستخدام. ضع المسارات مثل تسجيل الدخول بين startFlow وendFlow، وحدّد الخطوات باستخدام flowStep. إذا لم يكتمل أحدها في الوقت المحدد، يفتح Blipit مشكلة من نوع متوقف مع آخر خطوة والمسار الذي سبقها. يُحتسب الوقت على الشاشة فقط، وBlipit هو من يحدد المهل. تُرسل الأسماء كما كُتبت، لذا استخدم أسماء ثابتة، ولا تستخدم أبدًا عناوين البريد أو أي بيانات للمستخدم.

Android
Blipit.init(this) {
    key = "<public key>"
    project = "<project id>"
    waitForReady = true
}

Blipit.reportReady()

Blipit.startFlow("sign-in")
Blipit.flowStep("sign-in", "google-picker")
Blipit.endFlow("sign-in")
iOS
Blipit.start(key: "<public key>", project: "<project id>", waitForReady: true)

Blipit.reportReady()

Blipit.startFlow("sign-in")
Blipit.flowStep("sign-in", "apple-sheet")
Blipit.endFlow("sign-in")
React Native
Blipit.init({ key: "<public key>", project: <project id>, waitForReady: true });

Blipit.reportReady();

Blipit.startFlow("sign-in");
Blipit.flowStep("sign-in", "google-picker");
Blipit.endFlow("sign-in");
Flutter
await Blipit.init(key: '<public key>', project: <project id>, waitForReady: true, appRunner: () => runApp(const MyApp()));

Blipit.reportReady();

Blipit.startFlow('sign-in');
Blipit.flowStep('sign-in', 'google-picker');
Blipit.endFlow('sign-in');

11تحقق من أنه يعمل

افتح المشكلات في app.blipit.io. يظهر الحدث الأول خلال بضع ثوانٍ، مجمّعًا في مشكلة، ويتلقى المسؤولون بريدًا إلكترونيًا.

React Native
Blipit.captureMessage("Hello from React Native");
Flutter
await Blipit.captureMessage('Hello from Flutter');
iOS
Blipit.captureMessage("Hello from iOS")
Android
Blipit.captureMessage("Hello from Android")

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

  • الالتقاط اليدوي على كل منصة: captureException وcaptureMessage وsetUser وsetTag وaddBreadcrumb وcaptureSecurity لمحاولات تسجيل الدخول.
  • Expo: شغّل npx expo prebuild أو استخدم نسخة تطوير. لا يحتوي Expo Go على كود أصلي مخصص، لذا يُبلَّغ فيه عن أخطاء JavaScript لكن ليس عن الأعطال الأصلية.
  • ترقية React Native من 0.4: أزِل حزمة المراقبة من الطرف الثالث التي ثبّتها 0.4 معها وأزِل إضافة إعداد Expo الخاصة بها؛ وأُزيلت dsn() وwithIdentity(). Flutter من 0.3: أزِل تلك الحزمة من pubspec.yaml أيضًا؛ أصبح نوعا المستوى والمستخدم BlipitLevel وBlipitUser، وتعيد دوال الالتقاط معرّف الحدث كـ String?، وأُزيلت Blipit.dsn وBlipit.configure ودالة options: في init. في الحالتين، يُقبل tracesSampleRate لكن تتبعات الأداء لا تُرسل في هذا الإصدار.
  • ترقية أندرويد إلى v0.5.0 وiOS إلى 0.5.0: معظم التطبيقات تكتفي برفع رقم الإصدار. تعيد دوال الالتقاط معرّف الحدث كسلسلة نصية، ونوع المستوى هو Level الخاص بـ Blipit، وأُزيلت Blipit.dsn. في أندرويد، أُزيلت configure وapply وأصبح وسم إخفاء التسجيل blipit-mask. في iOS، أصبح Options صنفًا خاصًا بـ Blipit وتعمل beforeSend على الحدث كقاموس.
  • مراجعة المتاجر لطرق الإبلاغ: لا يوجد طلب إذن جديد. يستخدم iOS أحداث الهزّ في UIKit (لا CoreMotion) وإشعار لقطة الشاشة، فلا يحتاج بيان الخصوصية إلى أي إدخال جديد. على Android 14 وما بعده يعلن SDK عن DETECT_SCREEN_CAPTURE، وهو إذن عادي يُمنح عند التثبيت؛ وفي قسم أمان البيانات في Google Play لا يُجمع أي شيء جديد، لأن Blipit يعرف فقط أن لقطة شاشة التُقطت ولا يقرؤها ولا يقرأ المعرض أبدًا. إصدارات Android الأقدم تتخطى الإبلاغ بلقطة الشاشة. وتعمل إصدارات Huawei AppGallery بالطريقة نفسها دون خدمات Google Play.
  • تحقق من الإصدار المثبّت باستخدام npm ls @blipit/react-native (أو pnpm list @blipit/react-native). ينتظر pnpm 11 يومًا قبل أن يثبّت إصدارًا جديدًا (minimum-release-age)، لذلك يثبّت pnpm add في يوم الإصدار الإصدار السابق دون أي تنبيه؛ للحصول على الإصدار الجديد فورًا شغّل pnpm add @blipit/react-native@<version> --config.minimum-release-age=0.
  • إبقاء 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.