Menu

iOS Analytics Documentation

1. App Settings

Authorizations

The SDK requires two authorizations:

  1. Location (Always)
  2. Motion
  3. Background App Refresh (implicit)

By default both authorizations are requested from the user when you call start the first time.

Location

To function properly the SDK requires the ‘Always’ location permission.
If given only the ‘When-in-use’ permission the app will still track locations but will stop doing so approx. 3 min after the user closes the app (sends the app to the background).

If you want to request the permissions at another/earlier time you can do so by simply instantiating a CLLocationManager and calling requestAlwaysAuthorization at any time.

Motion

Unfortunatly, iOS provides no such way for requesting the ‘Motion authorization’ - it is automatically requested when you start gathering motion data the first time.

Background App Refresh

This is not really a permission, but needs to be handled anyway, since the user may disable this functionality within Settings -> Background App Refresh. With this setting being turned off the SDK will not function correctly. This is why we recommend implementing a notification listener as follows and display an alert if the user changes the setting:

NotificationCenter.default.addObserver(self,
                                       selector: #selector(self.applicationBackgroundRefreshStatusDidChange(notification:)),
                                       name: .UIApplicationBackgroundRefreshStatusDidChange,
                                       object: nil)

2. Dependencies

pod 'AFNetworking', '~> 2.6.3'
pod 'AFNetworkActivityLogger'
pod 'Underscore.m', '~> 0.2.1'
pod 'CocoaLumberjack/Swift'
pod 'Godzippa', '~> 1.1.0'
pod 'DeviceUtil', '~> 1.2'
pod 'JSONAPI', '~> 1.0.6'
pod 'SimpleKeychain'

3. Interface

public enum MTDataTransferMode : UInt {

    case dataTransferModeWifiOnly
    case dataTransferMode3G
}

open class MotionTagCore : NSObject {

    open class func sharedInstance(withToken token: String?, settings settingsDict: [AnyHashable : Any]?, completion: (() -> Swift.Void)? = nil) -> (NSObjectProtocol & MotionTag)!
    open func setDelegate(_ delegate: MotionTagDelegate?)
}

public protocol MotionTagDelegate : NSObjectProtocol {

    optional public func locationManager(_ locationManager: CLLocationManager, didChange status: CLAuthorizationStatus)
    optional public func didTrackLocation(_ location: CLLocation)
    optional public func didTransmitData(_ transmissionTimestamp: Date)
}

public protocol MotionTag {

    public var isTrackingActive: Bool { get }
    public var trackingActiveAsInt: NSNumber! { get }
    weak public var delegate: MotionTagDelegate! { get set }

    public func start(withToken token: String?)
    public func start(withToken token: String?, settings settingsDict: [AnyHashable : Any]?)
    public func stop()
}


4. Setup

Initialize the library via the singleton method:

	let motionTag = MotionTagCore.sharedInstance(withToken: TOKEN_OR_NIL, settings: SETTINGS_OR_NIL){
	// continue with setup here
	}

This needs to be done somewhere near the top of didFinishLaunchingWithOptions. The reason is that the app may be started from the background by the system. By initializing the tracking library early, you guarantee that all location managers are set up to retreive new incoming locations. Since the SDK may need additional time to finalize its initialization (e.g. necessary data migrations that have to be run on startup) the init call is asynchronous. The completion block will be called by the SDK once it is done with everything. Please do not call SDK functions before this block has been run since all calls will be ignored.
The library will recognize if it has already been started and act accordingly. Please be advised that if your have acquired a valid token in a previous start, you should pass it as a parameter here, otherwise pass nil. The settings parameter can also be an NSDictionary or nil. For more info see the Settings section below.

If you want to receive callbacks, set the appropriate delegate (MotionTagDelegate):

	motionTag.delegate = self

To start tracking, just call the startWithToken:settings: method:

	motionTag.start(withToken:"A_VALID_TOKEN", settings:SETTINGS_OR_NIL)

To stop tracking, just call the stop method:

	motionTag.stop()

5. Settings

Both, sharedInstance(withToken: , settings: ) and start(withToken: , settings: ) accept an NSDictionary as a parameter - if you pass in nil the SDK will fall back to default values. The settings described in this section cannot be changed while the SDK is running. So you will have stop the tracking (motionTag.stop()) before changing the settings and finally call start(withToken: , settings: ) with the modified settings to re-start the tracking. You would then also pass these modified settings into the sharedInstanceWithToken:settings:completion: method on the next start of your application - so it makes sense to persist the settings within your app.

The following options are available:

Example:

let settings:[String:AnyObject] = [kMTDataTransferMode:kDataTransferMode3G.rawValue as AnyObject,
									kMTBatterySavingsMode:true as AnyObject]
let motionTag = MotionTagCore.sharedInstance(withToken: TOKEN_OR_NIL, settings: settings, completion: {
				...
			})
...			
motionTag.stop()

let settings:[String:AnyObject] = [kMTDataTransferMode:kDataTransferModeWifiOnly.rawValue as AnyObject,
									kMTBatterySavingsMode:true as AnyObject]
motionTag.start(withToken: "A_VALID_TOKEN", settings: settings)

6. Callbacks

Optional

 locationManager(_ locationManager: CLLocationManager, didChange status: CLAuthorizationStatus)

If the user changes the location authorization status of the app this callback will be called.

didTrackLocation(_ location: CLLocation)

Gets called whenever the SDK tracks a new location.

didTransmitData(_ transmissionTimestamp: Date)

Gets called whenever the SDK has successfully transmitted a data package to the backend.

7. Example

Checkout the “Example” folder here for an example application.

8. Debugging

SDK versions

If you want to run your app on the simulator during development, you need to include the CoreDebug version of the SDK. In addition to the armv7 and arm64 symbols this SDK version includes x86_64 symbols, which are necessary to run it on the simulator.

pod 'MotionTagLib/CoreDebug', git: "https://gitlab.com/motiontag-dist/tracker-library-ios.git"

For the release of your app make sure to include the SDK’s release version, which has beend stripped of the arm64 symbols:

pod 'MotionTagLib', git: "https://gitlab.com/motiontag-dist/tracker-library-ios.git"

API endpoints

Normally the SDK processes against MotionTag’s production backend environment. If you need to debug and have setup staging with the MotionTag team, you can make the SDK send data to the staging backend by supplying the following key/value pair in your app’s Info.plist

<key>API_ENDPOINT</key>
<string>staging</string>