How to integrate the Quandopasso SDK into your application

Preliminary notes and general requirements

Quandopasso SDK has been implemented in Swift and can be integrated as a Framework in both Swift and Objective C projects.

The SDK depends on the following packages, which nned to be installed into the main project using the dependency manager of your choice.

The following is a Carthage file with the dependency package names along with the required versions:

github "xmartlabs/Eureka" ~> 5.0
github "ReactiveX/RxSwift" ~> 5.0
github "Alamofire/Alamofire" ~> 4.8
github "emaloney/CleanroomLogger" ~> 6.0.0
github "hkellaway/Gloss"
github "rwbutler/Connectivity"

The released QuandoPassoLib.framework file can then be linked to your Xcode project from the Linked Frameworks and Library section in the General settings, along with the dependency libraries listed above and any other dependency your project may have.

Usage

Initialise and start the QPEngine instance

After you link QuandoPassoLib.framework to your XCode project, the first step to use its functionalities is to create an instance of the QPEngine class, optionally passing to the constructor a QPSettings object to control its behaviour.

Then, you can call the askPermission() method to require the needed permissions in order to use the GPS and the Notifications modules.

Finally, you can call the start() method to start the QPEngine, which will in turn start tracking location updates using the GPS module, fetching vSigns from the Quandopasso API, and emitting events when vSigns are entered.

The example usage below is written in Swift, but the same concepts apply in Objective C:

override func viewDidLoad() {
    super.viewDidLoad()

    let qpEngine = QPEngine()

    qpEngine.askPermission()
    qpEngine.start()
}

How to receive event notifications and implement your custom app logic

The QuandoPasso SDK uses the popular Delegate pattern to let you perform custom logic for the events you care about.

As an example, this is how you would use the Delegate pattern to perform some custom actions:

// Note that our view implements the QPManagerDelegate protocol
class ViewController: UIViewController, QPManagerDelegate {

    override func viewDidLoad() {
        super.viewDidLoad()

        let qpEngine = QPEngine()

        // This line sets the delegate object to the current class, so that the qpManager method gets called by the SDK.
        // To make sure no events gets lost, it is recommended to always set the delegate before calling the .start() method.
        qpEngine.delegate = self

        qpEngine.askPermission()
        qpEngine.start()
    }

    // This is the delegate method called when noteworthy events are emitted by the Quandopasso SDK.    
    func qpManager(event: QPEvent) {
        switch event {
        case let ev as QPNotifiedVSignEvent:
            print("User entered vSign with id \(ev.signal.id)")
        case let ev as QPLocationUpdatedEvent:
            print("User location updated. New location: \(ev.currentLocation)")
        default:
            return
        }
    }
}

The following events are emitted by the Quandopasso SDK:

• QPEngineStarted: triggered when the Engine receives the first GPS update, which is required to perform the initial operations.

• QPConnectivityChangedEvent: triggered when the network status changes, e.g. from connected to disconnected.

• QPLocationUpdatedEvent: triggered when the Engine receives a GPS update from the system module.

• QPEnteredVSignEvent: triggered when the Engine detects the user has entered a VSign.

• QPNotifiedVSignEvent: triggered when a VSign has been notified to the user.

• QPVSignsFetchedEvent: triggered when the Engine fetches the list of vSigns from the API.

• QPExitedApiCoverageRegionEvent: triggered when the Engine detects that the user has exited the circular region coveder by the latest API call to fetch the relative vSigns.

• QPResetVSignStatus: triggered when the vSign notified status has been reset.

• QPGPSUpdatesPaused: triggered when iOS notified the Engine that GPS updates have been suspended because of inactivity.

For details about each specific event and the properties assigned to it, please refer to the code documentation.

Settings

enableTextToSpeech

Controls if vsign messages are read by the TTS service

apiBaseUrl

apiDomain

apiPollInterval

Controls how often (in seconds) we poll the API for new vSigns. Note that apart from polling, vsigns are fetched when the coverage geofence is exited.

Default value: 30

apiCoverageRadius

Value (in meters) passed to the API as the vsign coverage radius. A value of 1000 would ask the API to give us all vsigns in the given radius.

Default value: 5000

bearingToleranceDegrees

Value in degrees controlling the tolerance for the angle used to detect the entering direction for a vsign

Default value: 60

enableBearingChecks

Controls if the entering angle should be used when detecting if a visgin is being entered

Default value: true

gpsLocationMaxAgeSeconds

GPS updates older than this value (in seconds) will be discarded as outdated. Useful to discard out of date locations when the GPS doesn’t work properly.

Default value: 10

gpsLocationMinHorizontalAccuracy

GPS updates that fall outside of this accurancy range (in meters) will be discarded as too inaccurate to be used. Default value: 100

notifiedTimeoutSeconds

Notified vSigns will be re-notified again once re-entered if the previous notification is older than this value (in seconds)

Default value: 180

notifiedMinDistanceInMeters

Notified vSigns will be re-notified again once re-entered if the user has reached this min distance (in meters) from the vsign area.

Default value: 2000

ttsVolume

Volume for the TTS messages

Default value: 1.0

language

Language used to display and read vsign messages

syncMetricsInterval

Controls how often (in seconds) buffered metrics are sent to the API

Default value: 300

gpsDefaultAccuracy

Controls how often buffered metrics are sent to the API

Default value: .kCLLocationAccuracyBestForNavigation

gpsPausesLocationUpdatesAutomatically

Automatically pauses GPS updates if the system determines updates are not strictly requires (e.g. the user hasn’t been moving for a while) to save battery.

Default value: true

gpsDistanceFilter

Controls how often GPS updates are required, based on the user movements. For example, setting this to 5 meters will make the system sends GPS update events only if the user moves outside of a 5 meter radius from their last position.

Default value: 5