diff --git a/docs/Guide-Installation-Setup-template.md b/docs/Guide-Installation-Setup-template.md
index 2defcb77..44c99b24 100644
--- a/docs/Guide-Installation-Setup-template.md
+++ b/docs/Guide-Installation-Setup-template.md
@@ -1,30 +1,42 @@
-## Version 4.1.1
+## Version 4.1.2
-- [Changelog](http://www.hockeyapp.net/help/sdk/mac/4.1.1/docs/docs/Changelog.html)
+- [Changelog](http://www.hockeyapp.net/help/sdk/mac/4.1.2/docs/docs/Changelog.html)
**NOTE:** With the release of HockeySDK 4.0.0-alpha.1 a bug was introduced which lead to the exclusion of the Application Support folder from iCloud and iTunes backups.
-If you have been using one of the affected versions (4.0.0-alpha.2, Version 4.0.0-beta.1, 4.0.0, 4.1.0-alpha.1, 4.1.0-alpha.2, or Version 4.1.0-beta.1), please make sure to update to at least version 4.0.1 or 4.1.0-beta.2 of our SDK as soon as you can.
-
+If you have been using one of the affected versions (4.0.0-alpha.2, Version 4.0.0-beta.1, 4.0.0, 4.1.0-alpha.1, 4.1.0-alpha.2, or Version 4.1.0-beta.1), please make sure to update to a newer version of our SDK as soon as you can.
## Introduction
+HockeySDK-Mac implements support for using HockeyApp in your Mac applications.
+
+The following feature is currently supported:
+
+1. **Collect crash reports:** If you app crashes, a crash log with the same format as from the Apple Crash Reporter is written to the device's storage. If the user starts the app again, he is asked to submit the crash report to HockeyApp. This works for both beta and live apps, i.e. those submitted to the App Store!
+
+2. **User Metrics:** Understand user behavior to improve your app. Track usage through daily and monthly active users, monitor crash impacted users, as well as customer engagement through session count. You can now track Custom Events in your app, understand user actions and see the aggregates on the HockeyApp portal.
+
+3. **Feedback:** Collect feedback from your users from within your app and communicate directly with them using the HockeyApp backend.
+
+4. **Add analytics to Sparkle:** If you are using Sparkle to provide app-updates (HockeyApp also supports Sparkle feeds for beta distribution) the SDK contains helpers to add some analytics data to each Sparkle request.
+
This document contains the following sections:
1. [Requirements](#requirements)
2. [Setup](#setup)
3. [Advanced Setup](#advancedsetup)
- 1. [Setup with CocoaPods](#cocoapods)
- 2. [Crash Reporting](#crashreporting)
- 3. [User Metrics](#user-metrics)
- 4. [Feedback](#feedback)
- 5. [Sparkle](#sparkle)
- 6. [Debug information](#debug)
+1. [Setup with CocoaPods](#cocoapods)
+2. [Crash Reporting](#crashreporting)
+3. [User Metrics](#user-metrics)
+4. [Feedback](#feedback)
+5. [Sparkle](#sparkle)
+6. [Debug information](#debug)
4. [Documentation](#documentation)
5. [Troubleshooting](#troubleshooting)
6. [Contributing](#contributing)
-7. [Contributor License](#contributorlicense)
-8. [Contact](#contact)
+1. [Code of Coduct](#codeofconduct)
+2. [Contributor License](#contributorlicense)
+7. [Contact](#contact)
## 1. Requirements
@@ -58,14 +70,14 @@ From our experience, 3rd-party libraries usually reside inside a subdirectory (l
3. Drag & drop `HockeySDK.framework` from your window in the `Finder` into your project in Xcode and move it to the desired location in the `Project Navigator` (e.g. into the group called `Vendor`)
4. A popup will appear. Select `Create groups for any added folders` and set the checkmark for your target. Then click `Finish`.
5. Now we’ll make sure the framework is copied into your app bundle:
- - Click on your project in the `Project Navigator` (⌘+1).
- - Click your target in the project editor.
- - Click on the `Build Phases` tab.
- - Click the `Add Build Phase` button at the bottom and choose `Add Copy Files`.
- - Click the disclosure triangle next to the new build phase.
- - Choose `Frameworks` from the Destination list.
- - Drag `HockeySDK-Mac` from the Project Navigator left sidebar to the list in the new Copy Files phase.
-
+- Click on your project in the `Project Navigator` (⌘+1).
+- Click your target in the project editor.
+- Click on the `Build Phases` tab.
+- Click the `Add Build Phase` button at the bottom and choose `Add Copy Files`.
+- Click the disclosure triangle next to the new build phase.
+- Choose `Frameworks` from the Destination list.
+- Drag `HockeySDK-Mac` from the Project Navigator left sidebar to the list in the new Copy Files phase.
+
6. Make sure to sign the app, since the SDK will store user related input in the keychain for privacy reasons
@@ -76,36 +88,36 @@ From our experience, 3rd-party libraries usually reside inside a subdirectory (l
1. Open your `AppDelegate.m` file.
2. Add the following line at the top of the file below your own `import` statements:
- ```objectivec
- @import HockeySDK;
- ```
+```objectivec
+@import HockeySDK;
+```
3. Search for the method `applicationDidFinishLaunching:`
4. Add the following lines to setup and start the Application Insights SDK:
- ```objectivec
- [[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];
- // Do some additional configuration if needed here
- [[BITHockeyManager sharedHockeyManager] startManager];
- ```
+```objectivec
+[[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];
+// Do some additional configuration if needed here
+[[BITHockeyManager sharedHockeyManager] startManager];
+```
**Swift**
1. Open your `AppDelegate.swift` file.
2. Add the following line at the top of the file below your own import statements:
-
- ```swift
- import HockeySDK
- ```
+
+```swift
+import HockeySDK
+```
3. Search for the method `applicationWillFinishLaunching`
4. Add the following lines to setup and start the Application Insights SDK:
-
- ```swift
- BITHockeyManager.sharedHockeyManager().configureWithIdentifier("APP_IDENTIFIER")
- // Do some additional configuration if needed here
- BITHockeyManager.sharedHockeyManager().startManager()
- ```
+
+```swift
+BITHockeyManager.sharedHockeyManager().configureWithIdentifier("APP_IDENTIFIER")
+// Do some additional configuration if needed here
+BITHockeyManager.sharedHockeyManager().startManager()
+```
*Note:* In case of document based apps, invoke `startManager` at the end of `applicationDidFinishLaunching`, since otherwise you may lose the Apple events to restore, open untitled document etc.
@@ -172,39 +184,39 @@ On Mac OS X there are three types of crashes that are not reported to a register
1. Custom `NSUncaughtExceptionHandler` don't start working until after `NSApplication` has finished calling all of its delegate methods!
Example:
- ```objectivec
- - (void)applicationDidFinishLaunching:(NSNotification *)note {
- ...
- [NSException raise:@"ExceptionAtStartup" format:@"This will not be recognized!"];
- ...
- }
- ```
+```objectivec
+- (void)applicationDidFinishLaunching:(NSNotification *)note {
+...
+[NSException raise:@"ExceptionAtStartup" format:@"This will not be recognized!"];
+...
+}
+```
2. The default `NSUncaughtExceptionHandler` in `NSApplication` only logs exceptions to the console and ends their processing. Resulting in exceptions that occur in the `NSApplication` "scope" not occurring in a registered custom `NSUncaughtExceptionHandler`.
Example:
- ```objectivec
- - (void)applicationDidFinishLaunching:(NSNotification *)note {
- ...
- [self performSelector:@selector(delayedException) withObject:nil afterDelay:5];
- ...
- }
-
- - (void)delayedException {
- NSArray *array = [NSArray array];
- [array objectAtIndex:23];
- }
- ```
+```objectivec
+- (void)applicationDidFinishLaunching:(NSNotification *)note {
+...
+[self performSelector:@selector(delayedException) withObject:nil afterDelay:5];
+...
+}
+
+- (void)delayedException {
+NSArray *array = [NSArray array];
+[array objectAtIndex:23];
+}
+```
3. Any exceptions occurring in IBAction or other GUI does not even reach the NSApplication default UncaughtExceptionHandler.
Example:
- ```objective
- - (IBAction)doExceptionCrash:(id)sender {
- NSArray *array = [NSArray array];
- [array objectAtIndex:23];
- }
- ```
+```objective
+- (IBAction)doExceptionCrash:(id)sender {
+NSArray *array = [NSArray array];
+[array objectAtIndex:23];
+}
+```
In general there are two solutions. The first one is to use an `NSExceptionHandler` class instead of an `NSUncaughtExceptionHandler`. But this has a few drawbacks which are detailed in `BITCrashReportExceptionApplication.h`.
@@ -230,28 +242,28 @@ The `BITCrashManagerDelegate` protocol (which is automatically included in `BITH
1. Text attachments: `-(NSString *)applicationLogForCrashManager:(BITCrashManager *)crashManager`
- Check the following tutorial for an example on how to add CocoaLumberjack log data: [How to Add Application Specific Log Data on iOS or OS X](http://support.hockeyapp.net/kb/client-integration-ios-mac-os-x/how-to-add-application-specific-log-data-on-ios-or-os-x)
+Check the following tutorial for an example on how to add CocoaLumberjack log data: [How to Add Application Specific Log Data on iOS or OS X](http://support.hockeyapp.net/kb/client-integration-ios-mac-os-x/how-to-add-application-specific-log-data-on-ios-or-os-x)
2. Binary attachments: `-(BITHockeyAttachment *)attachmentForCrashManager:(BITCrashManager *)crashManager`
Make sure to implement the protocol
- ```objectivec
- @interface YourAppDelegate () {}
-
- @end
- ```
+```objectivec
+@interface YourAppDelegate () {}
+
+@end
+```
and set the delegate:
- ```objectivec
- [[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];
-
- [[BITHockeyManager sharedHockeyManager] setDelegate: self];
-
- [[BITHockeyManager sharedHockeyManager] startManager];
- ```
-
+```objectivec
+[[BITHockeyManager sharedHockeyManager] configureWithIdentifier:@"APP_IDENTIFIER"];
+
+[[BITHockeyManager sharedHockeyManager] setDelegate: self];
+
+[[BITHockeyManager sharedHockeyManager] startManager];
+```
+
### 3.3 User Metrics
@@ -309,11 +321,11 @@ It's possible to attach porperties and/or measurements to a custom event.
BITMetricsManager *metricsManager = [BITHockeyManager sharedHockeyManager].metricsManager;
NSDictionary *myProperties = @{@"Property 1" : @"Something",
- @"Property 2" : @"Other thing",
- @"Property 3" : @"Totally different thing"};
+@"Property 2" : @"Other thing",
+@"Property 3" : @"Totally different thing"};
NSDictionary *myMeasurements = @{@"Measurement 1" : @1,
- @"Measurement 2" : @2.34,
- @"Measurement 3" : @2000000};
+@"Measurement 2" : @2.34,
+@"Measurement 3" : @2000000};
[metricsManager trackEventWithName:eventName properties:myProperties measurements:myMeasurements]
```
@@ -323,7 +335,7 @@ NSDictionary *myMeasurements = @{@"Measurement 1" : @1,
```swift
let myProperties = ["Property 1": "Something", "Property 2": "Other thing", "Property 3" : "Totally different thing."]
let myMeasurements = ["Measurement 1": 1, "Measurement 2": 2.3, "Measurement 3" : 30000]
-
+
let metricsManager = BITHockeyManager.sharedHockeyManager().metricsManager
metricsManager.trackEventWithName(eventName, properties: myProperties, myMeasurements: measurements)
```
@@ -332,9 +344,9 @@ metricsManager.trackEventWithName(eventName, properties: myProperties, myMeasure
### 3.4 Feedback
`BITFeedbackManager` lets your users communicate directly with you via the app and an integrated user interface. It provides a single threaded discussion with a user running your app. This feature is only enabled, if you integrate the actual view controllers into your app.
-
+
You should never create your own instance of `BITFeedbackManager` but use the one provided by the `[BITHockeyManager sharedHockeyManager]`:
-
+
```objectivec
[BITHockeyManager sharedHockeyManager].feedbackManager
```
@@ -348,8 +360,8 @@ Please check the [documentation](#documentation) of the `BITFeedbackManager` cla
#### 3.5.1 Setup for beta distribution
1. Install the Sparkle SDK: [http://sparkle-project.org](http://sparkle-project.org)
- As of today (01/2016), Sparkle doesn't support Mac sandboxes. If you require this, check out the following discussion https://github.com/sparkle-project/Sparkle/issues/363
-
+As of today (01/2016), Sparkle doesn't support Mac sandboxes. If you require this, check out the following discussion https://github.com/sparkle-project/Sparkle/issues/363
+
2. Set `SUFeedURL` to `https://rink.hockeyapp.net/api/2/apps/` and replace `` with the same value used to initialize the HockeySDK
3. Create a `.zip` file of your app bundle and upload that to HockeyApp.
@@ -359,34 +371,34 @@ Please check the [documentation](#documentation) of the `BITFeedbackManager` cla
1. Set the following additional Sparkle property:
- ```objectivec
- sparkleUpdater.sendsSystemProfile = YES;
- ```
+```objectivec
+sparkleUpdater.sendsSystemProfile = YES;
+```
2. Add the following Sparkle delegate method (don't forget to bind `SUUpdater` to your appDelegate!):
- ```objectivec
- - (NSArray *)feedParametersForUpdater:(SUUpdater *)updater
- sendingSystemProfile:(BOOL)sendingProfile {
- return [[BITSystemProfile sharedSystemProfile] systemUsageData];
- }
- ```
+```objectivec
+- (NSArray *)feedParametersForUpdater:(SUUpdater *)updater
+sendingSystemProfile:(BOOL)sendingProfile {
+return [[BITSystemProfile sharedSystemProfile] systemUsageData];
+}
+```
3. Initialize usage tracking depending on your needs.
- One example scenario is when the app is started or comes to foreground and when it goes to background or is terminated:
+One example scenario is when the app is started or comes to foreground and when it goes to background or is terminated:
- ```objectivec
- - (void)applicationWillFinishLaunching:(NSNotification *)aNotification
- …
- NSNotificationCenter *dnc = [NSNotificationCenter defaultCenter];
- BITSystemProfile *bsp = [BITSystemProfile sharedSystemProfile];
- [dnc addObserver:bsp selector:@selector(startUsage) name:NSApplicationDidBecomeActiveNotification object:nil];
- [dnc addObserver:bsp selector:@selector(stopUsage) name:NSApplicationWillTerminateNotification object:nil];
- [dnc addObserver:bsp selector:@selector(stopUsage) name:NSApplicationWillResignActiveNotification object:nil];
- …
- };
- ```
+```objectivec
+- (void)applicationWillFinishLaunching:(NSNotification *)aNotification
+…
+NSNotificationCenter *dnc = [NSNotificationCenter defaultCenter];
+BITSystemProfile *bsp = [BITSystemProfile sharedSystemProfile];
+[dnc addObserver:bsp selector:@selector(startUsage) name:NSApplicationDidBecomeActiveNotification object:nil];
+[dnc addObserver:bsp selector:@selector(stopUsage) name:NSApplicationWillTerminateNotification object:nil];
+[dnc addObserver:bsp selector:@selector(stopUsage) name:NSApplicationWillResignActiveNotification object:nil];
+…
+};
+```
### 3.6 Debug information
@@ -404,24 +416,24 @@ To check if data is send properly to HockeyApp and also see some additional SDK
## 4. Documentation
-Our documentation can be found on [HockeyApp](http://hockeyapp.net/help/sdk/mac/4.1.1/index.html).
+Our documentation can be found on [HockeyApp](http://hockeyapp.net/help/sdk/mac/4.1.2/index.html).
## 5.Troubleshooting
1. dlyb crash on startup
- Make sure that the apps build setting has `LD_RUNPATH_SEARCH_PATHS` set to `@executable_path/../Frameworks`
+Make sure that the apps build setting has `LD_RUNPATH_SEARCH_PATHS` set to `@executable_path/../Frameworks`
2. Crash on startup with Xcode debugger running
- Make sure there is no `All Exceptions` breakpoint active or limit it to `Objective-C` only and exclude `C++`.
+Make sure there is no `All Exceptions` breakpoint active or limit it to `Objective-C` only and exclude `C++`.
3. Feature are not working as expected
- Enable debug output to the console to see additional information from the SDK initializing the modules, sending and receiving network requests and more by adding the following code before calling `startManager`:
+Enable debug output to the console to see additional information from the SDK initializing the modules, sending and receiving network requests and more by adding the following code before calling `startManager`:
- [BITHockeyManager sharedHockeyManager].logLevel = BITLogLevelDebug;
+[BITHockeyManager sharedHockeyManager].logLevel = BITLogLevelDebug;
## 6. Contributing