Integration into your projects

Call out into the framework

Once you got the framework embedded into you application the actual integration is really easy. Just include the header file and a few class methods become available.

 [[FRFeedbackReporter sharedReporter] reportFeedback];
 [[FRFeedbackReporter sharedReporter] reportIfCrash];

NOTE: The screencast is currently a litte out of date and does not include the latest API changes.

Method reportIfCash preferably should be called just after your application has started. A good place is awakeFromNib of the application controller. It checks whether there has been a crash or hang report since the last run. If so, it presents the user the feedback dialog. If there wasn't it moves on quietly.

Method reportFeedback is usually called from a "Feedback" menu item in your "Help" menu. This way users can send feedback at any time using the same mechanism.

Since the 1.1.0 release you can set a delegate and pass in arbitrary data on the submission e.g. like license information.

    ...
    [[FRFeedbackReporter sharedReporter] setDelegate:self];
 }

 - (NSDictionary*) customParametersForFeedbackReport
 {
    NSMutableDictionary *dict = [NSMutableDictionary dictionary];
    ...
    return dict;
 }

Catch uncaught exceptions

FeedbackReporter can also catch uncaught exceptions and pop up whenever they happen. All you have to do is to specify a new principal class in the project's Info.plist.

 <key>Principal class</key>
 <string>FRExceptionReportingApplication</string>

Specify the target in your projects Info.plist

The framework needs to know where to post the information to. The target needs to be specified in the application's Info.plist. Note: the %@ will get expanded to your application's name. If you don't want this URL to be guessable it can also be hard coded to whatever you like. The project parameter must just match the directory on the server.

 <key>FRFeedbacReporter.targetURL</key>
 <string>http://yourdomain.com/feedback/submit.php?project=%@</string>

Gather custom information from a shell script

In case your application needs more details from the user's system than what is provided by the FeedbackReporter framework you can include a shell script called FRFeedbackReporter.sh into your application bundle. It will be called whenever the feedback dialog comes up and the stdout and stderr output gets included in the shell pane.

 #!/bin/sh
 ls -la ~/Library/Something

Receiving the information on the server

The framework is using a standard multi-part post request to upload the data to the web server. It uses the target URL that is specified in the Info.plist. If you stick with the provided PHP script to receive the feedback submissions, all you need to do is to adjust the path in the php script and make sure uploads are enabled on your web server. You can verify that with a simple upload form (which is included in the distribution).

The information on the server will look like this:

   2008-05-15T23:36:18-9673e6e934d45a9090317edc77eff278/
     comment
     console
     crashes
     email
     exception
     preferences
     shell
     system
     user
     version

There is a directory per submission. The directory name includes date, time and a uniq id to prevent naming clashes. The individual files hold the data from the tabs.

Once on the server you can easily inject them into your bug tracking/ticketing system or just zip them up and send them to you via email. A simple email script is included. It will send a zip of the information and provide a link to see it online.