SkyPath

public class SkyPath

Use a shared instance SkyPath.shared. An entry point for work with the SDK. Set SkyPath.shared.delegate to get callbacks from the SDK when a new data is available, or an error etc. SDK should be started by calling start(...) method before it can record, fetch and provide data. To get data you can use query-based methods like turbulence(with:). See each function and property description as well as separate documentation available for more details on usage.

Start

  • Shared instance that should be used for all operations.

    Declaration

    Swift

    public static let shared: SkyPath
  • Implement SkyPathDelegate methods to get notified when new data has been received from the server. This will be a good place to query turbulence data and update layers on the map. All methods will be called on the main thread.

    Declaration

    Swift

    public weak var delegate: SkyPathDelegate?
  • Start SDK. It will not track and provide data until started. Should be called when SkyPath service needs to start (for example on app start) only once until app is relaunched or after it was explicitly stopped by SkyPath.stop(). The network connection is required for the very first start as it will validate the key on the server.

    Declaration

    Swift

    public func start(apiKey: String,
                      airline: String,
                      userId: String,
                      env: Environment? = nil,
                      completion: @escaping (_ error: StartError?) -> Void)

    Parameters

    apiKey

    The API key provided to you by SkyPath.

    airline

    The company’s ICAO code is registered in the SkyPath system.

    userId

    Any user identifier unique per company. Does not need to be registered in the SkyPath system.

    env

    Set it when the SkyPath server is not whitelisted and a proxy server should be used, or when need dev env. Optional. Default is production.

    completion

    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.

  • Check if SDK has been started already or not. Can be used before calling start().

    Declaration

    Swift

    public var isStarted: Bool { get }
  • Stops all SDK activities including communication with the server and turbulence detection. The cached data is deleted. Can be called if need to stop SkyPath service while the app is running for example when the pilot is logged out from the app, or the service should be stopped per the configuration, etc. Callingstart() is required to start working again after stopping.

    Declaration

    Swift

    public func stop()

Data

  • Configures what, how, and when data should be fetched from the server. All parameters have default values, so by default, it’s DataQuery() You can update data query at any time and in both ways by setting a property only or a whole object. At first request, the whole data according to SkyPath.dataQuery is fetched and then only the new data that appeared (delta) is fetched to save network traffic. When cached data expires or a delta can’t be received, the whole fresh data will be received again. When you change some query parameters SDK will start fetching fresh data immediately if needed. No need to force fetch manually. See more details on a separate documentation page.

    Declaration

    Swift

    public var dataQuery: DataQuery { get set }
  • It controls time intervals to fetch data for global turbulence polygons, route polygons, and viewport. However, when the data query route polygon or the viewport is changed, they are fetched as fast as possible not waiting for the next time interval. To save network traffic, you can set it to none to disable periodic new data fetch from the server at all or set it to minimal to update with bigger time intervals. Can be updated at any time in the project. Value is stored across app launches until changed. Default is fast.

    Declaration

    Swift

    public var dataUpdateFrequency: DataUpdateFrequency { get set }
  • It determines the data history to be fetched from the server. So if it is set to .twoHours for example (the default one), there will be no data locally available for more than 2 hours ago. If need 4 hours of history, set SkyPath.dataHistoryTime to .fourHours. When started, SDK fetches initial data from time back in time and then receives only updates since the last update. Changing from lower time to higher will require an API request to fetch data, when changing from higher to lower time, data could be available immediately as it was already included in the higher history time fetch. Alternatively, time can be set to .sixTime once to fetch 6 hours of history data always and then just query with a different time history to show on the map. Please note, that it will increase network traffic but will allow having more data available immediately and offline during changing time history. Default is twoHours.

    Declaration

    Swift

    public var dataHistoryTime: DataHistoryTime { get set }
  • Last date when successfully received new data from the server.

    Declaration

    Swift

    public var dataUpdatedAt: Date? { get }
  • Data is automatically fetched from the server by SDK out of the box, as well on changing data in dataQuery or dataUpdateFrequency. Use this function to let SDK fetch new data from the server immediately. Do not call it frequently. A recommended usage is to call it when the pilot taps a refresh button if it is such. The fetched data result will be notified in corresponding delegate methods.

    Declaration

    Swift

    public func fetchData(refresh: Bool = false)

    Parameters

    refresh

    If true, all data per query will be fetched.

  • Get if specific area data is currently fetching from the server or not. The change of status is also notified via SkyPathDelegate.didUpdateFetchingStatus(fetching:areaType).

    Declaration

    Swift

    public func fetchingStatus(for areaType: DataAreaType) -> Bool

    Parameters

    areaType

    Area type to check fetching status.

Turbulence

  • Get turbulence data using a query in locally cached data without making a server request. 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.

    SkyPath.shared.dataHistoryTime determines the data history to be fetched from the server. By default, it is .twoHours. So if it was not changed and query for .fourHours for example, there will be data only up to 2 hours because no more data was fetched from the server.

    H3 resolution 5 is used by SkyPath for the turbulence reports area. Each turbulence report covers ~252.9 square km hexagon area (as per the H3 resolutions table) and 1000 feet of altitude. Each hexagon is connected to the other so this allows for covering the area better. So one turbulence report covers for example FL370..<FL380 or FL380..<FL390.

    Declaration

    Swift

    public func turbulence(with query: TurbulenceQuery) -> Result<TurbulenceResult, QueryError>

    Parameters

    query

    Specify query parameters per your needs. See TurbulenceQuery docs for details.

  • Get turbulence polygons data using a query in locally cached data without making a server request. SDK fetches data from the server and caches it locally automatically. Use TurbulencePolygonsQuery to get filtered data as a GeoJSON string. It will query locally cached data received previously. It blocks the current thread, so using a separate background thread is recommended.

    SkyPath.shared.dataHistoryTime determines the data history to be fetched from the server. By default, it is .twoHours. So if it was not changed there are no polygons data for .fourHours for example. This is because polygons data is generated per each history time separately, so SDK needs to have it cached to return.

    Declaration

    Swift

    public func turbulencePolygons(with query: TurbulencePolygonsQuery) -> Result<TurbulencePolygonsResult, QueryError>

    Parameters

    query

    Specify query parameters per your needs. See TurbulencePolygonsQuery docs for details.

Alert

  • Get alerts manually when needed. Alerts will be searched in locally cached data received per SkyPath.dataQuery configuration. No server request will be made here. You can call it when needed, for example, on every location update, or by time intervals or distance passed. This will have all currently found turbulence alerts despite whether they were found in the previous query. It blocks the current thread, so using a separate background thread is recommended.

    Declaration

    Swift

    public func alerts(with query: AlertQuery = AlertQuery()) -> Result<AlertResult, AlertError>

    Parameters

    query

    Control how to search for a turbulence alert. See AlertQuery for more details.

    Return Value

    Alerts found result. See AlertResult for more details.

  • Automatic monitoring. SDK will check for turbulence on every new location update. When found, an alert will be reported via SkyPathDelegate.didReceiveAlert(alert:). This will not report the same turbulence alert multiple times in a row, but it could report the same alert that was reported previously if there were other alerts in between. So it will report only once in cases A1 A1 A1 A1 but will report 3 times in cases A1, A2, and A1.

    Based on the AlertQuery properties, SDK filters server reports. All AlertQuery properties have default values. Configure it per your needs. There are two modes: route and beam.

    • Route mode is used when route line coordinates or a polygon are set in the query. It can use polygon or route line coordinates and width around to make a corridor.
    • Beam mode is used when no route is provided. It is configured by angle span, and distance from the current location. When got a turbulence alert you can show it in the app with the local iOS notification if the app is in the background.

    It is safe to call startMonitoringAlerts multiple times. However, it works as enable disable, so no need to call it again after starting monitoring until stopped monitoring and needs to start again. You can also check SkyPath.shared.isMonitoringAlerts if need to call startMonitoringAlerts or stopMonitoringAlerts. When the AlertQuery changes you can call only startMonitoringAlerts(with:) with a new query without stopping it first.

    Declaration

    Swift

    public func startMonitoringAlerts(with query: AlertQuery = AlertQuery())

    Parameters

    query

    Control how to search for a turbulence alert. See AlertQuery(forMonitoringTime:) for more details. Current location details like lat, long, altitude, and heading will be taken dynamically. Optional.

    Return Value

    Alerts found result. See AlertResult for more details.

  • Stop monitoring alerts in an automatic mode.

    It is safe to call stopMonitoringAlerts multiple times. However, monitoring works as enabled and disable, so no need to call again after stopping. You can also check SkyPath.shared.isMonitoringAlerts if need to stop.

    Declaration

    Swift

    public func stopMonitoringAlerts()
  • Check if auto monitoring has been started or it’s stopped/not started.

    Declaration

    Swift

    public var isMonitoringAlerts: Bool { get }

Aircraft

  • Set a current aircraft type using supported types from the SDK. Should not be nil. When it is not set the turbulence data will not be fetched from the server..

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

    Usage example:

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

    Declaration

    Swift

    public var aircraft: Aircraft? { get set }
  • Get all aircraft supported by SkyPath.

    Declaration

    Swift

    public func aircrafts() -> [Aircraft]

    Return Value

    Aircraft objects supported by SkyPath.

  • Get an Aircraft by an id (ICAO code). Same as Aircraft(id:).

    Declaration

    Swift

    public func aircraft(byId id: String) -> Aircraft?

    Parameters

    id

    An ICAO id of the aircraft type.

    Return Value

    Found aircraft matched id or default if no found by id.

Flight

  • Update the current flight details. Flight is saved even across app launches. Call it when a flight is set or updated, or removed in the app. Recoding data requires a flight when getting turbulence data, and other data is available without a flight. Usage example:

    let flight = Flight(dep: "ICAO", dest: "ICAO", fnum: "FLIGHT_NUMBER")
    SkyPath.shared.startFlight(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.

    Declaration

    Swift

    public func setFlight(_ flight: Flight?)

    Parameters

    flight

    Flight details object. Pass nil when a flight is finished. See Flight for more details.

  • Current flight if any set by startFlight(_:).

    Declaration

    Swift

    public var flight: Flight? { get }

Settings

  • Set when toggle SkyPath layer visibility, when showing or hiding the layer on the map.

    Declaration

    Swift

    public func setMapLayer(enabled: Bool)

    Parameters

    enabled

    If SkyPath map layer is enabled or not.

  • Background location access is required to track turbulence and show notifications.

    Declaration

    Swift

    public var allowsBackgroundLocationUpdates: Bool { get set }
  • SDK version.

    Declaration

    Swift

    public var version: String { get }
  • env

    Current evironment.

    Declaration

    Swift

    public var env: Environment? { get }
  • If the device is in position.

    The app auto-calibrates on its own now, we show the notification that it is calibrating and ready to record. When moved around, the app stops the recording but we do not show any note, since it could be intended. Following a minute in a stable position, the app recalibrates and will be ready to record again. Data is not recorded when the iPad is horizontal. You can show a notification to the pilot on why it is not recording.

    Declaration

    Swift

    public var inPosition: Bool { get }
  • Data is not recorded when the iPad is horizontal. You can show a notification to the pilot on why it is not recording.

    Declaration

    Swift

    public var isHorizontal: Bool { get }
  • If there is a noise at the moment like moving the device out of the position. Data is not recorded when the iPad is in noise.

    Declaration

    Swift

    public var inNoise: Bool { get }
  • SDK has an internal logging system to help with debugging and solving issues. SDK logs are stored in their own files along with other files used by the SDK.

    Declaration

    Swift

    public var logger: Logger { get }

Simulator

  • In simulation mode, you can pass the simulated location to the SDK via simulateLocation(:) for testing purposes only.

    Recording turbulence works only in the air, so SDK provides a simulation mode to test it on the ground. Use it for DEV ENV only. It can be set by env: .dev(serverUrl: nil) in SkyPath.start(). By default when no env parameter is passed, the production server is used.
    You can have some hidden developer options to enable/disable simulation mode for QA testing. Simulation mode can be enabled/disabled at any time.

    Declaration

    Swift

    public func enableSimulation(_ enabled: Bool)

    Parameters

    enabled

    If simulation mode is enabled.

  • Provide a simulated location for testing only. Should be set to simulation mode by enableSimulation(:).

    Provide your own simulated location. The simplest way is to have an array of CLLocationCoordinate2D on the same in air altitude and pass it by a timer with 1-second time intervals.
    You can use your flight simulation as well.

    Declaration

    Swift

    public func simulatedLocation(_ location: CLLocation)

    Parameters

    location

    A simulated location for testing.

  • Enable SDK to send turbulence and events to the server. Otherwise simulated events will not be sent. The default is disabled.

    Declaration

    Swift

    public func enablePushSimulated(_ enabled: Bool)

    Parameters

    enabled

    Wheather to send data tracked in simulation mode to the server.

  • Trigger a turbulence event by using a timer at some time intervals, or randomly during some time, or just by having a test button or your own event to trigger. Turbulence will not be tracked on the ground, so need an air-simulated location.

    Declaration

    Swift

    public func simulateTurbulence(sev: TurbulenceSeverity)

    Parameters

    sev

    Turbulence severity level to simulate an event for.

  • Simulate bad location by dropping location updates.

    Declaration

    Swift

    public func simulateBadLocation(_ enabled: Bool)

    Parameters

    enabled

    Bad location simulation enabled or disabled.

  • If simulate bad location is currently enabled or not.

    Declaration

    Swift

    public var simulateBadLocation: Bool { get }