گزارش‌های خرابی Firebase Crashlytics خود را سفارشی کنید

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

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

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

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

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

کلیدهای سفارشی را اضافه کنید

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

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

از متد 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 گزارش‌ها را با داده‌های خرابی شما مرتبط می‌کند و آنها را در صفحه Crashlytics کنسول Firebase در زیر برگه Logs نمایش می‌دهد.

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 به جفت‌های کلید-مقدار تبدیل می‌شوند و در بخش keys/log در یک شماره جداگانه نمایش داده می‌شوند.

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

درست مانند گزارش‌های خرابی، می‌توانید گزارش‌ها و کلیدهای سفارشی را برای افزودن زمینه به NSError جاسازی کنید. با این حال، در مواردی که گزارش‌ها به خرابی‌ها وصل می‌شوند در مقابل خطاهای ثبت‌شده تفاوت وجود دارد. هنگامی که یک خرابی رخ می دهد و برنامه دوباره راه اندازی می شود، گزارش هایی که Crashlytics از دیسک بازیابی می کند، مواردی هستند که درست تا زمان خرابی نوشته شده اند. وقتی یک NSError را وارد می‌کنید، برنامه فوراً خاتمه نمی‌یابد. از آنجایی که Crashlytics فقط گزارش خطای ثبت‌شده را در راه‌اندازی برنامه بعدی ارسال می‌کند و باید مقدار فضای تخصیص‌یافته برای گزارش‌ها روی دیسک را محدود کند، پس از ثبت NSError می‌توان به اندازه کافی وارد سیستم شد تا زمانی که Crashlytics گزارش را از دستگاه ارسال می‌کند، همه گزارش‌های مربوطه چرخانده شوند. این تعادل را هنگام ثبت NSErrors و استفاده از گزارش‌ها و کلیدهای سفارشی در برنامه خود در نظر داشته باشید.

ملاحظات عملکرد

به خاطر داشته باشید که ثبت یک NSError می تواند نسبتاً گران باشد. در زمان برقراری تماس، Crashlytics پشته تماس رشته فعلی را با استفاده از فرآیندی به نام باز کردن پشته ضبط می‌کند. این فرآیند می‌تواند فشرده CPU و I/O باشد، به‌ویژه در معماری‌هایی که از باز کردن DWARF پشتیبانی می‌کنند (arm64 و x86). پس از اتمام باز کردن، اطلاعات به صورت همزمان روی دیسک نوشته می شود. در صورت خراب شدن خط بعدی، این از دست دادن داده ها جلوگیری می کند.

در حالی که فراخوانی این API در یک رشته پس‌زمینه امن است، به یاد داشته باشید که ارسال این تماس به صف دیگر، زمینه ردیابی پشته فعلی را از دست می‌دهد.

در مورد NSE Exceptions چطور؟

Crashlytics امکانی برای ثبت و ضبط مستقیم نمونه های NSException ارائه نمی دهد. به طور کلی، API های Cocoa و Cocoa Touch از نظر استثنایی ایمن نیستند. این بدان معناست که استفاده از @catch می‌تواند عوارض جانبی ناخواسته بسیار جدی در فرآیند شما داشته باشد، حتی زمانی که با دقت بسیار مورد استفاده قرار گیرد. شما هرگز نباید از دستورات @catch در کد خود استفاده کنید. لطفاً به مستندات اپل در مورد موضوع مراجعه کنید.

سفارشی کردن ردپای پشته

اگر برنامه شما در یک محیط غیر بومی (مانند 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];

سیاهههای مربوط به پودر سوخاری را دریافت کنید

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

گزارش‌های Breadcrumb توسط Google Analytics ارائه می‌شوند، بنابراین برای دریافت گزارش‌های breadcrumb، باید Google Analytics را برای پروژه Firebase خود فعال کنید و Firebase SDK برای Google Analytics را به برنامه خود اضافه کنید . هنگامی که این الزامات برآورده شد، هنگام مشاهده جزئیات یک مشکل، گزارش‌های خرده نان به طور خودکار با داده‌های رویداد در برگه گزارش‌ها گنجانده می‌شوند.

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

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

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

فعال کردن گزارش انتخابی

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

1. با افزودن یک کلید جدید به فایل Info.plist خود، مجموعه خودکار را خاموش کنید:

   • کلید: FirebaseCrashlyticsCollectionEnabled
   • مقدار: false

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

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

   سویفت

   Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(true)

   هدف-C

   [[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:YES];

داده‌های Crash Insights را مدیریت کنید

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

Crash Insights از داده‌های خرابی انبوه برای شناسایی روندهای رایج پایداری استفاده می‌کند. اگر ترجیح می‌دهید داده‌های برنامه خود را به اشتراک نگذارید، می‌توانید از منوی Crash Insights در بالای فهرست مشکلات Crashlytics در کنسول Firebase ، از Crash Insights انصراف دهید.

در داشبورد Crashlytics ، می توانید روی یک مسئله کلیک کرده و گزارش رویداد مفصلی را دریافت کنید. شما می توانید این گزارش ها را سفارشی کنید تا به شما در درک بهتر آنچه در برنامه خود می افتد و شرایط مربوط به وقایع گزارش شده به Crashlytics .

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

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

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

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

کلیدهای سفارشی اضافه کنید

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

• در داشبورد Crashlytics ، می توانید مواردی را جستجو کنید که با یک کلید سفارشی مطابقت داشته باشد.
• هنگامی که در حال بررسی یک مسئله خاص در کنسول هستید ، می توانید کلیدهای سفارشی مرتبط را برای هر رویداد ( Keys Subtab) مشاهده کنید و حتی رویدادها را با کلیدهای سفارشی فیلتر کنید (منوی فیلتر در بالای صفحه).

برای تنظیم جفت های کلید/مقدار از روش 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 ​​با یک nsdionary به عنوان تنها پارامتر ، جفت های کلید/مقدار را به صورت عمده اضافه کنید:

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 سیاههها را با داده های خرابی شما مرتبط می کند و آنها را در صفحه Crashlytics کنسول Firebase ، در زیر برگه Logs نمایش می دهد.

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 به جفت های ارزش کلیدی تبدیل شده و در بخش کلیدها/سیاهههای مربوط در یک شماره فردی نمایش داده می شوند.

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

دقیقاً مانند گزارش های Crash ، می توانید سیاهههای مربوط و کلیدهای سفارشی را برای اضافه کردن زمینه به NSError تعبیه کنید. با این حال ، تفاوت در آنچه سیاهههای مربوط به خرابی در مقابل خطاهای وارد شده وصل شده اند وجود دارد. هنگامی که یک تصادف رخ می دهد و برنامه مجدداً راه اندازی می شود ، Logs Crashlytics از دیسک بازیابی می شود ، مواردی هستند که درست تا زمان تصادف نوشته شده اند. هنگامی که یک NSError را وارد می کنید ، برنامه بلافاصله خاتمه نمی یابد. از آنجا که Crashlytics فقط گزارش خطای وارد شده را در راه اندازی برنامه بعدی ارسال می کند و باید میزان فضای اختصاص داده شده برای سیاهههای مربوط به دیسک را محدود کند ، پس از ثبت NSError به اندازه کافی امکان پذیر است تا تمام سیاهههای مربوطه با ارسال Crashlytics گزارش از دستگاه ارسال شود. این تعادل را هنگام ورود به سیستم NSErrors و استفاده از سیاهههای مربوط و کلیدهای سفارشی در برنامه خود در نظر داشته باشید.

ملاحظات عملکرد

به خاطر داشته باشید که ورود به NSError می تواند بسیار گران باشد. در زمان تماس ، Crashlytics با استفاده از فرآیندی به نام Stack Undinding ، پشته تماس با موضوع فعلی را ضبط می کند. این فرآیند می تواند CPU و I/O فشرده باشد ، به ویژه در مورد معماری که از دست دادن کوتوله پشتیبانی می کنند (ARM64 و x86). پس از اتمام UndInd ، اطلاعات به صورت همزمان به دیسک نوشته می شود. در صورت خراب شدن خط بعدی ، این امر از از بین رفتن داده جلوگیری می کند.

در حالی که به راحتی می توان این API را در یک موضوع پس زمینه فراخوانی کرد ، به یاد داشته باشید که ارسال این تماس به یک صف دیگر ، زمینه ردیابی پشته فعلی را از دست می دهد.

در مورد nsexceptions چطور؟

Crashlytics تسهیلاتی برای ورود به سیستم و ضبط موارد NSException به طور مستقیم ارائه نمی دهد. به طور کلی ، API های لمسی کاکائو و کاکائو از استثناء نیستند. این بدان معناست که استفاده از @catch می تواند عوارض جانبی ناخواسته بسیار جدی در فرآیند شما داشته باشد ، حتی در صورت استفاده از مراقبت های شدید. شما هرگز نباید از عبارات @catch در کد خود استفاده کنید. لطفاً به مستندات اپل در مورد موضوع مراجعه کنید.

آثار پشته را سفارشی کنید

اگر برنامه شما در یک محیط غیر بومی (مانند C ++ یا وحدت) اجرا می شود ، می توانید از API مدل استثناء برای گزارش ابرداده Crash در قالب استثناء بومی برنامه خود استفاده کنید. استثنائات گزارش شده به عنوان غیر جبهه مشخص شده اند.

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 می شود. این سیاهههای مربوط می توانند هنگام تلاش برای تولید مثل و اشکال زدایی یک مسئله مفید باشند.

سیاهههای مربوط به Breadcrumb از Google Analytics استفاده می شوند ، بنابراین برای به دست آوردن سیاهههای مربوط به نان ، باید Google Analytics را برای پروژه Firebase خود فعال کرده و SDK Firebase را برای Google Analytics به برنامه خود اضافه کنید . پس از برآورده شدن این الزامات ، هنگام مشاهده جزئیات یک مسئله ، سیاهههای مربوط به نان به طور خودکار با داده های یک رویداد در برگه سیاههها گنجانده می شوند.

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

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

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

Enable opt-in reporting

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

1. با افزودن یک کلید جدید به پرونده Info.plist خود ، مجموعه خودکار را خاموش کنید:

   • کلید: FirebaseCrashlyticsCollectionEnabled
   • مقدار: false

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

   برای امتناع از گزارش تصادف اتوماتیک ، به عنوان مقدار false گرفته شود. هنگام تنظیم false ، مقدار جدید تا اجرای بعدی برنامه اعمال نمی شود.

   سویفت

   Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(true)

   هدف-C

   [[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:YES];

داده های بینش Crash را مدیریت کنید

Crash Insights به شما کمک می کند تا با مقایسه آثار پشته ناشناس خود در مورد اثری از سایر برنامه های Firebase ، مسائل را حل کنید و به شما اطلاع می دهد که آیا مسئله شما بخشی از یک روند بزرگتر است یا خیر. برای بسیاری از مسائل ، Crash Insights حتی منابعی را برای کمک به اشکال زدایی در مورد تصادف فراهم می کند.

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

In the Crashlytics dashboard, you can click into an issue and get a detailed event report. You can customize those reports to help you better understand what's happening in your app and the circumstances around events reported to Crashlytics .

• Instrument your app to log custom keys , custom log messages , and user identifiers .

• Report exceptions to Crashlytics .

• Automatically get breadcrumb logs if your app uses the Firebase SDK for Google Analytics . These logs give you visibility into user actions leading up to a Crashlytics -collected event in your app.

• Turn off automatic crash reporting and enable opt-in reporting for your users. Note that, by default, Crashlytics automatically collects crash reports for all your app's users.

Add custom keys

Custom keys help you get the specific state of your app leading up to a crash. You can associate arbitrary key/value pairs with your crash reports, then use the custom keys to search and filter crash reports in the Firebase console.

• In the Crashlytics dashboard , you can search for issues that match a custom key.
• When you're reviewing a specific issue in the console, you can view the associated custom keys for each event ( Keys subtab) and even filter the events by custom keys ( Filter menu at the top of the page).

Use the setCustomValue method to set key/value pairs. به عنوان مثال:

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

You can also modify the value of an existing key by calling the key and setting it to a different value. به عنوان مثال:

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

Add key/value pairs in bulk by using the setCustomKeysAndValues method with an NSDictionary as the only parameter:

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

Add custom log messages

To give yourself more context for the events leading up to a crash, you can add custom Crashlytics logs to your app. Crashlytics associates the logs with your crash data and displays them in the Crashlytics page of the Firebase console , under the Logs tab.

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

Set user identifiers

To diagnose an issue, it's often helpful to know which of your users experienced a given crash. Crashlytics includes a way to anonymously identify users in your crash reports.

To add user IDs to your reports, assign each user a unique identifier in the form of an ID number, token, or hashed value:

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

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

If you ever need to clear a user identifier after you set it, reset the value to a blank string. Clearing a user identifier does not remove existing Crashlytics records. If you need to delete records associated with a user ID, contact Firebase support .

Report non-fatal exceptions

In addition to automatically reporting your app's crashes, Crashlytics lets you record non-fatal exceptions and sends them to you the next time your app launches.

You can record non-fatal exceptions by recording NSError objects with the recordError method. recordError captures the thread's call stack by calling [NSThread callStackReturnAddresses] .

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

[[FIRCrashlytics crashlytics] recordError:error];

When using the recordError method, it's important to understand the NSError structure and how Crashlytics uses the data to group crashes. Incorrect usage of the recordError method can cause unpredictable behavior and may cause Crashlytics to limit reporting of logged errors for your app.

An NSError object has three arguments:

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

Unlike fatal crashes, which are grouped via stack trace analysis, logged errors are grouped by domain and code . This is an important distinction between fatal crashes and logged errors. به عنوان مثال:

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

When you log the error above, it creates a new issue that is grouped by NSSomeErrorDomain and -1001 . Additional logged errors that use the same domain and code values are grouped under the same issue. Data contained within the userInfo object are converted to key-value pairs and displayed in the keys/logs section within an individual issue.

Logs and custom keys

Just like crash reports, you can embed logs and custom keys to add context to the NSError . However, there is a difference in what logs are attached to crashes versus logged errors. When a crash occurs and the app is relaunched, the logs Crashlytics retrieves from disk are those that were written right up to the time of the crash. When you log an NSError , the app does not immediately terminate. Because Crashlytics only sends the logged error report on the next app launch and must limit the amount of space allocated for logs on disk, it is possible to log enough after an NSError is recorded so that all relevant logs are rotated out by the time Crashlytics sends the report from the device. Keep this balance in mind when logging NSErrors and using logs and custom keys in your app.

ملاحظات عملکرد

Keep in mind that logging an NSError can be fairly expensive. At the time you make the call, Crashlytics captures the current thread's call stack using a process called stack unwinding. This process can be CPU and I/O intensive, particularly on architectures that support DWARF unwinding (arm64 and x86). After the unwind is complete, the information is written to disk synchronously. This prevents data loss if the next line were to crash.

While it is safe to call this API on a background thread, remember that dispatching this call to another queue loses the context of the current stack trace.

What about NSExceptions?

Crashlytics doesn't offer a facility for logging and recording NSException instances directly. Generally speaking, the Cocoa and Cocoa Touch APIs are not exception-safe. That means the use of @catch can have very serious unintended side-effects in your process, even when used with extreme care. You should never use @catch statements in your code. Please refer to Apple's documentation on the topic.

Customize stack traces

If your app runs in a non-native environment (such as C++ or Unity), you can use the Exception Model API to report crash metadata in your app's native exception format. Reported exceptions are marked as non-fatals.

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

Custom stack frames can also be initialized with just addresses:

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

Get breadcrumb logs

Breadcrumb logs give you a better understanding of the interactions that a user had with your app leading up to a crash, non-fatal, or ANR event. These logs can be helpful when trying to reproduce and debug an issue.

Breadcrumb logs are powered by Google Analytics, so to get breadcrumb logs, you need to enable Google Analytics for your Firebase project and add the Firebase SDK for Google Analytics to your app. Once these requirements are met, breadcrumb logs are automatically included with an event's data within the Logs tab when you view the details of an issue.

The Analytics SDK automatically logs the screen_view event which enables the breadcrumb logs to show a list of screens viewed before the crash, non-fatal, or ANR event. A screen_view breadcrumb log contains a firebase_screen_class parameter.

Breadcrumb logs are also populated with any custom events that you manually log within the user's session, including the event's parameter data. This data can help show a series of user actions leading up to a crash, non-fatal, or ANR event.

Note that you can control the collection and use of Google Analytics data , which includes the data that populates breadcrumb logs.

Enable opt-in reporting

By default, Crashlytics automatically collects crash reports for all your app's users. To give users more control over the data they send, you can enable opt-in reporting by disabling automatic reporting and only sending data to Crashlytics when you choose to in your code:

1. Turn off automatic collection by adding a new key to your Info.plist file:

   • Key: FirebaseCrashlyticsCollectionEnabled
   • Value: false

2. Enable collection for select users by calling the Crashlytics data collection override at runtime. The override value persists across launches of your app so Crashlytics can automatically collect reports.

   To opt out of automatic crash reporting, pass false as the override value. When set to false , the new value does not apply until the next run of the app.

   سویفت

   Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(true)

   هدف-C

   [[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:YES];

Manage Crash Insights data

Crash Insights helps you resolve issues by comparing your anonymized stack traces to traces from other Firebase apps and letting you know if your issue is part of a larger trend. For many issues, Crash Insights even provides resources to help you debug the crash.

Crash Insights uses aggregated crash data to identify common stability trends. If you'd prefer not to share your app's data, you can opt-out of Crash Insights from the Crash Insights menu at the top of your Crashlytics issue list in the Firebase console .