سفارشی‌سازی گزارش‌های خرابی برای Android

انتخاب پلاتفرم: iOS+‎ Android Flutter Unity


می‌توانید روی یک مشکل کلیک کنید و گزارش رویداد مفصلی را در DevOps و تعامل > Crashlytics داشبورد کنسول Firebase دریافت کنید. می‌توانید این گزارش‌ها را سفارشی‌سازی کنید تا به شما کمک کند بهتر متوجه شوید چه اتفاقی در برنامه‌تان می‌افتد و شرایط پیرامون رویدادهای گزارش‌شده به Crashlytics چیست.

  • برنامه‌تان را ابزاربندی کنید تا کلیدهای سفارشی، پیام‌های گزارش سفارشی، و شناسه‌های کاربر را ثبت کند.

  • استثناها را به Crashlytics گزارش کنید.

  • اگر برنامه‌تان از «کیت توسعه نرم‌افزار Firebase» برای Google Analytics استفاده می‌کند، به‌طور خودکار گزارش‌های ردپای دیجیتال دریافت کنید. این گزارش‌ها به شما دیدی از کنش‌های کاربر منتهی به رویداد جمع‌آوری‌شده Crashlytics در برنامه‌تان می‌دهد.

  • گزارش خرابی خودکار را خاموش کنید و گزارش‌دهی با موافقت را برای کاربران فعال کنید. توجه داشته باشید که به‌طور پیش‌فرض، Crashlytics گزارش‌های خرابی را برای همه کاربران برنامه‌تان به‌طور خودکار جمع‌آوری می‌کند.

افزودن کلیدهای سفارشی

کلیدهای سفارشی به شما کمک می‌کنند وضعیت خاص برنامه خود را قبل‌از خرابی دریافت کنید. می‌توانید جفت‌های کلید-مقدار دلخواه را با گزارش‌های خرابی خود مرتبط کنید، سپس از کلیدهای سفارشی برای جستجو و فیلتر کردن گزارش‌های خرابی در داشبورد DevOps و تعامل > Crashlytics در کنسول Firebase استفاده کنید.

  • می‌توانید مشکلاتی را که با کلید سفارشی مطابقت دارند جستجو کنید.

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

برای تنظیم جفت‌های کلید-مقدار، از روش نمونه setCustomKey استفاده کنید. توجه داشته باشید که setCustomKey برای پارامتر value بارگذاری بیش‌ازحد شده است تا هر آرگومان اولیه یا String را بپذیرد. چند نمونه در زیر آمده است:

Kotlin 

val crashlytics = Firebase.crashlytics
crashlytics.setCustomKeys {
    key("my_string_key", "foo") // String value
    key("my_bool_key", true) // boolean value
    key("my_double_key", 1.0) // double value
    key("my_float_key", 1.0f) // float value
    key("my_int_key", 1) // int value
}

Java 

FirebaseCrashlytics crashlytics = FirebaseCrashlytics.getInstance();

crashlytics.setCustomKey("my_string_key", "foo" /* string value */);

crashlytics.setCustomKey("my_bool_key", true /* boolean value */);

crashlytics.setCustomKey("my_double_key", 1.0 /* double value */);

crashlytics.setCustomKey("my_float_key", 1.0f /* float value */);

crashlytics.setCustomKey("my_int_key", 1 /* int value */);

همچنین می‌توانید مقدار کلید موجود را با فراخوانی کلید و تنظیم آن روی مقدار متفاوت تغییر دهید. برای مثال:

Kotlin 

val crashlytics = Firebase.crashlytics
crashlytics.setCustomKeys {
    key("current_level", 3)
    key("last_UI_action", "logged_in")
}

Java 

FirebaseCrashlytics crashlytics = FirebaseCrashlytics.getInstance();

crashlytics.setCustomKey("current_level", 3);
crashlytics.setCustomKey("last_UI_action", "logged_in");

با انتقال نمونه‌ای از CustomKeysAndValues به روش نمونه setCustomKeys، جفت‌های کلید-مقدار را به‌صورت انبوه اضافه کنید:

Kotlin

برای Kotlin، عملکرد موجود ساده‌تر از استفاده از سازنده CustomKeysAndValues است.

crashlytics.setCustomKeys {
  key("str_key", "hello")
  key("bool_key", true)
  key("int_key", 1)
  key("long_key", 1L)
  key("float_key", 1.0f)
  key("double_key", 1.0)
}

Java 

CustomKeysAndValues keysAndValues = new CustomKeysAndValues.Builder()
.putString("string key", "string value")
.putString("string key 2", "string  value 2")
.putBoolean("boolean key", True)
.putBoolean("boolean key 2", False)
.putFloat("float key", 1.01)
.putFloat("float key 2", 2.02)
.build();

FirebaseCrashlytics.getInstance().setCustomKeys(keysAndValues);

افزودن پیام‌های گزارش سفارشی

برای اینکه زمینه بیشتری درباره رویدادهای منتهی به خرابی داشته باشید، می‌توانید گزارش‌های Crashlytics سفارشی به برنامه‌تان اضافه کنید. Crashlytics گزارش‌ها را با داده‌های خرابی‌تان مرتبط می‌کند و آن‌ها را در برگه گزارش‌ها وقتی جزئیات مشکلی را مشاهده می‌کنید نمایش می‌دهد (همه مشکلاتتان را در داشبورد DevOps و تعامل > Crashlytics کنسول Firebase ببینید).

از log برای کمک به شناسایی دقیق مشکلات استفاده کنید. برای مثال:

Kotlin 

Firebase.crashlytics.log("message")

Java 

FirebaseCrashlytics.getInstance().log("message");

تنظیم شناسه‌های کاربر

برای تشخیص مشکل، اغلب مفید است بدانید کدام‌یک از کاربران شما با ازکارافتادگی معینی مواجه شده‌اند. ‫Crashlytics شامل روشی برای شناسایی ناشناس کاربران در گزارش‌های خرابی شما است.

برای افزودن شناسه‌های کاربر به گزارش‌هایتان، به هر کاربر یک شناسه یکتا در قالب شماره شناسه، کد، یا مقدار درهم‌سازی‌شده اختصاص دهید:

Kotlin 

Firebase.crashlytics.setUserId("user123456789")

Java 

FirebaseCrashlytics.getInstance().setUserId("user123456789");

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

(فقط جعبه‌ابزار توسعه بومی Android) افزودن فراداده به گزارش‌های خرابی NDK

می‌توانید به‌صورت اختیاری سرایند crashlytics.h را در کد C++ خود بگنجانید تا به گزارش‌های خرابی NDK فراداده اضافه کنید، مثل کلیدهای سفارشی، گزارش‌های سفارشی، شناسه‌های کاربر. همه این گزینه‌ها در این صفحه در بالا توضیح داده شده است.

‫crashlytics.h به‌عنوان کتابخانه C++ فقط سرصفحه در مخزن GitHub «کیت توسعه نرم‌افزار Firebase Android» دردسترس است.

برای دریافت دستورالعمل‌های استفاده از NDK C++ APIs، نظرات موجود در فایل سرصفحه را بخوانید.

گزارش‌های GWP-ASan را برای اشکال‌زدایی مشکلات خرابی حافظه اضافه کنید

‫Crashlytics با جمع‌آوری گزارش‌های GWP-ASan می‌تواند به شما در اشکال‌زدایی خرابی‌های ناشی از خطاهای حافظه محلی کمک کند. این خطاهای مربوط به حافظه می‌تواند با خرابی حافظه در برنامه شما مرتبط باشد که دلیل اصلی آسیب‌پذیری‌های امنیتی برنامه است.

در داشبورد DevOps و مشارکت > Crashlytics کنسول Firebase، می‌توانید کارهای زیر را با این داده‌ها انجام دهید:

  • وقتی روی جزئیات مشکل کلیک می‌کنید، می‌توانید این داده‌ها را در زبانه جدید «ردیابی پشته‌ای حافظه» مشاهده کنید.

  • می‌توانید از سیگنال و فیلتر جدید «گزارش GWP-ASan» برای مشاهده سریع همه مشکلات این داده‌ها استفاده کنید.

اگر در برنامه‌تان ‫GWP-ASan را صریحاً فعال کنید و از کیت توسعه نرم‌افزار Crashlytics برای NDK نسخه ۱۸.۳.۶ به‌بالا (Firebase BoM نسخه ۳۱.۳.۰ به‌بالا) استفاده کنید، می‌توانید گزارش‌های حافظه GWP-ASan را دریافت کنید. می‌توانید تنظیمات GWP-ASan را بااستفاده از کد بومی نمونه در اسناد Android آزمایش کنید.

گزارش کردن استثناهای غیرمهلک

علاوه‌بر گزارش خودکار خرابی‌های برنامه، Crashlytics به شما امکان می‌دهد استثناهای غیرمهلک را ضبط کنید و آن‌ها را در زمان راه‌اندازی بعدی برنامه برایتان ارسال می‌کند.

از روش recordException برای ثبت استثناهای غیرمهلک در بلوک‌های catch برنامه استفاده کنید. برای مثال:

Kotlin 

try {
    methodThatThrows()
} catch (e: Exception) {
    Firebase.crashlytics.recordException(e)
    // handle your exception here
}

Java 

try {
    methodThatThrows();
} catch (Exception e) {
    FirebaseCrashlytics.getInstance().recordException(e);
    // handle your exception here
}

علاوه‌براین، می‌توانید کلیدهای سفارشی را نیز به استثنای غیرمهلک خاص پیوست کنید. برای مثال:

Kotlin 

try {
    methodThatThrows()
} catch (e: Exception) {
    Firebase.crashlytics.recordException(e) {
        key("string key", "string value")
        key("boolean key", true)
        key("float key", Float.MAX_VALUE)
    }
    // handle your exception here
}

Java 

try {
    methodThatThrows();
} catch (Exception e) {
    CustomKeysAndValues keysAndValues = new CustomKeysAndValues.Builder()
            .putString("string key", "string value")
            .putBoolean("boolean key", true)
            .putFloat("float key", Float.MAX_VALUE)
            .build();
    FirebaseCrashlytics.getInstance().recordException(e, keysAndValues);
    // handle your exception here
}

همه استثناهای ضبط‌شده به‌عنوان مشکلات غیرمهلک در داشبورد DevOps و تعامل > Crashlytics کنسول Firebase نشان داده می‌شوند. خلاصه مشکل شامل همه اطلاعات وضعیت است که معمولاً از خرابی‌ها دریافت می‌کنید، به‌همراه تفکیک براساس نسخه Android و دستگاه سخت‌افزاری.

‫Crashlytics استثناها را در رشته پس‌زمینه‌ای اختصاصی پردازش می‌کند تا تأثیر عملکرد بر برنامه‌تان را به‌حداقل برساند. برای کاهش ترافیک شبکه کاربران، ‫Crashlytics استثناهای ثبت‌شده را دسته‌بندی می‌کند و آن‌ها را در راه‌اندازی بعدی برنامه ارسال می‌کند.

دریافت گزارش‌های ردپای رخدادها

گزارش‌های ردیابی تعامل‌هایی را که کاربر با برنامه شما داشته است و به رویداد خرابی، غیرمهلک، یا ANR منجر شده است بهتر درک کنید. این گزارش‌ها می‌توانند هنگام تلاش برای بازتولید و اشکال‌زدایی یک مشکل مفید باشند.

گزارش‌های ردپای خرده نان با Google Analytics ارائه می‌شود، بنابراین برای دریافت گزارش‌های ردپای خرده نان، باید Google Analytics را فعال کنید برای پروژه Firebase و «کیت توسعه نرم‌افزار Firebase برای Google Analytics» را به برنامه‌تان اضافه کنید. پس‌از برآورده شدن این الزامات، گزارش‌های ردپای خرده نان به‌طور خودکار به داده‌های رویداد در برگه گزارش‌ها اضافه می‌شود وقتی جزئیات مشکلی را مشاهده می‌کنید (همه مشکلاتتان را در داشبورد DevOps و مشارکت > Crashlytics در Firebase console ببینید).

Analytics کیت توسعه نرم‌افزار به‌طور خودکار رویداد screen_view را ثبت می‌کند که باعث می‌شود گزارش‌های ردیابی فهرست صفحه‌های مشاهده‌شده قبل‌از رویداد خرابی، غیرمهلک، یا ANR را نشان دهد. گزارش ردپای screen_view حاوی پارامتر firebase_screen_class است.

گزارش‌های ردیابی همچنین با هرگونه رویداد سفارشی که به‌صورت دستی در جلسه کاربر ثبت می‌کنید، ازجمله داده‌های پارامتر رویداد، تکمیل می‌شود. این داده‌ها می‌توانند مجموعه‌ای از کنش‌های کاربر را که منجر به رویداد خرابی، غیرمهلک، یا ANR شده است نشان دهند.

توجه داشته باشید که می‌توانید جمع‌آوری و استفاده از داده‌های Google Analytics را کنترل کنید، که شامل داده‌هایی می‌شود که گزارش‌های ردپا را تکمیل می‌کنند.

فعال کردن گزارش موافقت

به‌طور پیش‌فرض، Crashlytics گزارش‌های خرابی را برای همه کاربران برنامه شما به‌طور خودکار جمع‌آوری می‌کند. برای اینکه کاربران کنترل بیشتری بر داده‌هایی که ارسال می‌کنند داشته باشند، می‌توانید با غیرفعال کردن گزارش خودکار و ارسال داده‌ها فقط به Crashlytics درصورتی‌که در کدتان انتخاب کرده باشید، گزارش موافقت را فعال کنید.

  1. در بخش application فایل AndroidManifest.xml، برچسب meta-data را برای خاموش کردن جمع‌آوری خودکار اضافه کنید:

    <meta-data
    android:name="firebase_crashlytics_collection_enabled"
    android:value="false" />

  2. با فراخوانی کردن ملغی کردن جمع‌آوری داده‌های Crashlytics در زمان اجرا، جمع‌آوری را برای کاربران منتخب فعال کنید. مقدار ملغی در همه راه‌اندازی‌های بعدی برنامه شما ماندگار است، بنابراین Crashlytics می‌تواند به‌طور خودکار گزارش‌های آن کاربر را جمع‌آوری کند.

    Kotlin 

    Firebase.crashlytics.setCrashlyticsCollectionEnabled(true)

    Java 

    FirebaseCrashlytics.getInstance().setCrashlyticsCollectionEnabled(true);

    اگر کاربر بعداً از جمع‌آوری داده انصراف دهد، می‌توانید false را به‌عنوان مقدار جایگزین ارسال کنید که در دفعه بعدی که کاربر برنامه را راه‌اندازی می‌کند اعمال خواهد شد و در همه راه‌اندازی‌های بعدی برای آن کاربر ماندگار خواهد بود.

مدیریت داده‌های «اطلاعات آماری خرابی»

«اطلاعات آماری خرابی» با مقایسه ردهای پشته ناشناس شما با ردهای پشته سایر برنامه‌های Firebase به شما کمک می‌کند مشکلات را حل کنید و به شما اطلاع می‌دهد که آیا مشکل شما بخشی از یک روند بزرگ‌تر است یا خیر. برای بسیاری از مشکلات، «اطلاعات آماری خرابی» حتی منابعی را برای کمک به اشکال‌زدایی خرابی ارائه می‌دهد.

«اطلاعات آماری خرابی» از داده‌های خرابی انبوهشی برای شناسایی گرایش‌های رایج پایداری استفاده می‌کند. اگر ترجیح می‌دهید داده‌های برنامه‌تان را هم‌رسانی نکنید، می‌توانید از منو اطلاعات آماری خرابی در بالای فهرست مشکل در داشبورد Crashlytics DevOps و تعامل در کنسول Firebase از «اطلاعات آماری خرابی» انصراف دهید.

مراحل بعدی

  • داده‌هایتان را به BigQuery یا Cloud Logging صادر کنید تا از تجزیه‌وتحلیل و ویژگی‌های پیشرفته، مثل پرسش از داده‌ها، ساختن داشبوردهای سفارشی، و راه‌اندازی هشدارهای سفارشی بهره‌مند شوید.