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

اختيار المنصة: +iOS Android Flutter Unity


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

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

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

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

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

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

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 تسجيل الاستثناءات غير الخطيرة وإرسالها إليك في المرة التالية التي يتم فيها تشغيل تطبيقك.

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

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

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

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

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

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

ماذا عن NSExceptions؟

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

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

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

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

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

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

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

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

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

    Swift 

    Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(true)

    Objective-C 

    [[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:YES];

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

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

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

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

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