تخصيص تقارير أعطال Firebase Crashlytics

+iOS نظام التشغيل Android Flutter الانسجام

في لوحة بيانات Crashlytics، يمكنك النقر على مشكلة والحصول على تقرير الحدث. يمكنك تخصيص هذه التقارير لمساعدتك على فهم ما يحدث في تطبيقك والظروف المحيطة بالأحداث التي يتم الإبلاغ عنها Crashlytics

• استخدِم تطبيقك لتسجيل المفاتيح المخصّصة. رسائل السجلّ المخصَّصة ومعرّفات المستخدمين.

• إبلاغ Crashlytics عن الاستثناءات

• الحصول على سجلات شريط التنقل تلقائيًا إذا كان تطبيقك يستخدم حزمة تطوير البرامج (SDK) لمنصّة Firebase الخاصّة بخدمة "إحصاءات Google" تمنحك هذه السجلات رؤية في إجراءات المستخدمين التي أدت إلى حدث تم جمعه من خلال Crashlytics في تطبيقك.

• أوقِف الإبلاغ عن الأعطال تلقائيًا و تفعيل إعداد تقارير الموافقة للمستخدمين لاحظ أنه من خلال تلقائيًا، يجمع Crashlytics تلقائيًا تقارير الأعطال لجميع مستخدمي التطبيق.

إضافة مفاتيح مخصّصة

تساعدك المفاتيح المخصّصة في معرفة الحالة المحدّدة لتطبيقك التي تؤدي إلى تعطُّل. يمكنك ربط أزواج مفاتيح/قيم عشوائية بتقارير الأعطال، ومن ثمَّ استخدام المفاتيح المخصَّصة للبحث عن تقارير الأعطال وتصفيتها في وحدة تحكُّم Firebase.

• في لوحة بيانات Crashlytics، يمكنك البحث عن المشاكل. التي تطابق مفتاحًا مخصصًا
• عند مراجعة مشكلة معيّنة في وحدة التحكّم، يمكنك الاطّلاع على المفاتيح المخصّصة المرتبطة بكل حدث (علامة التبويب الفرعية المفاتيح) وحتى فلترة الأحداث حسب مفاتيح مخصّصة (قائمة فلترة في أعلى الصفحة).

ملاحظة: يتيح تطبيق Crashlytics استخدام 64 زوجًا من المفاتيح/القيمة كحدّ أقصى. بعد للوصول إلى هذا الحد، لن يتم حفظ القيم الإضافية. يمكن لكل زوج مفتاح/قيمة يصل حجمها إلى 1 كيلوبايت.

استخدِم الطريقة setCustomValue لضبط أزواج المفتاح/القيمة. على سبيل المثال:

Swift

// Set int_key to 100.
Crashlytics.crashlytics().setCustomValue(100, forKey: "int_key")

// Set str_key to "hello".
Crashlytics.crashlytics().setCustomValue("hello", forKey: "str_key")

Objective-C

عند ضبط الأعداد الصحيحة أو القيم المنطقية أو الأعداد العائمة، اضبط القيمة على @(value).

// Set int_key to 100.
[[FIRCrashlytics crashlytics] setCustomValue:@(100) forKey:@"int_key"];

// Set str_key to "hello".
[[FIRCrashlytics crashlytics] setCustomValue:@"hello" forKey:@"str_key"];

يمكنك أيضًا تعديل قيمة مفتاح حالي من خلال طلب المفتاح ثم ضبط إلى قيمة مختلفة. على سبيل المثال:

Swift

Crashlytics.crashlytics().setCustomValue(100, forKey: "int_key")

// Set int_key to 50 from 100.
Crashlytics.crashlytics().setCustomValue(50, forKey: "int_key")

Objective-C

[[FIRCrashlytics crashlytics] setCustomValue:@(100) forKey:@"int_key"];

// Set int_key to 50 from 100.
[[FIRCrashlytics crashlytics] setCustomValue:@(50) forKey:@"int_key"];

يمكنك إضافة أزواج المفتاح/القيمة بشكل مجمّع باستخدام طريقة setCustomKeysAndValues مع NSDictionary هي المعلمة الوحيدة:

Swift

let keysAndValues = [
                 "string key" : "string value",
                 "string key 2" : "string value 2",
                 "boolean key" : true,
                 "boolean key 2" : false,
                 "float key" : 1.01,
                 "float key 2" : 2.02
                ] as [String : Any]

Crashlytics.crashlytics().setCustomKeysAndValues(keysAndValues)

Objective-C

NSDictionary *keysAndValues =
    @{@"string key" : @"string value",
      @"string key 2" : @"string value 2",
      @"boolean key" : @(YES),
      @"boolean key 2" : @(NO),
      @"float key" : @(1.01),
      @"float key 2" : @(2.02)};

[[FIRCrashlytics crashlytics] setCustomKeysAndValues: keysAndValues];

إضافة رسائل سجلّ مخصَّصة

لمنح نفسك المزيد من السياق حول الأحداث التي أدت إلى حادث سير، يمكنك إضافة لسجلات Crashlytics المخصصة لتطبيقك. يربط Crashlytics السجلات. مع بيانات الأعطال وعرضها في صفحة Crashlytics من وحدة تحكُّم Firebase ضِمن علامة التبويب السجلات

ملاحظة: لتجنُّب إبطاء تطبيقك، تضع Crashlytics على حدّ أقصى سعة السجلات 64 كيلوبايت. وتحذف الإدخالات القديمة في السجلّ عندما تتجاوز سجلات الجلسة هذا الحد.

Swift

ويمكنك استخدام log() أو log(format:, arguments:) للمساعدة في تحديد المشاكل. إذا كنت تريد الحصول على مخرجات مفيدة في السجل مع الرسائل، وهي الكائن الذي تمرره إلى يجب أن يتوافق log() مع CustomStringConvertible الموقع. تعرض log() خاصية الوصف التي تحددها من أجل الكائن. على سبيل المثال:

Crashlytics.crashlytics().log("Higgs-Boson detected! Bailing out…, \(attributesDict)")

.log(format:, arguments:) تنسيقات القيم التي تم عرضها من الاتصال getVaList() على سبيل المثال:

Crashlytics.crashlytics().log(format: "%@, %@", arguments: getVaList(["Higgs-Boson detected! Bailing out…", attributesDict]))

لمزيد من التفاصيل حول كيفية استخدام log() أو log(format:, arguments:)، يمكنك الرجوع إلى Crashlytics المستندات المرجعية

Objective-C

ويمكنك استخدام log أو logWithFormat للمساعدة في تحديد المشاكل. لاحظ أنه إذا تريد الحصول على مخرجات سجلّ مفيدة مع الرسائل، وهو الكائن الذي تمرره إلى أي من الطريقتين إلى إلغاء خاصية المثيل description. على سبيل المثال:

[[FIRCrashlytics crashlytics] log:@"Simple string message"];

[[FIRCrashlytics crashlytics] logWithFormat:@"Higgs-Boson detected! Bailing out... %@", attributesDict];

[[FIRCrashlytics crashlytics] logWithFormat:@"Logging a variable argument list %@" arguments:va_list_arg];

لمزيد من التفاصيل عن كيفية استخدام "log" و"logWithFormat"، يُرجى الاطّلاع على المستندات المرجعية حول Crashlytics

ضبط معرّفات المستخدمين

لتشخيص مشكلة، من المفيد في كثير من الأحيان معرفة المستخدمين الذين واجهوا مشكلة عطل معين. يتضمن Crashlytics طريقة للكشف عن هوية المستخدمين في تقارير الأعطال لديك.

لإضافة أرقام تعريف مستخدمين إلى تقاريرك، عليك تخصيص معرّف فريد لكل مستخدم في شكل رقم تعريف أو رمز مميز أو قيمة مجزّأة:

Swift

Crashlytics.crashlytics().setUserID("123456789")

Objective-C

[[FIRCrashlytics crashlytics] setUserID:@"123456789"];

إذا احتجت في أي وقت إلى محو معرّف مستخدم بعد تعيينه، فأعد تعيين القيمة على سلسلة فارغة. لا يؤدي محو معرّف المستخدم إلى إزالة البيانات الحالية. سجلّات Crashlytics إذا كنت بحاجة إلى حذف السجلات المرتبطة بأحد المستخدمين رقم التعريف، يُرجى التواصل مع فريق دعم Firebase.

الإبلاغ عن الاستثناءات غير الفادحة

بالإضافة إلى ميزة الإبلاغ تلقائيًا عن أعطال تطبيقك، يتيح تطبيق Crashlytics تسجيل الاستثناءات غير الفادحة وإرسالها إليك في المرة القادمة التي يستخدم فيها تطبيقك عمليات الإطلاق.

ملاحظة: يخزِّن تطبيق Crashlytics فقط الاستثناءات الثمانية الأخيرة في مجموعة جلسة التطبيق. إذا كان تطبيقك يعرض أكثر من ثمانية استثناءات في جلسة واحدة، في حال فقدان الاستثناءات.

يمكنك تسجيل الاستثناءات غير الفادحة عن طريق تسجيل NSError عناصر باستخدام طريقة recordError. يحصل recordError على حزمة المكالمات لسلسلة المحادثات من خلال الاتصال [NSThread callStackReturnAddresses]

Swift

Crashlytics.crashlytics().record(error: error)

Objective-C

[[FIRCrashlytics crashlytics] recordError:error];

عند استخدام طريقة recordError، من المهم فهم NSError. وكيفية استخدام Crashlytics للبيانات لتجميع الأعطال. إجابة غير صحيحة أن استخدام طريقة recordError يمكن أن يؤدي إلى سلوك غير متوقع وقد تتسبب في تقييد Crashlytics من الإبلاغ عن الأخطاء المسجّلة في تطبيقك.

يتضمن كائن NSError ثلاث وسيطات:

• domain: String
• code: Int
• userInfo: [AnyHashable : Any]? = nil

على عكس الأعطال الفادحة التي يتم تجميعها من خلال تحليل تتبُّع تسلسل استدعاء الدوال البرمجية، يتم تسجيل الأخطاء يتم تجميعهما حسب domain وcode. هذا تمييز مهم بين الأعطال الفادحة والأخطاء المسجّلة. على سبيل المثال:

Swift

let userInfo = [
  NSLocalizedDescriptionKey: NSLocalizedString("The request failed.", comment: ""),
  NSLocalizedFailureReasonErrorKey: NSLocalizedString("The response returned a 404.", comment: ""),
  NSLocalizedRecoverySuggestionErrorKey: NSLocalizedString("Does this page exist?", comment: ""),
  "ProductID": "123456",
  "View": "MainView"
]

let error = NSError.init(domain: NSCocoaErrorDomain,
                         code: -1001,
                         userInfo: userInfo)

Objective-C

NSDictionary *userInfo = @{
  NSLocalizedDescriptionKey: NSLocalizedString(@"The request failed.", nil),
  NSLocalizedFailureReasonErrorKey: NSLocalizedString(@"The response returned a 404.", nil),
  NSLocalizedRecoverySuggestionErrorKey: NSLocalizedString(@"Does this page exist?", nil),
  @"ProductID": @"123456",
  @"View": @"MainView",
};

NSError *error = [NSError errorWithDomain:NSCocoaErrorDomain
                                     code:-1001
                                 userInfo:userInfo];

عند تسجيل الخطأ أعلاه، يؤدي ذلك إلى إنشاء مشكلة جديدة يتم تجميعها حسب المشكلة. "NSSomeErrorDomain" و-1001" المزيد من الأخطاء المسجلة التي تستخدم نفس يتم تجميع قيم النطاق والرمز البرمجي ضِمن المشكلة نفسها. البيانات الموجودة داخل يتم تحويل الكائن userInfo إلى أزواج المفتاح/القيمة ويتم عرضه في قسم المفاتيح/السجلات ضمن مشكلة فردية.

تنبيه: تجنَّب استخدام قيم فريدة، مثل رقم تعريف المستخدم ومعرّف المنتج والطوابع الزمنية. في حقل النطاق وحقل الرمز. يؤدي استخدام قيم فريدة في هذه الحقول إلى عدد القيم الفريدة للسمة، وقد يؤدّي إلى احتياج Crashlytics إلى الحدّ من الإبلاغ عن الأخطاء المسجّلة في التطبيق يجب إضافة القيم الفريدة إلى كائن قاموس userInfo.

السجلّات والمفاتيح المخصّصة

تمامًا مثل تقارير الأعطال، يمكنك تضمين السجلّات والمفاتيح المخصّصة لإضافة سياق إليها NSError. ومع ذلك، هناك فرق في نوع السجلات المرفقة الأعطال مقابل الأخطاء المسجلة. عند حدوث عطل وإعادة تشغيل التطبيق، والسجلات التي يستردها Crashlytics من القرص هي تلك التي تمت كتابتها مباشرةً وقت حدوث العطل. وعند تسجيل NSError، لا يتخذ التطبيق إجراءات على الفور تنتهي. ولأن Crashlytics لا يرسل إلا تقرير الخطأ الذي تم تسجيله على في المرة التالية التي يتم فيها تشغيل التطبيق ويجب أن يحد من المساحة المخصصة للسجلات على القرص، يمكن تسجيل ما يكفي من التسجيل بعد تسجيل NSError حتى يتم تدوير السجلات في الوقت الذي يرسل فيه Crashlytics التقرير من الخاص بك. ضع هذا الرصيد في الاعتبار عند تسجيل NSErrors واستخدام السجلات مفاتيح مخصّصة في تطبيقك.

اعتبارات الأداء

تذكَّر أنّ تسجيل NSError قد يكون مكلفًا إلى حدٍّ ما. في الوقت الذي إجراء الاتصال، يلتقط Crashlytics حزمة الاستدعاءات لسلسلة المحادثات الحالية باستخدام تسمى استرخاء المكدس. قد تستهلك هذه العملية وحدة المعالجة المركزية (CPU) ومنافذ الإدخال/الإخراج (I/O) بشكل مكثف، لا سيما في البُنى الأساسية التي تدعم فك DWARF (arm64 وx86). وبعد اكتمال الاسترخاء، تتم كتابة المعلومات على القرص بشكل متزامن. وهذا يمنع فقدان البيانات في حالة تعطُّل السطر التالي.

بينما يكون الاتصال من خلال واجهة برمجة التطبيقات هذه على سلسلة محادثات في الخلفية، فتذكر أن إرسال هذا الاتصال إلى تفقد قائمة الانتظار سياق تتبُّع تسلسل استدعاء الدوال البرمجية الحالي.

ماذا عن NSالاستثناءات؟

لا يوفّر تطبيق Crashlytics وسيلة لتسجيل بيانات "NSException" وتسجيلها. الحالات مباشرةً. بشكل عام، لا يتم التعامل مع واجهات برمجة تطبيقات Cocoa وCocoa Touch غير آمن تمامًا. وهذا يعني أن استخدام @catch يمكن أن يكون له نتائج خطيرة غير مقصودة والآثار الجانبية في عمليتك، حتى عند استخدامها بحذر شديد. لا ينبغي عليك أبدًا استخدام عبارات @catch في الرمز الخاص بك. يُرجى الرجوع إلى مستندات Apple حول هذا الموضوع.

تخصيص عمليات تتبُّع تسلسل استدعاء الدوال البرمجية

إذا كان تطبيقك يعمل في بيئة غير أصلية (مثل C++ أو Unity)، يمكنك استخدام واجهة برمجة التطبيقات Exception model API للإبلاغ عن البيانات الوصفية للأعطال في استثناء التطبيق الأصلي . يتم وضع علامة على الاستثناءات التي تم الإبلاغ عنها على أنّها غير فادحة.

Swift

var  ex = ExceptionModel(name:"FooException", reason:"There was a foo.")
ex.stackTrace = [
  StackFrame(symbol:"makeError", file:"handler.js", line:495),
  StackFrame(symbol:"then", file:"routes.js", line:102),
  StackFrame(symbol:"main", file:"app.js", line:12),
]

crashlytics.record(exceptionModel:ex)

Objective-C

FIRExceptionModel *model =
    [FIRExceptionModel exceptionModelWithName:@"FooException" reason:@"There was a foo."];
model.stackTrace = @[
  [FIRStackFrame stackFrameWithSymbol:@"makeError" file:@"handler.js" line:495],
  [FIRStackFrame stackFrameWithSymbol:@"then" file:@"routes.js" line:102],
  [FIRStackFrame stackFrameWithSymbol:@"main" file:@"app.js" line:12],
];

[[FIRCrashlytics crashlytics] recordExceptionModel:model];

يمكن أيضًا إعداد إطارات التكديس المخصصة باستخدام العناوين فقط:

Swift

var  ex = ExceptionModel.init(name:"FooException", reason:"There was a foo.")
ex.stackTrace = [
  StackFrame(address:0xfa12123),
  StackFrame(address:12412412),
  StackFrame(address:194129124),
]

crashlytics.record(exceptionModel:ex)

Objective-C

FIRExceptionModel *model =
    [FIRExceptionModel exceptionModelWithName:@"FooException" reason:@"There was a foo."];
model.stackTrace = @[
  [FIRStackFrame stackFrameWithAddress:0xfa12123],
  [FIRStackFrame stackFrameWithAddress:12412412],
  [FIRStackFrame stackFrameWithAddress:194129124],
];


[[FIRCrashlytics crashlytics] recordExceptionModel:model];

الحصول على سجلات شريط التنقل

تمنحك سجلات شريط التنقل فهمًا أفضل للتفاعلات التي يجريها المستخدم في تطبيقك أدى إلى تعطُّل أو حدث غير خطير أو خطأ ANR. يمكن لهذه السجلات أن تكون مفيدة عند محاولة إعادة إنتاج مشكلة ما وتصحيحها.

يتم دعم سجلات شريط التنقل من خلال Google Analytics، وبالتالي للحصول على سجلات شريط التنقل، بحاجة إلى تفعيل "إحصاءات Google" لمشروعك على Firebase إضافة حزمة تطوير البرامج (SDK) لمنصّة Firebase الخاصّة بخدمة "إحصاءات Google" إلى تطبيقك. بعد استيفاء هذه المتطلبات، يتم تلقائيًا إنشاء سجلات شريط التنقل. مضمّنة في بيانات الحدث ضمن علامة التبويب السجلات عند عرض التفاصيل المشكلة.

حزمة تطوير البرامج لخدمة "إحصاءات Google" يسجّل تلقائيًا حدث screen_view والذي يمكّن سجلات شريط التنقل من عرض قائمة بالشاشات التي تمت مشاهدتها قبل أعطال أو أحداث غير فادحة أو أحداث ANR. يحتوي سجلّ شريط التنقّل screen_view على مَعلمة firebase_screen_class.

تتم تعبئة سجلات شريط التنقل أيضًا بأي الأحداث المخصّصة التي تسجّلها يدويًا داخل سجلّ المستخدم بما في ذلك بيانات مَعلمات الحدث يمكن أن تساعد هذه البيانات في عرض سلسلة إجراءات المستخدمين التي أدت إلى تعطُّل أو حدث غير فادح أو خطأ ANR.

لاحظ أنه يمكنك التحكّم في جمع بيانات "إحصاءات Google" واستخدامها والتي تتضمّن البيانات التي تُعبّئ سجلات شريط التنقّل.

تفعيل إعداد تقارير الموافقة

يجمع تطبيق Crashlytics تلقائيًا تقارير الأعطال لجميع مستخدمي التطبيق. لمنح المستخدمين المزيد من التحكم في البيانات التي يرسلونها، يمكنك تفعيل تمكين إعداد التقارير عن طريق إيقاف إعداد التقارير التلقائية وإرسال البيانات فقط إلى Crashlytics عند اختيار ذلك في التعليمة البرمجية:

1. يمكنك إيقاف عملية الجمع التلقائي من خلال إضافة مفتاح جديد إلى ملف Info.plist:

   • المفتاح: FirebaseCrashlyticsCollectionEnabled
   • القيمة: false

2. تفعيل عملية الجمع لمستخدمين محدَّدين من خلال استدعاء بيانات Crashlytics تجاوز المجموعة في وقت التشغيل. تستمر قيمة التجاوز عبر على الإطلاق لتطبيقك حتى يتمكن تطبيق Crashlytics من جمع التقارير تلقائيًا.

   لإيقاف إعداد تقارير الأعطال التلقائية، اضبط false كقيمة الإلغاء. وعند ضبطها على false، لا تنطبق القيمة الجديدة إلى أن يتم تنفيذ عملية التطبيق.

   Swift

   Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(true)

   Objective-C

   [[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:YES];

ملاحظة: عندما يتم إيقاف جمع البيانات، يُخزِّن تطبيق Crashlytics الأعطال. المعلومات محليًا على الجهاز. إذا تم تفعيل جمع البيانات في وقت لاحق، أي معلومات تعطّل مخزّنة على الجهاز سيتم إرسالها إلى تطبيق Crashlytics قيد المعالجة.

إدارة بيانات "إحصاءات الأعطال"

تساعدك ميزة "إحصاءات الأعطال" في حلّ المشاكل من خلال مقارنة الحزمة المجهولة الهوية. يتيح لك تتبّع نشاطك التجاري من تطبيقات Firebase الأخرى وإعلامك بما إذا كانت المشكلة جزء من اتجاه أكبر. بالنسبة إلى العديد من المشاكل، توفّر ميزة "إحصاءات الأعطال" مراجع أيضًا. لمساعدتك في تصحيح العطل.

تستخدم "إحصاءات الأعطال" بيانات الأعطال المجمّعة لتحديد مؤشرات الاستقرار الشائعة. إذا أردت عدم مشاركة بيانات تطبيقك، يمكنك إيقاف "إحصاءات الأعطال". من قائمة إحصاءات الأعطال في أعلى قائمة مشاكل Crashlytics في وحدة تحكُّم Firebase.

ملاحظة: يؤدي إيقاف مشاركة البيانات إلى إزالة الإحصاءات المتعلقة بمشاكلك أيضًا. قد تؤدي التغييرات قد يستغرق تنفيذ هذا الإجراء مدة تصل إلى 24 ساعة.