Menu

iOS Analytics Documentation

The MotionTag Mobility & Location Analytics SDK collects an iPhone’s raw sensor data in a battery efficient way. This data is then transmitted to the MotionTag back-end system (ISO 27001 certified). In the backend, the sensor events are processed and a partial journey is constructed. Journeys consist either solely of tracks or tracks plus stays. Tracks describe a movement from a origin to a destination with a certain mode of transport. Stays symbolize a stationary behaviour with a particular purpose for the visit.

The use cases for the SDK are manifold. In the mobility sector it can be used to get detailed mobility data for planning purposes. The collected data enables to compare how the transport network is being used. This way the effectiveness of the current infrastructureand and the passenger flow management is measured and the design of new mobility services. By implementing and using the SDK you can make use of these learnings to improve timetables and routes, expand transport supply and attract more passengers.

If you integrate the MotionTag Tracker library inside your own application, you can either download user journeys via a provided dump interface on the internet or we tailor a customized solution to your needs.

You can find the SDK version in our changelog page.

1. App Settings

Authorizations

The SDK requires two authorizations:

  1. Location (Always)
  2. Motion

Make sure you have obtained both authorizations (e.g. in an app onboarding dialog) from your users before you call start the first time.

Location

To function properly the SDK requires the ‘Always’ location permission.

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.

Disclaimer: Since iOS 13 the users will be presented with a permission dialog, in which they will have to choose “While in Use” when requesting ‘Always’ authorization. Once the users accept the SDK will receive a provisional ‘Always’ authorization. After a while (currently after ~3 days) iOS presents another dialog to the users, which lets them decide whether they want to grant ‘full’ ‘Always’ authorization or grant the app ‘While in Use’ authorization. Only after the users select ‘Always’ in this dialog will the SDK work as intended.

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.

1. Dependencies

	pod 'CocoaLumberjack/Swift'
	pod 'Godzippa', '~> 1.1.0'
	pod 'DeviceUtil', '~> 1.2'
	pod 'JSONAPI', '~> 1.0.6'
	pod 'SimpleKeychain'

2. Interface

public enum DataTransferMode : UInt {
    case wifiOnly
    case wifiAnd3G
}

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

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


public protocol MotionTag {
    var isTrackingActive: Bool { get }
    var trackingActiveAsInt: NSNumber { get }
    weak var delegate: MotionTagDelegate? { get set }
    func start(withToken token: String?)
    func start(withToken token: String?, settings settingsDict: [AnyHashable : Any]?)
    func stop()
}



3. 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()

4. 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)

5. Callbacks

Optional

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

didTrackLocation(_ location: CLLocation)

didTransmitData(_ transmissionTimestamp: Date)

6. Example

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

7. Debugging

SDK

The SDK contains both the armv64 and the x86_64 symbols (which are necessary to run it on the simulator). When building a release version the cocoapods scripts will strip out all x86_64 symbols so that the release will be compatible with the App Store.

  pod 'MotionTagSDK', 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>