# iOS

> https://docs.errora.org/platforms/apple-ios

ارورا بدون هیچ تغییری با [SDK رسمی Sentry برای Cocoa](https://docs.sentry.io/platforms/apple/guides/ios/)
کار می‌کند. SDK کرش‌ها را روی خود دستگاه ثبت می‌کند، هنگ برنامه و خاتمهٔ اجباری watchdog را گزارش
می‌دهد و `sentry-cli` فایل‌های dSYM را بارگذاری می‌کند تا ارورا آدرس‌های کرش را به نام تابع، فایل
و خط تبدیل کند.

پروژه را با پلتفرم **iOS** بسازید تا پنل نمونه‌کدهای درست را نشان دهد.

## نصب

**Swift Package Manager** — در Xcode از منوی *File → Add Package Dependencies…* این آدرس را
اضافه کنید:

```text
https://github.com/getsentry/sentry-cocoa
```

**CocoaPods:**

```ruby
# Podfile
pod 'Sentry'
```

## مقداردهی اولیه

SDK را هرچه زودتر شروع کنید — در `application(_:didFinishLaunchingWithOptions:)` یا در
`init()` مربوط به `App` در SwiftUI:

```swift
import Sentry

SentrySDK.start { options in
    options.dsn = "https://<public_key>@<your-errora-host>/<project_id>"
    options.environment = "production"

    options.tracesSampleRate = 0.2             // ردیابی کارایی

    options.configureProfiling = {             // پروفایلینگ
        $0.sessionSampleRate = 1.0
        $0.lifecycle = .trace
    }

    options.attachScreenshot = true            // اسکرین‌شات هنگام خطا
    options.attachViewHierarchy = true         // سلسله‌مراتب ویوها هنگام خطا

    options.sessionReplay.onErrorSampleRate = 1.0
    options.sessionReplay.sessionSampleRate = 0.1

    options.enableAppHangTracking = true       // پیش‌فرض: روشن
    options.appHangTimeoutInterval = 2         // ثانیه
}
```

نسخه‌های قدیمی‌تر SDK به‌جای `configureProfiling` از `options.profilesSampleRate = 1.0`
استفاده می‌کنند؛ ارورا خروجی هر دو را می‌پذیرد.

## گزینه‌هایی که ارزش روشن‌کردن دارند

| گزینه | چه چیزی در ارورا می‌گیرید |
| --- | --- |
| `tracesSampleRate` | [کارایی](/products/performance): شروع برنامه، UIViewController و اسپن‌های شبکه |
| `configureProfiling` / `profilesSampleRate` | [پروفایلینگ](/products/profiling)، نمادگشایی‌شده با dSYMهای شما |
| `attachScreenshot` | اسکرین‌شاتی که همراه هر خطا ذخیره و در صفحهٔ خطا پیش‌نمایش می‌شود |
| `attachViewHierarchy` | درخت ویوها در لحظهٔ خطا، که در صفحهٔ خطا به شکل درخت نمایش داده می‌شود |
| `sessionReplay.*SampleRate` | [بازپخش نشست موبایل](/products/session-replay#بازپخش-موبایل) |
| `enableAppHangTracking` | هنگ‌های برنامه مثل خطای معمولی می‌رسند و مثل هر خطای دیگری گروه می‌شوند و هشدار می‌دهند |
| `enableAutoSessionTracking` | نشست‌ها برای [سلامت نسخه](/products/release-health) — پیش‌فرض روشن |

لازم نیست نسخه (release) را تعیین کنید: SDK خودش `<bundleId>@<version>+<build>` را می‌گذارد و
سلامت نسخه روی همین رشته کار می‌کند.

اسکرین‌شات‌ها، سلسله‌مراتب ویوها و گزارش‌های کرش اپل [پیوست](/products/issues#پیوستها)
هستند: همراه رویدادشان ذخیره می‌شوند، به اندازهٔ [نگهداری داده](/account/retention)ی سازمان
می‌مانند و اگر رویداد نمونه‌برداری یا با سقف جهش کنار گذاشته شود، همراه آن حذف می‌شوند.

## بارگذاری dSYM

گزارش کرش فقط آدرس دستورالعمل‌ها را دارد. ارورا **پیش از گروه‌بندی** آن‌ها را با dSYMی نمادگشایی
می‌کند که شناسهٔ دیباگش (UUID فایل Mach-O) با هر ایمیج بارگذاری‌شده جور باشد — نگاه کنید به
[فایل‌های دیباگ](/products/debug-files).

### ۱. تولید dSYM

در **Build Settings** تارگت، **Debug Information Format** را روی **DWARF with dSYM File**
بگذارید — دست‌کم برای پیکربندی Release.

### ۲. تنظیم sentry-cli

`sentry-cli` را نصب کنید (`brew install getsentry/tools/sentry-cli`) و آدرس ارورا را به آن
بدهید. یا با متغیرهای محیطی:

```bash
export SENTRY_URL=https://<your-errora-host>
export SENTRY_AUTH_TOKEN=errora_pat_…
export SENTRY_ORG=<organization-slug>
export SENTRY_PROJECT=<project-slug>
```

…یا با یک فایل `.sentryclirc` کنار پروژه (توکن را وارد git نکنید):

```ini
[defaults]
url = https://<your-errora-host>
org = <organization-slug>
project = <project-slug>

[auth]
token = errora_pat_…
```

توکن، یک [توکن دسترسی شخصی](/account/tokens) ارورا است که صاحبش در سازمان نقش **member** یا
بالاتر دارد. شناسهٔ متنی (slug) سازمان همان است که در آدرس داشبورد می‌بینید
(`/organizations/<slug>/…`).

### ۳. افزودن فاز بیلد در Xcode

**Build Phases → + → New Run Script Phase** را بعد از *Compile Sources* اضافه کنید:

```bash
if [[ "$(uname -m)" == arm64 ]]; then
  export PATH="/opt/homebrew/bin:$PATH"
fi

if which sentry-cli >/dev/null; then
  ERROR=$(sentry-cli debug-files upload "$DWARF_DSYM_FOLDER_PATH" 2>&1 >/dev/null)
  if [ ! $? -eq 0 ]; then
    echo "warning: sentry-cli - $ERROR"
  fi
else
  echo "warning: sentry-cli not installed"
fi
```

این مسیر را به **Input Files** همین فاز اضافه کنید تا Xcode آن را بعد از ساخته‌شدن dSYM اجرا
کند (و با sandbox اسکریپت‌های کاربر هم کار کند):

```text
${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME}
```

### یا با fastlane

```ruby
lane :upload_symbols do
  sentry_debug_files_upload(
    url: "https://<your-errora-host>",
    auth_token: ENV["SENTRY_AUTH_TOKEN"],
    org_slug: "<organization-slug>",
    project_slug: "<project-slug>",
  )
end
```

آن را بعد از `build_app` (یا `gym`) اجرا کنید تا dSYMهای بیلد روی دیسک باشند.

فایل دیباگ را می‌توانید دستی و از مرورگر هم بارگذاری کنید:
**تنظیمات ← فایل‌های دیباگ**.

## بررسی نهایی

پیکربندی **Release** را بسازید، برنامه را **بدون** دیباگر متصل اجرا کنید (دیباگر کرش‌ها را
می‌بلعد) و بعد:

```swift
SentrySDK.capture(error: NSError(domain: "errora.smoke-test", code: 1))
// یا یک کرش واقعی:
SentrySDK.crash()
```

کرش در اجرای بعدی برنامه فرستاده می‌شود. صفحهٔ خطا را باز کنید: فریم‌ها باید نام تابع، فایل و خط
را نشان دهند و فریم‌های inline‌شده باز شده باشند. اگر فریمی نمادگشایی نشده، صفحهٔ خطا شناسهٔ
دیباگ گمشده و ایمیجی را که به آن تعلق دارد فهرست می‌کند.

## عیب‌یابی

| نشانه | علت / راه‌حل |
| --- | --- |
| فریم‌ها فقط آدرس دارند | dSYM آن بیلد بارگذاری نشده — لاگ بیلد و **فایل‌های دیباگ** را بررسی کنید |
| نمادهای Swift شبیه `$s7MyApp…` هستند | ایمیج ارورا Swift را با کتابخانهٔ زمان اجرای همراهش دی‌منگل می‌کند؛ ایمیج سفارشی به `libswiftCore.so` نیاز دارد — [فایل‌های دیباگ](/products/debug-files#محدودیتها) را ببینید |
| بعد از `SentrySDK.crash()` کرشی نمی‌رسد | دیباگر وصل بوده یا برنامه دوباره باز نشده |
| بارگذاری با `401` شکست می‌خورد | توکن اشتباه یا باطل‌شده است، یا `SENTRY_URL` تنظیم نشده (sentry-cli پیش‌فرض به sentry.io می‌فرستد) |
| دادهٔ سلامت نسخه نمی‌آید | `enableAutoSessionTracking` خاموش شده است |