اندروید

ارورا بدون هیچ تغییری با SDK رسمی Sentry برای اندروید و پلاگین Gradle آن کار می‌کند. SDK کرش‌های جاوا/کاتلین، کرش‌های نیتیو (NDK) و ANRها را گزارش می‌دهد؛ پلاگین Gradle هم فایل‌هایی را بارگذاری می‌کند که ارورا برای برگرداندن ردپای مبهم‌شده یا نیتیو به کد شما لازم دارد.

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

نصب

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

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

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

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

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

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

SDK خودش را از روی AndroidManifest.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 صدا بزنید:

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

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`	کارایی: تراکنش شروع برنامه، اکتیویتی و فرگمنت، اسپن‌های HTTP
`profilesSampleRate`	پروفایلینگ تراکنش‌های نمونه‌برداری‌شده (ردپای متد ART)
`isAttachScreenshot`	اسکرین‌شاتی که همراه هر خطا ذخیره و در صفحهٔ خطا پیش‌نمایش می‌شود
`isAttachViewHierarchy`	درخت ویوها در لحظهٔ خطا، که در صفحهٔ خطا به شکل درخت نمایش داده می‌شود
`sessionReplay.*SampleRate`	بازپخش نشست موبایل
`isAnrEnabled`	ANRها مثل خطای معمولی می‌رسند و مثل هر خطای دیگری گروه می‌شوند و هشدار می‌دهند؛ نرخ ANR هم از همین‌ها حساب می‌شود
`isEnableAutoSessionTracking`	نشست‌ها برای سلامت نسخه — پیش‌فرض روشن

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

اسکرین‌شات‌ها و سلسله‌مراتب ویوها پیوست هستند: همراه رویدادشان ذخیره می‌شوند، از نگهداری دادهی سازمان پیروی می‌کنند و اگر رویداد نمونه‌برداری یا با سقف جهش کنار گذاشته شود، همراه آن حذف می‌شوند.

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

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

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

// 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 یک توکن دسترسی شخصی ارورا (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 با همان چهار تنظیم استفاده کنید:

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 بسازید (تا هم مینیفای و هم بارگذاری اجرا شوند) و بعد:

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` کرشی نمی‌رسد	کرش‌ها در اجرای بعدی فرستاده می‌شوند — برنامه را دوباره باز کنید

نصب​

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

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

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

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

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

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

بررسی نهایی​

عیب‌یابی​

نصب