iOS SDK

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 an 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 infrastructure 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 findings to improve timetables and routes, expand transport supply and attract more passengers.

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

1. Installation

To integrate the MOTIONTAG Tracker SDK into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'MotionTagSDK'

You can also integrate a specific version:

pod 'MotionTagSDK', '~> 4.3.1'

2. Changelog

You can find the latest SDK version in our changelog page.

3. Native sample app

A native iOS sample app can be found on our GitHub page: https://github.com/MOTIONTAG/motiontag-sample-app-ios This sample app showcases the best practices in integrating the SDK into native iOS apps.

4. Required App Settings

• Capabilities -> Background Modes:

  • Location Updates

• Add to Info.plist:

  • "Privacy - Motion Usage Description" string
  • "Privacy - Location Always & When in Use Description" string
  • "Privacy - When in Use Description" string
  • "Privacy - Bluetooth Always Usage Description" string

• The SDK does not use Bluetooth except for certain clients. However, the presence of BT code in the SDK necessitates the inclusion of this purpose string.

• The minimum deployment target is 12.3.

5. Authorizations

The SDK requires two authorizations:

1. Location (Always)
2. Motion

Both would be need to be obtained by your app before calling the start method the first time.

Location

On iOS > 13.5, the "Always" authorization can be obtained by obtaining the "While Using" authorization, and elevating it to "Always" right away as demonstrated in our sample app.

Motion

The "Motion authorization" is not essential, but it is recommended for improved battery usage. Unfortunately, iOS provides no such way for requesting "Motion authorization" - it is automatically requested when you start gathering motion data the first time. This is also demonstrated in the sample app.

6. SDK user authentication

The SDK must be configured at runtime with a user-specific token.

Tokens can be generated on your backend, or manually with the form below (only accessible when signed in). They are signed JWTs (see jwt.io). Users are identified by distinct UUIDs – the creation and management of the user UUIDs is up to you. MOTIONTAG creates a user entry in its database when data from the SDK for a new user UUID arrives for the first time.

To generate the JWTs on your backend, encode and sign a payload like the example below with the shared secret, which is accessible in the admin dashboard under "Authentication tokens". Include these claims:

• iss claim: the tenant key that you have received from MOTIONTAG
• sub claim: the user UUID
• exp claim: expiry integer timestamp (optional)

Example payload:

{
  "iss": "my-tenant-key",
  "sub": "aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb"
}

To create tokens in your backend, use the shared secret available under Authentication tokens

7. Interface

The MotionTag protocol is the main entry point of the SDK. The singleton instance to this protocol can be obtained by: let motionTag: MotionTag = MotionTagCore.sharedInstance and interacting with it through the following public methods and properties

It also contains the following public properties:

The MotionTagDelegate has both optional and required methods:

8. Using the SDK

8.1 Initialization

A basic initialization of the SDK, directly from the AppDelegate would look like:

import UIKit
import MotionTagSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    let motionTag: MotionTag = MotionTagCore.sharedInstance

    func application(_: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        motionTag.initialize(using: self, launchOption: launchOptions)
        return true
    }

    func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void) {
        motionTag.handleEvents(forBackgroundURLSession: identifier, completionHandler: completionHandler)
    }
}

extension AppDelegate: MotionTagDelegate {

    func trackingStatusChanged(_ isTracking: Bool) {
        print("MotionTag SDK trackingStatusChanged: \(isTracking)")
    }

    func locationAuthorizationStatusDidChange(_ status: CLAuthorizationStatus, precise: Bool) {
        print("MotionTag SDK CLAuthorizationStatus: \(status.rawValue) precise: \(precise)")
    }
    // optional methods:
    func motionActivityAuthorized(_ authorized: Bool) {
        print("MotionTag SDK motionActivityAuthorized: \(authorized)")
    }

    func didTrackLocation(_ location: CLLocation) {
        print("MotionTag SDK didTrackLocation - CLLocation: \(location)")
    }

    func dataUploadWithTracked(from startDate: Date, to endDate: Date, didCompleteWithError error: Error?) {
        let errorText = error == nil ? "successfully completed" : error.debugDescription
        print("MotionTag SDK dataUploadWithTracked - startDate: \(startDate), endDate: \(endDate)", errorText)
    }
}

It is crucial that the initialization happens as early as possible in the didFinishLaunchingWithOptions delegate call of the app. 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 retrieve new incoming locations.

Also, the AppDelegate's handleEventsForBackgroundURLSession method needs to be implemented and the SDKs handleEvents(forBackgroundURLSession: ... called as shown above.

If you're using FirebaseAnalytics, you need to call its handleEvents(forBackgroundURLSession .... here as well. Moreover addFirebaseAppDelegateProxyEnabled to your App's Info.plist and set its value to NO. Please see FIRAnalytics(AppDelegate) .

This goes for similar frameworks which swizzle the handleEventsForBackgroundURLSession method by default.

8.2 Start tracking

To start tracking, first a valid user token (JWT) needs to be set. Otherwise, the events would not get transmitted to the server.

motionTag.userToken = "A_VALID_JWT"

The token does not need to be set on every initialization, as the SDK keeps it in the keychain. This property can be used to retrieve the token when necessary. It is initially nil.

After that, the start() method should be called to activate tracking:

motionTag.start()

8.3 Stop tracking

To stop tracking, just call the stop method:

motionTag.stop()

8.4 Tracking state

The SDK preserves the tracking state across app and device restarts, therefore we recommend only calling the start and stop functions when the user manually enables or disables tracking in the App UI.

IMPORTANT: The token is user-specific and should not be used on multiple devices at the same time.

9. License

The SDK is licensed under the MOTIONTAG SDK Test License.

10. Open Source Software Licenses

The SDK relies on Open Source Software components. See their respective Open Source Licenses.