سفارشی‌سازی گزارش‌های خرابی برای پلاتفرم‌های Apple

انتخاب پلاتفرم: iOS+‎ Android Flutter Unity


می‌توانید روی یک مشکل کلیک کنید و گزارش رویداد مفصلی را در DevOps و تعامل > Crashlytics داشبورد کنسول Firebase دریافت کنید. می‌توانید این گزارش‌ها را سفارشی‌سازی کنید تا به شما کمک کند بهتر متوجه شوید چه اتفاقی در برنامه‌تان می‌افتد و شرایط پیرامون رویدادهای گزارش‌شده به Crashlytics چیست.

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

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

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

  • گزارش خرابی خودکار را خاموش کنید و گزارش‌دهی با موافقت را برای کاربران فعال کنید. توجه داشته باشید که به‌طور پیش‌فرض، 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 پشته تماس رشته فعلی را بااستفاده از فرایندی به نام باز کردن پشته ضبط می‌کند. این فرایند می‌تواند ازنظر واحد پردازش مرکزی و ورودی/خروجی فشرده باشد، به‌ویژه در معماری‌هایی که از واگرد DWARF پشتیبانی می‌کنند (arm64 و x86). پس‌از تکمیل واگرد، اطلاعات به‌صورت هم‌زمان روی دیسک نوشته می‌شود. این کار از ازدست رفتن داده‌ها درصورت خرابی خط بعدی جلوگیری می‌کند.

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

‫NSExceptions چطور؟

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

سفارشی‌سازی ردیابی پشته

اگر برنامه‌تان در محیط غیربومی (مثل C++ یا Unity) اجرا می‌شود، می‌توانید از «میانای برنامه‌سازی کاربردی مدل استثنا» برای گزارش فراداده خرابی در قالب استثنای بومی برنامه‌تان استفاده کنید. استثناهای گزارش‌شده به‌عنوان غیرمهلک علامت‌گذاری می‌شوند.

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 Analytics را فعال کنید برای پروژه Firebase و «کیت توسعه نرم‌افزار Firebase برای Google Analytics» را به برنامه‌تان اضافه کنید. پس‌از برآورده شدن این الزامات، گزارش‌های ردپای خرده نان به‌طور خودکار به داده‌های رویداد در برگه گزارش‌ها اضافه می‌شود وقتی جزئیات مشکلی را مشاهده می‌کنید (همه مشکلاتتان را در داشبورد DevOps و مشارکت > Crashlytics در Firebase console ببینید).

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

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

مراحل بعدی

  • داده‌هایتان را به BigQuery یا Cloud Logging صادر کنید تا از تجزیه‌وتحلیل و ویژگی‌های پیشرفته، مثل پرسش از داده‌ها، ساختن داشبوردهای سفارشی، و راه‌اندازی هشدارهای سفارشی بهره‌مند شوید.