Quick Start

Before you begin, ensure you have Installed the SkyPath iOS SDK.

1. Import SkyPathSDK

Near the top of any Swift file that uses SkyPathSDK, add the following import statement:

import SkyPathSDK

2. Set Delegate

Set your SkyPathDelegate object. All methods will be called on the main thread.

SkyPath.shared.delegate = delegate

Implement the SkyPathDelegate protocol required methods.

extension Controller: SkyPathDelegate {

    func didUpdateRecordingStatus(to recording: Bool) {
        
        print("SkyPath did \(recording ? "start" : "stop") recording")
        
        // SDK could stop recording due to an error.
        // Call SkyPath.start() to start recording again after stopped.
    }
    
    func didReceiveNewTurbulenceData(areaType: DataAreaType) {
    
        print("SkyPath did receive new turbulence data")
        
        // Query turbulence using `TurbulenceQuery` and show it on the map
        // See the "Get Turbulence" step of this guide
    }
    
    func didChangeDevicePosition(_ inPosition: Bool, horizontal: Bool) {
    
        print("SkyPath device is \(inPosition ? "" : "not ")in position and \(horizontal ? "" : "not ")horizontal")
                
        // Turbulence data is not tracked when the device is not in a position or is horizontal. 
        // Show a notice here to properly position the device in the cradle.
    }
}

These are required to implement the methods of the delegate and are enough for a quick start. You can get more details in the corresponding documentation sections.

3. Start SDK

Start SDK. It will not track and provide data until started.

SkyPath.shared.start(apiKey: "API_KEY", airline: "AIRLINE", userId: "ID", env: .dev(serverUrl: nil)) { error in
    if let error {
        // handle the error
    }
}

• API_KEY Your SkyPath API KEY (for production / staging).
• AIRLINE is a string that identifies the current using airline, i.e. or EXAMPLE_AIRLINES or Example Airaways or EXA. This string values needs to be communicated to SkyPath when onboarding new airline.
• ID is the current user unique identifier.
• .dev(serverUrl: nil) is set to use a default SkyPath development server dev-api.skypath.io.

The completion block will be called asynchronously on the main thread. error will have details in case SDK can't start. If all is good SkyPathDelegate.didUpdateRecordingStatus(to:) will be called with recording: true.

4. Setup Aircraft

warning

This is mandatory for recording and receiving data.

The turbulence severity level can be different for different aircraft types.

Set a current a/c type using supported types from the SDK after it started.

if let aircraft = SkyPath.shared.aircraft(byId: "B737") {
    SkyPath.shared.aircraft = aircraft
}

5. Set Route Corridor

After SDK started and the aircraft was set, set a route corridor to get data in.

It should be a valid GeoJSON Polygon RFC 7946. See Data for more details.

Use the following for a quick test.

// KJFK-KIAD as [lng, lat]
let corridor = [(-76.76, 37.43), (-72.55,39.50), (-72.21,40.06), (-72.26,41.33), (-72.64,41.86), (-73.51,42.28), (-74.16,42.26), (-78.15,40.46), (-79.10,39.20), (-78.80,37.96), (-77.72,37.30), (-76.76,37.43)]
.map { CLLocationCoordinate2D(latitude: $0.1, longitude: $0.0) } 

SkyPath.shared.dataQuery.polygon = corridor

6. Get Turbulence

SDK fetches data from the server and caches it locally automatically.

Use TurbulenceQuery to get filtered data as a GeoJSON string or as an array of objects. It will query locally cached data received previously. It blocks the current thread, so using a separate background thread is recommended.

do {
    let result = try SkyPath.shared.turbulence(with: TurbulenceQuery()).get()
    let geoJSON = result.geoJSON
    // Show GeoJSON on the map
} catch {
    print(error)
}

7. Set Flight

To track data, flight info is required. You can still get turbulence data without setting it. Update flight data at any time and pass nil when a flight is ended or removed.

let flight = Flight(dep: "ICAO", dest: "ICAO", fnum: "FLIGHT_NUMBER")
SkyPath.shared.setFlight(flight)

• ICAO is the airport's ICAO code.
• FLIGHT_NUMBER is a combination of the airline's ICAO code and 1-4 digit number. When there is no such number, use ORIG-DEST-GUID, where ORIG is the ICAO code of the departure airport, DEST is the ICAO code of the destination airport and GUID is a globally unique identifier.

8. Handle Errors

Process and act on the delegated errors accordingly using the following:

• SkyPathDelegate.didUpdateRecordingStatus(to:)
• SkyPathDelegate.didFailToFetchNewData(with:)
• locationManagerDidFail(withError:)

9. Whitelist

warning

This is mandatory for sending and receiving data.

By default, SDK will access api.skypath.io domain. This should be whitelisted, so SDK can receive and send data. When a domain is not whitelisted it will work as when offline.

You can use a proxy server to avoid whitelisting a SkyPath domain. It should forward all HTTPS network traffic for api.skypath.io with a wildcard * for a path. docs.skypath.io describes APIs to get data only as it's not possible to send recorded data outside of SDK. SDK will use other non-documented API endpoints, so whitelisting only those or any other fixed endpoint paths list is not sufficient.

10. Test

After completing the above steps run the project and see if the data is provided correctly. You should see some turbulence data. See Test for how to test recording.

11. Set Map Layer

Set whether the SkyPath map layer is enabled or not by calling the following when showing/hiding the SkyPath data layer on the map.

SkyPath.shared.setMapLayer(enabled: true)

Thread Safety

SkyPath.start() should be called on the main thread. Besides that, SDK is thread-safe in general and will use its own threads when needed.