> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerix.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS (Swift) — تتبع الأخطاء

> أبلغ عن الأخطاء والتقط الأعطال (crashes) تلقائياً من تطبيق iOS الأصلي (native) إلى لوحة تحكم Lerix.

## مقدمة

يلتقط Lerix الأخطاء والأعطال من تطبيق iOS الأصلي (native) الخاص بك لتتمكّن من تصحيح المشاكل بشكل أسرع. بعد إتمام [تثبيت iOS](/ar/frameworks/ios/installation)، استخدم `Lerix.throwError` لإرسال أخطاء مخصّصة أو استثناءات ملتقطة إلى لوحة التحكم — أما الأعطال غير الملتقطة فتُلتقط تلقائياً، دون الحاجة لأي كود إضافي.

<Note>
  تأكّد من تهيئة الـ SDK عبر `Lerix.initialize()` قبل الإبلاغ عن الأخطاء.
</Note>

## الإبلاغ عن خطأ

استخدم `Lerix.throwError` للإبلاغ عن خطأ يدوياً. هذا مفيد عندما تلتقط خطأً بنفسك وتريد إرساله إلى Lerix مع سياق إضافي.

```swift theme={"dark"}
do {
    try riskyOperation()
} catch {
    Lerix.throwError(
        "\(error)",
        stack: Thread.callStackSymbols,
        type: .runtimeError,
        severity: .high,
        metadata: ["userId": "123", "action": "payment", "amount": 100]
    )
}
```

### المعاملات (Parameters)

| المعامل | النوع | مطلوب | الوصف |
| - | - | - | - |
| `issue` | `String` | نعم | رسالة الخطأ أو وصفه |
| `stack` | `[String]` | لا | أطر تتبّع المكدس (Stack trace) — مرّر `Thread.callStackSymbols` للحصول على المكدس الحالي |
| `type` | `BugType` | لا | تصنيف نوع الخطأ (الافتراضي: `.runtimeError`) |
| `severity` | `BugSeverity` | لا | مستوى الخطورة (الافتراضي: `.medium`) |
| `metadata` | `[String: Any]?` | لا | سياق إضافي يُرفق بالتقرير |

### قيم `BugType`

| القيمة | الوصف |
| - | - |
| `runtimeError` | استثناء غير معالَج يُرمى أثناء التشغيل |
| `logicBug` | سلوك غير صحيح لا يرمي استثناءً |
| `uiBug` | خلل بصري أو في التخطيط (layout) |
| `networkError` | طلب شبكة فاشل أو مُشوَّه |
| `performance` | بطء، تقطّع (jank)، أو استهلاك موارد مفرط |
| `compatibility` | خلل يظهر على جهاز أو إصدار نظام أو منصة محدّدة |
| `validationError` | إدخال غير صالح تجاوز التحقق رغم أنه لا ينبغي |
| `security` | خلل متعلّق بالأمان |
| `crash` | توقّف التطبيق بشكل غير متوقّع |
| `unknown` | لا شيء مما سبق |

### قيم `BugSeverity`

| القيمة | الوصف |
| - | - |
| `critical` | يعطّل وظيفة أساسية أو يؤثّر على جميع المستخدمين |
| `high` | تأثير كبير، لكن يوجد حل بديل (workaround) |
| `medium` | ملحوظ لكن تأثيره محدود |
| `low` | بسيط أو شكلي |
| `unknown` | لم يتم تقييم الخطورة بعد |

## الالتقاط التلقائي للأعطال

يُثبّت `Lerix.initialize()` معالج أعطال (crash handler) تلقائياً، ويغطّي كلاً من:

* **الاستثناءات غير الملتقطة** (`NSException` — مثل استدعاء selector غير مُنفَّذ، أو عملية غير صالحة على مجموعة بيانات).
* **الإشارات القاتلة (fatal signals)** (`SIGABRT`، `SIGILL`، `SIGSEGV`، `SIGFPE`، `SIGBUS`، `SIGTRAP`) — وهذا ما يلتقط أعطال Swift الشائعة أثناء التشغيل: فكّ التغليف الإجباري (force-unwrap) لقيمة `nil`، أو تجاوز فهرس مصفوفة، أو فشل `precondition`، وما شابه.

لا يمكن للعطل إجراء استدعاء شبكة بشكل موثوق — فالعملية (process) تكون بصدد الإنهاء — لذا يُكتب التقرير إلى القرص بشكل متزامن (synchronous) لحظة العطل، ثم يُرسَل تلقائياً في *المرة التالية* لتشغيل تطبيقك، مصنَّفاً كـ `type: .crash, severity: .critical`. لا تحتاج لفعل أي شيء لاستلامه؛ سيظهر في لوحة التحكم عند التشغيل التالي.

لتعطيل هذه الميزة (مثلاً إذا كان تطبيقك يملك بالفعل نظام تتبع أعطال خاصاً به وتريد فقط استدعاءات `throwError` اليدوية):

```swift theme={"dark"}
Lerix.initialize(
    apiKey: "your-api-key",
    projectId: "your-project-id",
    enableCrashReporting: false
)
```

<Note>
  يتم ترميز أسماء الدوال في تتبّع المكدس (symbolication) باستخدام رموز التصحيح (debug symbols) الخاصة بالتطبيق نفسه لحظة العطل، لذا قد يُظهر إصدار Release الذي أُزيلت منه هذه الرموز عناوين ذاكرة بدلاً من أسماء الدوال في بعض الأطر — هذه خاصية طبيعية للإبلاغ الأصلي (native) عن الأعطال، وليست خللاً في الـ SDK.
</Note>

### تحقّق من التكامل

أرسل خطأً تجريبياً للتأكّد من أن كل شيء يعمل:

```swift theme={"dark"}
Lerix.throwError("Test error", stack: Thread.callStackSymbols)
```

ثم افتح [لوحة التحكم](https://app.lerix.dev) — يجب أن يظهر الخطأ خلال ثوانٍ.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.