# اندروید

> https://docs.errora.org/platforms/android

ارورا بدون هیچ تغییری با [SDK رسمی Sentry برای اندروید](https://docs.sentry.io/platforms/android/)
و پلاگین Gradle آن کار می‌کند. SDK کرش‌های جاوا/کاتلین، کرش‌های نیتیو (NDK) و ANRها را گزارش
می‌دهد؛ پلاگین Gradle هم فایل‌هایی را بارگذاری می‌کند که ارورا برای برگرداندن ردپای مبهم‌شده یا
نیتیو به کد شما لازم دارد.

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

## نصب

راه پیشنهادی پلاگین Gradle است؛ SDK را خودش اضافه می‌کند و در هر بیلد انتشار، نگاشت و سیمبل‌ها
را بارگذاری می‌کند:

```kotlin
// app/build.gradle.kts
plugins {
    id("com.android.application")
    id("io.sentry.android.gradle") version "5.+"   // در بیلد واقعی نسخهٔ دقیق را پین کنید
}
```

بدون پلاگین، SDK را خودتان اضافه کنید (گزارش کرش NDK را هم در خود دارد):

```kotlin
dependencies {
    implementation("io.sentry:sentry-android:8.+")
}
```

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

### روش ۱ — فایل مانیفست

SDK خودش را از روی `AndroidManifest.xml` مقداردهی می‌کند:

```xml
<application>
    <meta-data android:name="io.sentry.dsn"
               android:value="https://<public_key>@<your-errora-host>/<project_id>" />
    <meta-data android:name="io.sentry.traces.sample-rate" android:value="0.2" />
    <meta-data android:name="io.sentry.attach-screenshot" android:value="true" />
    <meta-data android:name="io.sentry.attach-view-hierarchy" android:value="true" />
    <meta-data android:name="io.sentry.session-replay.on-error-sample-rate" android:value="1.0" />
    <meta-data android:name="io.sentry.session-replay.session-sample-rate" android:value="0.1" />
</application>
```

### روش ۲ — داخل کد

مقداردهی خودکار را در مانیفست خاموش کنید و بعد `SentryAndroid.init` را از کلاس `Application`
صدا بزنید:

```xml
<meta-data android:name="io.sentry.auto-init" android:value="false" />
```

```kotlin
import io.sentry.android.core.SentryAndroid

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        SentryAndroid.init(this) { options ->
            options.dsn = "https://<public_key>@<your-errora-host>/<project_id>"
            options.environment = "production"

            options.tracesSampleRate = 0.2          // ردیابی کارایی
            options.profilesSampleRate = 1.0        // پروفایلینگ (از تراکنش‌های نمونه‌برداری‌شده)

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

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

            options.isAnrEnabled = true             // پیش‌فرض: روشن
            options.isEnableAutoSessionTracking = true  // پیش‌فرض: روشن — خوراک سلامت نسخه
        }
    }
}
```

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

| گزینه | چه چیزی در ارورا می‌گیرید |
| --- | --- |
| `tracesSampleRate` | [کارایی](/products/performance): تراکنش شروع برنامه، اکتیویتی و فرگمنت، اسپن‌های HTTP |
| `profilesSampleRate` | [پروفایلینگ](/products/profiling) تراکنش‌های نمونه‌برداری‌شده (ردپای متد ART) |
| `isAttachScreenshot` | اسکرین‌شاتی که همراه هر خطا ذخیره و در صفحهٔ خطا پیش‌نمایش می‌شود |
| `isAttachViewHierarchy` | درخت ویوها در لحظهٔ خطا، که در صفحهٔ خطا به شکل درخت نمایش داده می‌شود |
| `sessionReplay.*SampleRate` | [بازپخش نشست موبایل](/products/session-replay#بازپخش-موبایل) |
| `isAnrEnabled` | ANRها مثل خطای معمولی می‌رسند و مثل هر خطای دیگری گروه می‌شوند و هشدار می‌دهند؛ نرخ ANR هم از همین‌ها حساب می‌شود |
| `isEnableAutoSessionTracking` | نشست‌ها برای [سلامت نسخه](/products/release-health) — پیش‌فرض روشن |

لازم نیست `release` را تعیین کنید: SDK خودش آن را `<package>@<versionName>+<versionCode>`
می‌گذارد و سلامت نسخه و تطبیق فایل‌های دیباگ روی همین رشته کار می‌کنند.

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

## بارگذاری نگاشت ProGuard/R8 و سیمبل‌های NDK

بیلد انتشارِ مینیفای‌شده فریم‌هایی مثل `a.b.c.d(SourceFile)` گزارش می‌دهد و کرش نیتیو فقط
آدرس. ارورا با فایل‌هایی که بارگذاری می‌کنید، **پیش از گروه‌بندی** آن‌ها را رمزگشایی و نمادگشایی
می‌کند — نحوهٔ تطبیق را در [فایل‌های دیباگ](/products/debug-files) ببینید.

پلاگین Gradle را به ارورا وصل کنید:

```kotlin
// app/build.gradle.kts
sentry {
    url.set("https://<your-errora-host>")
    org.set("<organization-slug>")
    projectName.set("<project-slug>")
    authToken.set(System.getenv("SENTRY_AUTH_TOKEN"))   // errora_pat_…

    includeProguardMapping.set(true)       // فایل mapping.txt از ProGuard/R8
    autoUploadProguardMapping.set(true)    // بارگذاری آن در حین بیلد
    uploadNativeSymbols.set(true)          // سیمبل‌های دیباگ .so در NDK
    includeNativeSources.set(false)

    telemetry.set(false)                   // تله‌متری بیلد به sentry.io فرستاده نشود
}
```

- `authToken` یک [توکن دسترسی شخصی](/account/tokens) ارورا (`errora_pat_…`) است که صاحبش در
  سازمان نقش **member** یا بالاتر دارد. آن را در مخزن اسرار CI نگه دارید، نه داخل مخزن کد.
- `org` شناسهٔ متنی (slug) سازمان است که در آدرس داشبورد می‌بینید (`/organizations/<slug>/…`)؛
  `projectName` هم شناسهٔ متنی پروژه است.
- اگر ترجیح می‌دهید بلوک را خالی بگذارید، پلاگین فایل `sentry.properties` و متغیرهای محیطی
  `SENTRY_URL`، `SENTRY_ORG`، `SENTRY_PROJECT` و `SENTRY_AUTH_TOKEN` را هم می‌خواند.

پلاگین روی هر بیلد یک UUID پروگارد می‌زند که SDK گزارشش می‌کند؛ پس هر کرش با نگاشت همان بیلدی
رمزگشایی می‌شود که آن را ساخته. آنچه رسیده را در **تنظیمات ← فایل‌های دیباگ** ببینید.

### بدون پلاگین Gradle

از `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>

sentry-cli upload-proguard --uuid <uuid> app/build/outputs/mapping/release/mapping.txt
sentry-cli debug-files upload app/build/intermediates/merged_native_libs/release/
```

مقدار `--uuid` باید همان UUID پروگاردی باشد که برنامه گزارش می‌کند — و برای همین پلاگین راه
ساده‌تری است.

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

یک نسخهٔ **release** بسازید (تا هم مینیفای و هم بارگذاری اجرا شوند) و بعد:

```kotlin
Sentry.captureException(RuntimeException("Errora smoke test"))
// یا یک کرش واقعی:
throw RuntimeException("Errora crash test")
```

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

## عیب‌یابی

| نشانه | علت / راه‌حل |
| --- | --- |
| فریم‌ها هنوز شبیه `a.b.c` هستند | نگاشت آن بیلد بارگذاری نشده — خروجی Gradle و **فایل‌های دیباگ** را بررسی کنید |
| فریم‌های نیتیو فقط آدرس دارند | سیمبل‌های NDK را بارگذاری کنید (`uploadNativeSymbols`)، آن هم از فایل‌های `.so` **strip‌نشده** |
| بارگذاری با `401` شکست می‌خورد | توکن اشتباه یا باطل‌شده است، یا `url` هنوز به sentry.io اشاره می‌کند |
| بارگذاری با `403` شکست می‌خورد | صاحب توکن عضو آن سازمان نیست |
| دادهٔ سلامت نسخه نمی‌آید | ردیابی خودکار نشست خاموش شده است |
| بعد از `throw` کرشی نمی‌رسد | کرش‌ها در اجرای **بعدی** فرستاده می‌شوند — برنامه را دوباره باز کنید |