Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
documentation cleanup,
- Loading branch information
Showing
9 changed files
with
349 additions
and
236 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| LICENSE.txt | ||
| HISTORY.md | ||
| README.txt | ||
| README.md | ||
| Server/* | ||
| Sources/* | ||
| Resources/* | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,87 @@ | ||
| ### 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]; | ||
|
|
||
|
|
||
| Method `reportIfCash` should preferably be called just after your application | ||
| has started. A good place is `applicationDidFinishLaunching` 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. | ||
|
|
||
| You can set a delegate and... | ||
|
|
||
| ... | ||
| [[FRFeedbackReporter sharedReporter] setDelegate:self]; | ||
| } | ||
|
|
||
| pass in arbitrary data on the submission e.g. like license information, | ||
|
|
||
| - (NSDictionary*) customParametersForFeedbackReport | ||
| { | ||
| NSMutableDictionary *dict = [NSMutableDictionary dictionary]; | ||
| ... | ||
| return dict; | ||
| } | ||
|
|
||
| there is a hook to anonymize the preference information | ||
|
|
||
| - (NSMutableDictionary*) anonymizePreferencesForFeedbackReport:(NSMutableDictionary *)preferences | ||
| { | ||
| ... | ||
| return preferences; | ||
| } | ||
|
|
||
| and you can change/set the target for the feedback report | ||
|
|
||
| - (NSString *) targetUrlForFeedbackReport | ||
| { | ||
| return "http://somewhere.com/" | ||
| } | ||
|
|
||
| ## 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>FRFeedbackReporter.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 | ||
|
|
||
| Please check the [documentation][1] for more how to receive the data on the | ||
| server. | ||
|
|
||
| [1]: http://github.com/tcurdt/feedbackreporter/Documentation/Server.md |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| ## 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`. 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. | ||
|
|
||
| There are couple -mostly contributed- scripts that can receive the reports on | ||
| the server side. | ||
|
|
||
| * a PHP script that sends you an email | ||
| * a PHP script that just writes the data to disk and let's cron send the email | ||
| * a PHP script that directly creates an issue in [Mantis][1] | ||
| * a node.js app that stores the reports to disk as json and (optinally) sends a notification via [prowl][2] | ||
|
|
||
| ...of course you can easily write your own backend. In the end it's just the | ||
| same as receiving a form POST submission. | ||
|
|
||
| Please check the various scripts/backends for how to configure them. | ||
|
|
||
| [1]: http://www.mantisbt.org/ | ||
| [2]: http://www.prowlapp.com/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| When writing desktop applications you are dealing with a huge amount of | ||
| different installations. Tracking down a bug requires to get detailed | ||
| information on what happened on the user's computer. But most likely you don't | ||
| want to bother the users with how to make this information available to you. | ||
|
|
||
| I wasn't really satisfied with the frameworks available so I came up with one | ||
| that suits my needs. Hopefully it will also suit yours. | ||
|
|
||
| For information on how to integrate the FeedbackReporter Framework please see | ||
| the [screencast][1] and the [documentation][1]. | ||
|
|
||
| Suggestions, bug reports and fixes are much welcome. The source code is | ||
| available through git at | ||
|
|
||
| git clone git://github.com/tcurdt/feedbackreporter.git | ||
|
|
||
| or via [web interface][3] | ||
|
|
||
| Enjoy! | ||
|
|
||
|
|
||
| Credits: | ||
|
|
||
| * Fraser Speirs, Multipart/Form construction, BSD License | ||
| * Jens Alfke, Exception handling and callstack, BSD License | ||
| * Torsten Curdt, initial codebase, ASL2.0 License | ||
|
|
||
| any more contributors sending patches. Thanks! | ||
|
|
||
| [1]: http://vafer.org/project/feedbackreporter/screencasts/Integrating%20with%20FeedbackReporter.mov | ||
| [2]: http://github.com/tcurdt/feedbackreporter/Documentation/Integration.md | ||
| [3]: http://github.com/tcurdt/feedbackreporter/tree/master |
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.