سفارشی‌سازی گزارش‌های خرابی برای 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 گزارش‌ها را با داده‌های خرابی شما مرتبط می‌کند و وقتی جزئیات مشکلی را مشاهده می‌کنید، آن‌ها را در برگه گزارش‌ها نمایش می‌دهد (همه مشکلاتتان را در داشبورد Crashlytics DevOps و تعامل > در کنسول 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) افزودن فراداده به گزارش‌های خرابی NDK

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

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

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

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

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

در داشبورد Crashlytics در DevOps و تعامل در کنسول 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 ببینید).

Analytics SDK به‌طور خودکار رویداد 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 و اطلاع‌رسانی به شما درباره اینکه آیا مشکل شما بخشی از یک روند بزرگ‌تر است یا نه، به شما کمک می‌کند مشکلات را حل کنید. برای بسیاری از مشکلات، «اطلاعات آماری خرابی» حتی منابعی را برای کمک به اشکال‌زدایی خرابی ارائه می‌دهد.

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

مراحل بعدی