تخصيص تقارير الأعطال لمنصات Apple

يمكنك النقر على إحدى المشاكل والحصول على تقرير مفصّل عن الحدث في لوحة بيانات DevOps & Engagement > Crashlytics في Firebase Console. يمكنك تخصيص هذه التقارير لمساعدتك في فهم ما يحدث في تطبيقك بشكل أفضل والظروف المحيطة بالأحداث التي تم الإبلاغ عنها إلى Crashlytics.

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

• يمكنك الإبلاغ عن الاستثناءات إلى Crashlytics.

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

• يمكنك إيقاف ميزة إعداد تقارير الأعطال التلقائية و تفعيل ميزة إعداد التقارير التي يوافق عليها المستخدمون. يُرجى العِلم أنّ Crashlytics تجمع تلقائيًا تقارير الأعطال لجميع مستخدمي تطبيقك.Crashlytics

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

تساعدك المفاتيح المخصّصة في الحصول على الحالة المحدّدة لتطبيقك التي أدّت إلى حدوث عطل. يمكنك ربط أزواج عشوائية من المفاتيح والقيم بتقارير الأعطال، ثم استخدام المفاتيح المخصّصة للبحث عن تقارير الأعطال وفلترتها في DevOps & Engagement > Crashlytics dashboard of the Firebase console.

• يمكنك البحث عن المشاكل التي تتطابق مع مفتاح مخصّص.

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

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

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

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

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

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

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

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

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

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

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

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

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)

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 السجلّات ببيانات الأعطال وتعرضها في علامة التبويب السجلّات عند الاطّلاع على تفاصيل مشكلة (يمكنك الاطّلاع على جميع مشاكلك في لوحة بيانات DevOps & Engagement > Crashlytics dashboard في Firebase console).

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

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

[[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];

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

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

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

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

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

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

الإبلاغ عن الاستثناءات غير الخطيرة

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

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

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

[[FIRCrashlytics crashlytics] recordError:error];

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

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

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

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

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)

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 إلى أزواج من المفاتيح والقيم وعرضها في قسم المفاتيح/السجلّات ضمن مشكلة فردية.

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

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

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

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

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

ماذا عن NSExceptions؟

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

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

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

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)

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];

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

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)

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"، لذا للحصول على سجلّات مسار التنفيذ، عليك تفعيل "إحصاءات Google" لمشروعك على Firebase و إضافة حزمة تطوير البرامج (SDK) لخدمة Google Analytics إلى تطبيقك. بعد استيفاء هذه المتطلبات، يتم تضمين سجلّات مسار التنفيذ تلقائيًا مع بيانات الحدث ضمن علامة التبويب السجلّات عند الاطّلاع على التفاصيل لمشكلة (يمكنك الاطّلاع على جميع مشاكلك في لوحة بيانات DevOps & Engagement > Crashlytics في Firebase Console).

تسجِّل حزمة تطوير البرامج (SDK) لخدمة Analytics تلقائيًا حدث screen_view الذي يتيح لسجلّات مسار التنفيذ عرض قائمة بالشاشات التي تم الاطّلاع عليها قبل حدوث العطل أو الحدث غير الخطير أو حدث عدم استجابة التطبيق (ANR). يحتوي سجلّ مسار التنفيذ screen_view على مَعلمة firebase_screen_class.

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

يُرجى العِلم أنّه يمكنك التحكّم في جمع بيانات Google Analytics واستخدامها، بما في ذلك البيانات التي تملأ سجلّات مسار التنفيذ.

تفعيل ميزة إعداد التقارير التي يوافق عليها المستخدمون

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

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

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

2. فعِّل ميزة الجمع لمستخدمين محدّدين من خلال استدعاء عملية إلغاء جمع بيانات Crashlytics Crashlytics في وقت التشغيل. تظل قيمة الإلغاء سارية في جميع عمليات تشغيل تطبيقك اللاحقة، لذا يمكن أن تجمع Crashlyticsتلقائيًا التقارير لهذا المستخدم.

   Swift

   Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(true)

   Objective-C

   [[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:YES];

   إذا أوقف المستخدم لاحقًا ميزة جمع البيانات، يمكنك تمرير false كقيمة للإلغاء، وسيتم تطبيقها في المرة التالية التي يشغّل فيها المستخدم التطبيق وستظل سارية في جميع عمليات التشغيل اللاحقة لهذا المستخدم.

إدارة بيانات Crash Insights

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

تستخدِم ميزة Crash Insights بيانات الأعطال المجمّعة لتحديد المؤشرات الشائعة للاستقرار. إذا كنت تفضّل عدم مشاركة بيانات تطبيقك، يمكنك إيقاف ميزة Crash Insights من قائمة Crash Insights في أعلى قائمة المشاكل في لوحة بيانات DevOps & Engagement > Crashlytics في Firebase Console.

الخطوات التالية

• يمكنك تصدير بياناتك إلى BigQuery أو Cloud Logging للحصول على تحليل وميزات متقدّمة، مثل طلب بياناتك وإنشاء لوحات بيانات مخصّصة وإعداد تنبيهات مخصّصة.