SmartCrashReportsAPI

Smart Crash Reports requires no Application Enhancer or similar "patching" frameworks users have to install; they operate on the InputManager mechanism that built-in Mac OS X.

Smart Crash Reports is completely free to use for both users and developers; Unsanity is providing it as a service to the community being certain it will benefit all the users on the platform.

How does Smart Crash Reports work?

Whenever an application crashes on user's computer and they click on the Report... button, Smart Crash Reports analyzes the crash log that is about to be submitted to Apple. If the crash log is determined to be related to a developer that registered the application or product (Contextual Menu Module, InputManager, or any other type of system plugin), then the user is given an option to submit the bug report to both that developer and Apple, thus giving the developer the chance to fix the bug in the crashed product in a timely manner.

For developers, there is two ways to make Smart Crash Reports recognize your product. First, and probably the simplest one, is to add a couple of new keys into the application's Info.plist file that instruct Smart Crash Reports what to do in case that application crashes. However, this method only works for stand-alone applications and not plugins.

Second method involves using of the supplied API calls to register a Match Specifier with the system. A match specifier is a simple string (no wildcards or regexp) that contains full or partial name of developer product(s) CFBundleIdentifier (for example, "com.somecompany."). When an application crashes on user's computer, Smart Crash Reports system analyzes the crashed thread of the crash log to determine if it contains any of the match specifiers registered with it. If so, the crash is likely related to the developer who registered the match specifier, so Smart Crash Reports takes the appropriate action from there on.

How Developer Receives The Crash Reports

Developer can receive the crash reports that Smart Crash Reports detected as belonging to them in either of two ways:

• By E-Mail to the address provided during the match specifier registration (Unsanity server will handle the mailing for you)
• By a custom CGI script on your web server that processes CrashReporter logs

So, How to Make My Application Work With Smart Crash Reports so I Receive Crash Logs?

If you develop an application and would like to simply receive all the crash logs related to it, do this:

1. Obtain an E-mail Ticket ID for the E-mail you wish to receive reports at by going to the following URL: http://www.unsanity.com/goto/email-ticket/.
2. Add the following keys to your application Info.plist:
   <key>SmartCrashReports_CompanyName</key>
<string>Your Company Name</string>
<key>SmartCrashReports_EmailTicket</key>
<string>SCR-XXXXXXXX</string>
   Replace "Your Company Name" with a readable (short) company name, and "SCR-XXXXXXXX" with the Email Ticket ID you will receive in the E-mail after performing Step 1.
   
3. You're all done! If you'd like to use your own CGI to process the crash logs, replace SmartCrashReports_EmailTicket key with the SmartCrashReports_URL key. Now your application is successfully registered with the Smart Crash Reports system and you will receive crash logs for it in the mail.

If you are developing a plugin, InputManager, and whatnot, you have to use the API provided to register your Match Specifier:

1. Download the Smart Crash Reports SDK. It will contain two files (among others), libSmartCrashReportsAPI.a and SmartCrashReportsAPI.h. Add them to your project.
2. Obtain an E-mail Ticket ID for the E-mail you wish to receive reports at by going to the following URL: http://www.unsanity.com/goto/email-ticket/.
3. Somewhere in your application, or plugin, add the following line:
   UnsanitySCR_RegisterMatchSpecifier(NULL, CFSTR("Your Company Name"), NULL, CFSTR("SCR-XXXXXXXX"), NULL);
   Replace "Your Company Name" with a readable (short) company name, and "SCR-XXXXXXXX" with the Email Ticket ID you will receive in the E-mail after performing Step 2.
   Note: The best way to call this is after your application has finished launching, such as applicationDidFinishLaunching: in the NSApp delegate for Cocoa apps, or whatever for any other types of projects.
4. There's no Step 4! Now your product is successfully registered with the Smart Crash Reports system and you will receive crash logs containing the match specifier in the crashed thread in the mail.

Notes: It is not necessary to register with Smart Crash Reports on every application launch; once you register, it is permanent and will exist until user deletes the SCR database somehow. However, it takes little speed/memory overhead so you can safely call it on every launch to avoid doing 'is registered already' checks and whatnot.

How to Make a CGI to Accept Crash Reports On Your Site?

If you wish to receive crash reports on your Web site, you can implement the custom Submit URL script that user's CrashReporter.app will contact directly. However, keep in mind that the following criteria should be met:

• Your web server script has to be in the same place over next several years, at the very least, to allow delivery of crash reports to you.
• You are responsible for adjusting the web script if the format CrashReporter.app sends crash reports in changes.
• Your web server should be accessible 24/7 and be on a reasonably fast connection to not delay user's submission process.

For the above reasons, it is recommended to obtain the E-mail ticket from Unsanity and use the E-mail feature of Smart Crash Reports. Unsanity will make sure the server is accessible, knows how to parse all formats of submissions, and will safely redirect the crash reports to the email you provide.

If your own Web script is still the way you want to go, here is the list of keys currently known to be passed to the script by the CrashReporter.app in a POST form data:

• url_from: contains the subject of the crash report, usually "<Some Application> crash"
• feedback_comments: user comments they entered in the additional info fields
• bug_type: unknown constant, probably determines which POST elements are available; presently 9.
• app_name: full crashed application name
• app_version: version of the crashed application
• os_version: Mac OS X version, in form 10.X.X:BUILD (for example, "10.4.2:8C46")
• machine_config: Computer configuration string, for example, "PowerMac7,2 (2048 MB)"
• page_source: Contains BASE64-encoded crash report
• system_profile: Contains BASE64-encoded property list with a brief system profile of the user's system.

Please note that these form keys are subject to change by Apple, so it is your responsibility to adjust the scripts on your Web servers if such thing happens.

What Are The Licensing Terms for Smart Crash Reports and its SDK?

You are free to use and distribute Smart Crash Reports enabled products freely in any form without prior permission from Unsanity, LLC. If you like the system and would like to return the favor Unsanity is doing to the developer community, link to Smart Crash Reports somewhere on your SCR-enabled product page:
This product uses <a href="http://www.unsanity.com/smartcrashreports/">Smart Crash Reports<a> by <a href="http://www.unsanity.com/">Unsanity<a>.