BMSAnalytics

Build Status Codacy Badge Coverage Status Platform CocoaPods Compatible

BMSAnalytics is the analytics and logger component of the Swift SDKs for IBM Bluemix Mobile Services.

Table of Contents

Summary

BMSAnalytics is the client SDK for the Mobile Analytics service on Bluemix. This service provides insight into how your apps are performing and how they are being used. With BMSAnalytics, you can gather information about your app’s usage such as unique users, app lifecycle duration, roundtrip time of network requests, crashes, and any additional information or events that you choose to log.

This SDK is also available for Android and Cordova.

Read the official documentation for more information about getting started with Mobile Analytics.

Requirements

  • iOS 8.0+ / watchOS 2.0+
  • Xcode 7.3, 8.0
  • Swift 2.2 - 3.0
  • Cocoapods or Carthage

Installation

The Bluemix Mobile Services Swift SDKs can be installed with either Cocoapods or Carthage.

Cocoapods

To install BMSAnalytics using Cocoapods, add it to your Podfile. If your project does not have a Podfile yet, use the pod init command.

use_frameworks!

target 'MyApp' do
    pod 'BMSAnalytics'
end

Then run the pod install command, and open the generated .xcworkspace file. To update to a newer release of BMSAnalytics, use pod update BMSAnalytics.

For more information on using Cocoapods, refer to the Cocoapods Guides.

Xcode 8

When installing with Cocoapods in Xcode 8, make sure you have installed Cocoapods 1.1.0 or later. You can get the latest version of Cocoapods using the command sudo gem install cocoapods.

If you receive a prompt saying Convert to Current Swift Syntax? when opening your project in Xcode 8 (following the installation of BMSAnalytics), do not convert BMSAnalytics, BMSCore, or BMSAnalyticsAPI.

Carthage

To install BMSAnalytics with Carthage, follow the instructions here.

Add this line to your Cartfile: 

github "ibm-bluemix-mobile-services/bms-clientsdk-swift-analytics"

Then run the carthage update command. Once the build is finished, add BMSAnalytics.framework, BMSCore.framework and BMSAnalyticsAPI.framework to your project (step 3 in the link above).

Xcode 8

For apps built with Swift 2.3, use the command carthage update --toolchain com.apple.dt.toolchain.Swift_2_3. Otherwise, use carthage update.

Example Usage

View the complete API reference here.

–

Import the modules

import BMSCore
import BMSAnalytics

–

Initialize

Initialize BMSClient and Analytics. This is typically done at the beginning of the app’s lifecycle, such as the application(_:didFinishLaunchingWithOptions:) method in the AppDelegate.swift. 

BMSClient.sharedInstance.initialize(bluemixRegion: BMSClient.Region.usSouth)

Analytics.initialize(appName: "My App", apiKey: "1234", hasUserContext: true, collectLocation: true, deviceEvents: .lifecycle, .network)

–

Configure Logger and Analytics

Enable logger and analytics, and set the Logger.logLevelFilter to the level of severity you want to record. This is typically done at the beginning of the app’s lifecycle, such as the application(_:didFinishLaunchingWithOptions:) method in the AppDelegate.swift.

Analytics.isEnabled = true
Logger.isLogStorageEnabled = true
Logger.isInternalDebugLoggingEnabled = true
Logger.logLevelFilter = LogLevel.debug

–

Set the app user’s identity

If your app’s users log in with a username, you can track each user with Analytics.userIdentity. To use this feature, you must have set the hasUserContext parameter to true in the Analytics.initialize() method first, as shown in the Initialize section.. If you set hasUserContext to false, BMSAnalytics will automatically record user identities anonymously by treating each device as one unique user.

Analytics.userIdentity = "John Doe"

–

Log the user’s current location

Before using this feature, you first need to import CoreLocation and get permission from the user to monitor their location using the requestWhenInUseAuthorization() method from CLLocationManager.

To have BMSAnalytics automatically record the user’s location, set the collectLocation parameter to true in the Analytics.initialize() method, as shown in the Initialize section. Once this parameter is set, you can log the user’s current location yourself at any time while the app is in an active state by calling Analytics.logLocation().

–

Log some other information

Create a Logger instance and log messages anywhere in your application, using an appropriate severity level.

let logger = Logger.logger(name: "My Logger")

logger.debug(message: "Fine level information, typically for debugging purposes.")
logger.info(message: "Some useful information regarding the application's state.")
logger.warn(message: "Something may have gone wrong.")
logger.error(message: "Something has definitely gone wrong!")
logger.fatal(message: "CATASTROPHE!")

// The metadata can be any JSON object
Analytics.log(metadata: ["event": "something significant that occurred"])

By default the Bluemix Mobile Service SDK internal debug logging will not be printed to Xcode console. If you want to see BMS debug logs, set the Logger.isInternalDebugLoggingEnabled property to true.

–

Send the data to the server

Send all recorded logs and analytics data to the Mobile Analytics service. This is typically done at the beginning of the app’s lifecycle, such as the application(_:didFinishLaunchingWithOptions:) method in the AppDelegate.swift.

Logger.send(completionHandler: { (response: Response?, error: Error?) in
    if let response = response {
        print("Status code: \(response.statusCode)")
        print("Response: \(response.responseText)")
    }
    if let error = error {
        logger.error(message: "Failed to send logs. Error: \(error)")
    }
})

Analytics.send(completionHandler: { (response: Response?, error: Error?) in
    if let response = response {
        print("Status code: \(response.statusCode)")
        print("Response: \(response.responseText)")
    }
    if let error = error {
        logger.error(message: "Failed to send analytics. Error: \(error)")
    }
})

–

Disable logging output for production applications

By default, the Logger class will print its logs to Xcode console. If is advised to disable Logger output for applications built in release mode. In order to do so add a debug flag named RELEASE_BUILD to your release build configuration. One way of doing so is adding -D RELEASE_BUILD to the Other Swift Flags section of the project build configuration.

–

In app feedback mode

Users and Testers can record and send feedback and bug reports ‘In-app’, as they run and use the application. App owners get a deeper sense of the application’s user experience with this context rich user feedback. Developers on the other hand receive accurate application contexts to diagnose and fix bugs / feature deficiencies.

Applications can invoke feedback mode on any application event such as buttons, menu actions or gestures on calling the method:


--------

## License

Copyright 2016 IBM Corp.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.