Update release notes for Beta 3
This commit is contained in:
Lukas Spieß
Родитель
fa8e676501
Коммит
417d0cd823
|
|
@ -1,6 +1,6 @@
|
|||
[](https://travis-ci.org/Microsoft/ApplicationInsights-iOS)
|
||||
|
||||
# Application Insights for iOS (1.0-beta.2)
|
||||
# Application Insights for iOS (1.0-beta.3)
|
||||
|
||||
This is the repository of the iOS SDK for Application Insights. [Application Insights](http://azure.microsoft.com/en-us/services/application-insights/) is a service that allows developers to keep their applications available, performing, and succeeding. The SDK enables you to send telemetry of various kinds (events, traces, exceptions, etc.) to the Application Insights service where your data can be visualized in the Azure Portal.
|
||||
|
||||
|
|
@ -22,31 +22,43 @@ The SDK runs on devices with iOS 6.0 or higher.
|
|||
12. [Contributing](#contributing)
|
||||
13. [Contact](#contact)
|
||||
|
||||
## <a name="releasenotes"></a>1. Release Notes
|
||||
<a name="releasenotes"></a>
|
||||
## 1. Release Notes
|
||||
|
||||
* The size of the devices screen is now reported in physical pixels
|
||||
* Renamed umbrella-class and product to **ApplicationInsights**
|
||||
* Cleaned up code
|
||||
* Removed previously deprecated methods and classes
|
||||
* The order of stackframes is now reversed to appear in the portal correctly
|
||||
* Developer Mode for more ease during development/debugging
|
||||
* Includes Nullability warnings (learn more readin ([Apple's own blogpost]("https://developer.apple.com/swift/blog/?id=25") about this)
|
||||
* Add gzip-support to dramatically decrease data volume used to send data to the server
|
||||
* _Developer mode_ for ease of debugging
|
||||
* Setting a custom server now requires the complete URL to the server (e.g. https://yourdomin/something/tracking/)
|
||||
* Add new API to be able to manually set session and user IDs.
|
||||
|
||||
## <a name="breakingchanges"></a>2. Breaking Changes
|
||||
``` objectivec
|
||||
[MSAIApplicationInsights setUserId:@"your_user_id"];
|
||||
[MSAIApplicationInsights renewSessionWithId:@"4815162342"];
|
||||
```
|
||||
|
||||
* Allow to specify the amount of time that an app has to have been in the background before a new session is triggered.
|
||||
|
||||
``` objectivec
|
||||
[MSAIApplicationInsights setAppBackgroundTimeBeforeSessionExpires:60];
|
||||
```
|
||||
|
||||
* Make our sending-retry policy more robust and only delete data on unrecoverable HTTP status codes.
|
||||
* Trigger saving of queued-up date when the app goes to the background since then there is a high probability it might be removed from memory by the OS.
|
||||
* Add our Xcode docset part of the downloaded archive.
|
||||
* Several small fixes, cleanups and optimizations under the hood.
|
||||
|
||||
See [here](https://github.com/Microsoft/ApplicationInsights-iOS/releases) for the release notes of previous versions.
|
||||
|
||||
<a name="breakingchanges"></a>
|
||||
## 2. Breaking Changes
|
||||
Starting with the first 1.0 stable release, we will start deprecating API instead of breaking old ones.
|
||||
|
||||
* **[1.0-beta.2]** ```MSAIAppInsights``` was the the central entry-point to use the Application Insights SDK. It has been renamed to ```MSAIApplicationInsights```.
|
||||
* **[1.0-beta.2]** Setting the custom server URL now requires the complete URL to the server
|
||||
|
||||
|
||||
##<a id="requirements"></a> 3. Requirements
|
||||
<a id="requirements"></a>
|
||||
## 3. Requirements
|
||||
|
||||
The SDK runs on devices with iOS 6.0 or higher.
|
||||
|
||||
##<a name="setup"></a> 4. Setup
|
||||
<a name="setup"></a>
|
||||
## 4. Setup
|
||||
|
||||
We recommend integration of our binary into your Xcode project to setup Application Insights for your iOS app. For other ways to setup the SDK, see [Advanced Setup](#advancedsetup).
|
||||
|
||||
|
|
@ -54,7 +66,8 @@ We recommend integration of our binary into your Xcode project to setup Applicat
|
|||
|
||||
Please see the "[Getting an Application Insights Instrumentation Key](https://github.com/Microsoft/ApplicationInsights-Home/wiki#getting-an-application-insights-instrumentation-key)" section of the wiki for more information on acquiring a key.
|
||||
|
||||
### <a id="downloadsdk"></a> 4.2 Download the SDK
|
||||
<a id="downloadsdk"></a>
|
||||
### 4.2 Download the SDK
|
||||
|
||||
1. Download the latest [Application Insights for iOS](https://github.com/Microsoft/AppInsights-iOS/releases) framework which is provided as a zip-File.
|
||||
2. Unzip the file and you will see a folder called `ApplicationInsights` .
|
||||
|
|
@ -63,7 +76,8 @@ Please see the "[Getting an Application Insights Instrumentation Key](https://gi
|
|||
|
||||
From our experience, 3rd-party libraries usually reside inside a subdirectory (let's call our subdirectory `Vendor`), so if you don't have your project orgainzed with a subdirectory for libraries, now would be a great start for it. To continue our example, create a folder called "Vendor" inside your project directory and move the unzipped `ApplicationInsights`-folder into it.
|
||||
|
||||
### <a id="setupxcode"></a> 4.4 Set up the SDK in Xcode
|
||||
<a id="setupxcode"></a>
|
||||
### 4.4 Set up the SDK in Xcode
|
||||
|
||||
1. We recommend to use Xcode's group-feature to create a group for 3rd-party-lobraries similar to the structure of our files on disk. For example, similar to the file structure in 4.1 above, our projects have a group called `Vendor`.
|
||||
2. Make sure the `Project Navigator` is visible (⌘+1)
|
||||
|
|
@ -89,68 +103,71 @@ 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 <ApplicationInsights/ApplicationInsights.h>
|
||||
```
|
||||
```objectivec
|
||||
#import <ApplicationInsights/ApplicationInsights.h>
|
||||
```
|
||||
|
||||
3. Search for the method `application:didFinishLaunchingWithOptions:`
|
||||
4. Add the following lines to setup and start the Application Insights SDK:
|
||||
|
||||
```objectivec
|
||||
[[MSAIApplicationInsights sharedInstance] setup];
|
||||
// Do some additional configuration if needed here
|
||||
...
|
||||
[[MSAIApplicationInsights sharedInstance] start];
|
||||
```
|
||||
```objectivec
|
||||
[[MSAIApplicationInsights sharedInstance] setup];
|
||||
// Do some additional configuration if needed here
|
||||
...
|
||||
[[MSAIApplicationInsights sharedInstance] start];
|
||||
```
|
||||
|
||||
You can also use the following shortcuts:
|
||||
You can also use the following shortcuts:
|
||||
|
||||
```objectivec
|
||||
[MSAIApplicationInsights setup];
|
||||
[MSAIApplicationInsights start];
|
||||
```
|
||||
```objectivec
|
||||
[MSAIApplicationInsights setup];
|
||||
[MSAIApplicationInsights start];
|
||||
```
|
||||
|
||||
**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 ApplicationInsights
|
||||
```
|
||||
```swift
|
||||
#import ApplicationInsights
|
||||
```
|
||||
|
||||
3. Search for the method
|
||||
|
||||
```swift
|
||||
application(application: UIApplication, didFinishLaunchingWithOptions launchOptions:[NSObject: AnyObject]?) -> Bool`
|
||||
```
|
||||
```swift
|
||||
application(application: UIApplication, didFinishLaunchingWithOptions launchOptions:[NSObject: AnyObject]?) -> Bool`
|
||||
```
|
||||
|
||||
4. Add the following lines to setup and start the Application Insights SDK:
|
||||
|
||||
```swift
|
||||
MSAIApplicationInsights.sharedInstance().setup();
|
||||
MSAIApplicationInsights.sharedInstance().start();
|
||||
```
|
||||
```swift
|
||||
MSAIApplicationInsights.sharedInstance().setup();
|
||||
MSAIApplicationInsights.sharedInstance().start();
|
||||
```
|
||||
|
||||
You can also use the following shortcuts:
|
||||
You can also use the following shortcuts:
|
||||
|
||||
```swift
|
||||
MSAIApplicationInsights.setup();
|
||||
MSAIApplicationInsights.start();
|
||||
```
|
||||
```swift
|
||||
MSAIApplicationInsights.setup();
|
||||
MSAIApplicationInsights.start();
|
||||
```
|
||||
|
||||
**Congratulation, now you're all set to use Application Insights! See [Basic Usage](#basicusage) on how to use Application Insights.**
|
||||
|
||||
|
||||
##<a id="advancedsetup"></a> 5. Advanced Setup
|
||||
<a id="advancedsetup"></a>
|
||||
## 5. Advanced Setup
|
||||
|
||||
### 5.1 Set Instrumentation Key in Code
|
||||
|
||||
It is also possible to set the instrumentation key of your app in code. This will override the one you might have set in your `info.plist`. Do set it in code, MSAIApplicationInsights provides an overloaded constructor:
|
||||
|
||||
```objectivec
|
||||
[MSAIApplicationInsights setupWithInstrumentationKey:@"{YOUR-INSTRUMENTATION-KEY}"];
|
||||
|
||||
//Do additional configuration
|
||||
[MSAIApplicationInsights setupWithInstrumentationKey:@"{YOUR-INSTRUMENTATIONKEY}"];
|
||||
|
||||
MSAIApplicationInsights start];
|
||||
//Do additional configuration
|
||||
|
||||
[MSAIApplicationInsights start];
|
||||
```
|
||||
|
||||
|
||||
|
|
@ -166,7 +183,7 @@ As soon as Application Insights 1.0 is available, the version doesn't have to be
|
|||
|
||||
```ruby
|
||||
platform :ios, '8.0'
|
||||
pod "ApplicationInsights", '1.0-beta.2'
|
||||
pod "ApplicationInsights", '1.0-beta.3'
|
||||
```
|
||||
|
||||
### 5.3 iOS 8 Extensions
|
||||
|
|
@ -176,24 +193,25 @@ The following points need to be considered to use the Application Insights SDK w
|
|||
1. Each extension is required to use the same values for version (`CFBundleShortVersionString`) and build number (`CFBundleVersion`) as the main app uses. (This is required only if you are using the same `MSAIInstrumentationKey` for your app and extensions).
|
||||
2. You need to make sure the SDK setup code is only invoked **once**. Since there is no `applicationDidFinishLaunching:` equivalent and `viewDidLoad` can run multiple times, you need to use a setup like the following example:
|
||||
|
||||
```objectivec
|
||||
@interface TodayViewController () <NCWidgetProviding>
|
||||
@property (nonatomic, assign) BOOL didSetupApplicationInsightsSDK;
|
||||
@end
|
||||
```objectivec
|
||||
@interface TodayViewController () <NCWidgetProviding>
|
||||
@property (nonatomic, assign) BOOL didSetupApplicationInsightsSDK;
|
||||
@end
|
||||
|
||||
@implementation TodayViewController
|
||||
@implementation TodayViewController
|
||||
|
||||
- (void)viewDidLoad {
|
||||
[super viewDidLoad];
|
||||
if (!self.didSetupApplicationInsightsSDK) {
|
||||
[MSAIApplicationInsights setup];
|
||||
[MSAIApplicationInsights start];
|
||||
self.didSetupApplicationInsightsSDK = YES;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## <a name="developermode"></a> 6. Developer Mode
|
||||
- (void)viewDidLoad {
|
||||
[super viewDidLoad];
|
||||
if (!self.didSetupApplicationInsightsSDK) {
|
||||
[MSAIApplicationInsights setup];
|
||||
[MSAIApplicationInsights start];
|
||||
self.didSetupApplicationInsightsSDK = YES;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<a name="developermode"></a>
|
||||
## 6. Developer Mode
|
||||
|
||||
###6.1 Batching of data
|
||||
|
||||
|
|
@ -204,7 +222,7 @@ The **developer mode** is enabled automatically in case the debugger is attached
|
|||
We're all big fans of a clean debugging output without 3rd-party-SDKs messages pilling up in the debugging view, right?!
|
||||
That's why Application Insights keeps log messages to a minimum (like critical errors) unless the developer specifically enables before starting the SDK:
|
||||
|
||||
```objectivec
|
||||
```objectivec
|
||||
[MSAIApplicationInsights setup]; //setup the SDK
|
||||
|
||||
[[MSAIApplicationInsights sharedInstance] setDebugLogEnabled:YES]; //enable debug logging
|
||||
|
|
@ -214,7 +232,8 @@ That's why Application Insights keeps log messages to a minimum (like critical e
|
|||
|
||||
This setting is ignored if the app is running in an appstore environment, so the user's console won't be littered with our log messages.
|
||||
|
||||
## <a id="basicusage"></a> 7. Basic Usage
|
||||
<a id="basicusage"></a>
|
||||
## 7. Basic Usage
|
||||
|
||||
**[NOTE]** The SDK is optimized to defer everything possible to a later time while making sure e.g. crashes on startup can also be caught and each module executes other code with a delay some seconds. This ensures that applicationDidFinishLaunching will process as fast as possible and the SDK will not block the startup sequence resulting in a possible kill by the watchdog process.
|
||||
|
||||
|
|
@ -222,7 +241,7 @@ After you have setup the SDK as [described above](#setup), the ```MSAITelemetryM
|
|||
|
||||
### 7.1 Objective-C
|
||||
|
||||
```objectivec
|
||||
```objectivec
|
||||
// Send an event with custom properties and measurements data
|
||||
[MSAITelemetryManager trackEventWithName:@"Hello World event!"
|
||||
properties:@{@"Test property 1":@"Some value",
|
||||
|
|
@ -243,10 +262,8 @@ After you have setup the SDK as [described above](#setup), the ```MSAITelemetryM
|
|||
[MSAITelemetryManager trackMetricWithName:@"Test metric" value:42.2];
|
||||
```
|
||||
|
||||
|
||||
### 7.2 Swift
|
||||
|
||||
|
||||
|
||||
```swift
|
||||
// Send an event with custom properties and measuremnts data
|
||||
MSAITelemetryManager.trackEventWithName(name:"Hello World event!",
|
||||
|
|
@ -268,10 +285,12 @@ MSAITelemetryManager.trackPageView(pageView:"MyViewController",
|
|||
MSAITelemetryManager.trackMetricWithName(name:"Test metric", value:42.2);
|
||||
```
|
||||
|
||||
## <a name="autolifecycle"></a>8. Automatic collection of pageviews
|
||||
<a name="autolifecycle"></a>
|
||||
## 8. Automatic collection of lifecycle events
|
||||
|
||||
Automatic collection of life-cycle events is **enabled by default**. This means that Application Insights automatically tracks the appearance of a viewcontroller for you.
|
||||
Automatic collection of life-cycle events is **enabled by default**. This means that Application Insights automatically tracks the appearance of a viewcontroller and manages sessions for you.
|
||||
|
||||
### 8.1. Page views
|
||||
The automatic tracking of viewcontroller appearance can be disabled between setup and start of the SDK.
|
||||
|
||||
|
||||
|
|
@ -281,10 +300,36 @@ The automatic tracking of viewcontroller appearance can be disabled between setu
|
|||
[[MSAIApplicationInsights sharedInstance] setAutoPageViewTrackingDisabled:YES]; //disable the auto collection
|
||||
|
||||
[MSAIApplicationInsights start]; //start using the SDK
|
||||
|
||||
```
|
||||
|
||||
## <a name="crashreporting"></a>9. Crash Reporting
|
||||
### 8.2. Sessions
|
||||
|
||||
By default, the Application Insights for iOS SDK starts a new session when the containing app is restarted (That means a 'cold start', i.e. when the app has not already been in memory prior to being launched.) or when it has been in the background for more then 20 seconds.
|
||||
|
||||
You can either change this time frame:
|
||||
``` objectivec
|
||||
[MSAIApplicationInsights setAppBackgroundTimeBeforeSessionExpires:60];
|
||||
```
|
||||
|
||||
turn of automatic session completely:
|
||||
``` objectivec
|
||||
[MSAIApplicationInsights setAutoSessionManagementDisabled:YES];
|
||||
```
|
||||
|
||||
This then requires you to manage sessions manually:
|
||||
``` objectivec
|
||||
[MSAIApplicationInsights renewSessionWithId:@"4815162342"];
|
||||
```
|
||||
|
||||
### 8.3. Users
|
||||
|
||||
Normally, a random anonymous ID is automatically generated for every user of your app by the SDK. Alternatively you can set your own user ID which will then be attached to all telemetry events and crashes:
|
||||
```objectivec
|
||||
[MSAIApplicationInsights setUserId:@"your_user_id"];
|
||||
```
|
||||
|
||||
<a name="crashreporting"></a>
|
||||
## 9. Crash Reporting
|
||||
|
||||
The Application Insights SDK enables crash reporting **per default**. Crashes will be immediately sent to the server the next time the app is launched.
|
||||
To provide you with the best crash reporting, we are using [PLCrashReporter]("https://github.com/plausiblelabs/plcrashreporter") in [Version 1.2 / Commit 273a7e7cd4b77485a584ac82e77b7c857558e2f9]("https://github.com/plausiblelabs/plcrashreporter/commit/273a7e7cd4b77485a584ac82e77b7c857558e2f9").
|
||||
|
|
@ -297,10 +342,10 @@ This feature can be disabled as follows:
|
|||
[[MSAIApplicationInsights sharedInstance] setCrashManagerDisabled:YES]; //disable crash reporting
|
||||
|
||||
[MSAIApplicationInsights start]; //start using the SDK
|
||||
|
||||
```
|
||||
|
||||
## <a name="additionalconfig"></a>10. Set Custom Server Endpoint
|
||||
<a name="additionalconfig"></a>
|
||||
## 10. Set Custom Server Endpoint
|
||||
|
||||
You can also configure a different server endpoint for the SDK if needed using a full URL
|
||||
|
||||
|
|
@ -310,12 +355,12 @@ You can also configure a different server endpoint for the SDK if needed using a
|
|||
[[MSAIApplicationInsights sharedInstance] setServerURL:@"https://YOURDOMAIN/path/subpath"];
|
||||
|
||||
[MSAIApplicationInsights start]; //start using the SDK
|
||||
|
||||
```
|
||||
|
||||
<a id="documentation"></a>
|
||||
## 11. Documentation
|
||||
|
||||
Our documentation can be found on [CocoaDocs](http://cocoadocs.org/docsets/ApplicationInsights/1.0-beta.2/)
|
||||
Our documentation can be found on [CocoaDocs](http://cocoadocs.org/docsets/ApplicationInsights/1.0-beta.3/)
|
||||
|
||||
|
||||
<a id="contributing"></a>
|
||||
|
|
@ -333,4 +378,4 @@ We're looking forward to your contributions via pull requests.
|
|||
<a id="contact"></a>
|
||||
## 13. Contact
|
||||
|
||||
If you have further questions or are running into trouble that cannot be resolved by any of the steps here, feel free to contact us at [AppInsights-iOS@microsoft.com](mailto:AppInsights-ios@microsoft.com)
|
||||
If you have further questions or are running into trouble that cannot be resolved by any of the steps here, feel free to open a Github issue here or contact us at [AppInsights-iOS@microsoft.com](mailto:AppInsights-ios@microsoft.com)
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче