/* * Author: Andreas Linde * Kent Sutherland * * Copyright (c) 2012 HockeyApp, Bit Stadium GmbH. * Copyright (c) 2011 Andreas Linde & Kent Sutherland. * All rights reserved. * * Permission is hereby granted, free of charge, to any person * obtaining a copy of this software and associated documentation * files (the "Software"), to deal in the Software without * restriction, including without limitation the rights to use, * copy, modify, merge, publish, distribute, sublicense, and/or sell * copies of the Software, and to permit persons to whom the * Software is furnished to do so, subject to the following * conditions: * * The above copyright notice and this permission notice shall be * included in all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR * OTHER DEALINGS IN THE SOFTWARE. */ #import typedef enum BITCrashAlertType { BITCrashAlertTypeSend = 0, BITCrashAlertTypeFeedback = 1, } BITCrashAlertType; typedef enum BITCrashStatus { BITCrashStatusQueued = -80, BITCrashStatusUnknown = 0, BITCrashStatusAssigned = 1, BITCrashStatusSubmitted = 2, BITCrashStatusAvailable = 3, } BITCrashStatus; @protocol BITCrashManagerDelegate; /** The crash reporting module. This is the HockeySDK module for handling crash reports, including when distributed via the App Store. As a foundation it is using the open source, reliable and async-safe crash reporting framework [PLCrashReporter](https://code.google.com/p/plcrashreporter/). This module works as a wrapper around the underlying crash reporting framework and provides functionality to detect new crashes, queues them if networking is not available, present a user interface to approve sending the reports to the HockeyApp servers and more. It also provides options to add additional meta information to each crash report, like `userName`, `userEmail`, additional textual log information via `BITCrashManagerDelegate` protocol and a way to detect startup crashes so you can adjust your startup process to get these crash reports too and delay your app initialization. Crashes are send the next time the app starts. If `autoSubmitCrashReport` is enabled, crashes will be send without any user interaction, otherwise an alert will appear allowing the users to decide wether they want to send the report or not. This module is not sending the reports right when the crash happens deliberately, because if is not safe to implement such a mechanism while being async-safe (any Objective-C code is _NOT_ async-safe!) and not causing more danger like a deadlock of the device, than helping. We found that users do start the app again because most don't know what happened, and you will get by far most of the reports. Sending the reports on startup is done asynchronously (non-blocking). This is the only safe way to ensure that the app won't be possibly killed by the iOS watchdog process, because startup could take too long and the app could not react to any user input when network conditions are bad or connectivity might be very slow. More background information on this topic can be found in the following blog post by Landon Fuller, the developer of [PLCrashReporter](https://code.google.com/p/plcrashreporter/), about writing reliable and safe crash reporting: [Reliable Crash Reporting](http://goo.gl/WvTBR) */ @interface BITCrashManager : NSObject { @private id _delegate; NSString *_appIdentifier; NSString *_feedbackRequestID; float _feedbackDelayInterval; BITCrashStatus _serverResult; int _analyzerStarted; NSString *_crashesDir; NSFileManager *_fileManager; BOOL _crashIdenticalCurrentVersion; BOOL _crashReportActivated; NSMutableArray *_crashFiles; NSMutableData *_responseData; NSInteger _statusCode; NSURLConnection *_urlConnection; NSData *_crashData; BOOL _sendingInProgress; } ///----------------------------------------------------------------------------- /// @name Delegate ///----------------------------------------------------------------------------- /** Sets the optional `BITCrashManagerDelegate` delegate. */ @property (nonatomic, assign) id delegate; ///----------------------------------------------------------------------------- /// @name Additional meta data ///----------------------------------------------------------------------------- /** Define the users name or userid that should be send along each crash report @warning When setting this property, crash reports are not anonymous any more and the alerts will not show the "anonymous" word! */ @property (nonatomic, copy) NSString *userName; /** Define the users email address that should be send along each crash report @warning When setting this property, crash reports are not anonymous any more and the alerts will not show the "anonymous" word! */ @property (nonatomic, copy) NSString *userEmail; ///----------------------------------------------------------------------------- /// @name Configuration ///----------------------------------------------------------------------------- /** Flag that determines if crashes should be send without user interaction If enabled, new crashes will not cause an alert to show up asking the user if he or she agrees on sending the crash report to the server. By default a crash report is anonymous, unless you are adding personal information using the `userName`, `userEmail` or `[BITCrashManagerDelegate applicationLogForCrashReporter:]` options. For privacy reasons you should give the user an option not to send the reports. *Default*: _NO_ */ @property (nonatomic, assign, getter=isAutoSubmitCrashReport) BOOL autoSubmitCrashReport; /** Flag that determines if an "Always" option should be shown If enabled the crash reporting alert will also present an "Always" option, so the user doesn't have to approve every single crash over and over again. If `autoSubmitCrashReport` is enabled, this property has no effect, since no alert will be presented. @warning This will cause the dialog not to show the alert description text landscape mode! @see autoSubmitCrashReport */ @property (nonatomic, assign, getter=isShowingAlwaysButton) BOOL showAlwaysButton; // if YES, the user will be presented with a status of the crash, if known // if NO, the user will not see any feedback information (default) /** Flag that determines if the user should get feedback about the crash On the HockeyApp servers it is possible to assign each crash group a fixed app version. Each app version also has a status like `new`, `submitted` or `available`. This status defines what kind of feedback the user will get, if the crash belongs to a crash group with a fixed version assigned. The best case would be, that an update is already `available` which fixes this crash. *Default*: _NO_ */ @property (nonatomic, assign, getter=isFeedbackActivated) BOOL feedbackActivated; ///----------------------------------------------------------------------------- /// @name Crash Meta Information ///----------------------------------------------------------------------------- /** Indicates if the app crash in the previous session Use this on startup, to check if the app starts the first time after it crashed previously. You can use this also to disable specific events, like asking the user to rate your app. */ @property (nonatomic, readonly) BOOL didCrashInLastSession; // will return the timeinterval from startup to the crash in seconds, default is -1 /** Provides the time between startup and crash in seconds Use this in together with `didCrashInLastSession` to detect if the app crashed very early after startup. This can be used to delay app initialization until the crash report has been sent to the server or if you want to do any other actions like cleaning up some cache data etc. The `BITCrashManagerDelegate` protocol provides some delegates to inform if sending a crash report was finished successfully, ended in error or was cancelled by the user. @see didCrashInLastSession @see BITCrashManagerDelegate */ @property (nonatomic, readonly) NSTimeInterval timeintervalCrashInLastSessionOccured; @end