The GiPStech MDK is developed in Kotlin Multiplatform and exported to Swift via SKIE (si apre in una nuova scheda), making it available as an XCFramework for integration into a pure iOS Swift application. As a result, there are a few integration-specific aspects to keep in mind.
Singleton
Sezione intitolata “Singleton”In Kotlin, you can define a singleton using the object keyword, which ensures that only one instance of the class exists. Swift, on the other hand, does not have a built-in object construct for singletons.
To achieve similar behavior in Swift, SKIE (si apre in una nuova scheda) defines a static property called shared, which holds the sole instance of the class. For example, you can access the singleton instance of the GiPStech class using GiPStech.shared.
Protocols
Sezione intitolata “Protocols”If you let Xcode generate the stubs for your LocationListener class, it will produce two method signatures for each Kotlin function. For example:
func __onLocationUpdated(location: Location, completionHandler: @escaping ((any Error)?) -> Void) {}
func __onLocationUpdated(location: Location) async throws {}This happens because Kotlin’s suspend functions are asynchronous by nature, and Swift supports two different paradigms for asynchronous code:
- The modern async/await syntax, introduced in Swift 5.5.
- The traditional callback-based approach, using completion handlers.
To ensure maximum compatibility, SKIE (si apre in una nuova scheda) exposes both:
- The async throws version is recommended if you’re writing modern Swift code using structured concurrency.
- The completionHandler version is provided for compatibility with older codebases or APIs that are not async-aware.
Both versions perform the same operation under the hood, so you’re free to choose the one that best fits your architecture and remove the other.
Exceptions
Sezione intitolata “Exceptions”Kotlin exceptions are not directly mapped to Swift exceptions. When an exception is thrown from Kotlin, it is exposed in Swift as an NSError. To handle it, you need to catch the error as an NSError and access its kotlinException property.
You can then use the is operator to check whether the kotlinException is an instance of a specific subclass of GiPStechException, and safely cast it to the appropriate type if needed.
Example
Sezione intitolata “Example”do { ...} catch let error as NSError { if error.kotlinException is GiPStechException.Busy { ... } else if error.kotlinException is GiPStechException.ActivationRequired { ... }}Exception mapping
Sezione intitolata “Exception mapping”Another important aspect to consider is that all exceptions in the MDK are nested within the GiPStechException class, or even within its subclasses. Since Swift does not support this level of exception nesting, Kotlin/Native flattens the hierarchy by appending the base class name to all subclasses. For example, MdkException.Network.ServerUnreachable in Kotlin becomes MdkException.NetworkServerUnreachable in Swift.
Upcoming Changes
Sezione intitolata “Upcoming Changes”Starting with Kotlin 2.1.0, JetBrains introduced Native Swift export, a new mechanism that allows Kotlin Multiplatform libraries to be exported directly to Swift without relying on third-party tooling. At the moment, this feature is still experimental and comes with important limitations.
In particular, the current implementation does not support coroutines, which are a core part of the GiPStech MDK API and are exposed to clients for asynchronous operations. This makes Native Swift export not yet compatible with the current architecture of the library.
For these reasons, the GiPStech MDK will continue to use SKIE (si apre in una nuova scheda) for Swift interoperability until JetBrains’ Native Swift export becomes stable and provides full support for key Kotlin features such as coroutines.
We are actively monitoring the evolution of this feature and plan to migrate to the official export mechanism once it is mature enough to guarantee:
- full coroutine interoperability,
- stable Swift API generation,
- and long-term support from the Kotlin toolchain.
For more information, please refer to the official Kotlin documentation: https://kotlinlang.org/docs/native-swift-export.html (si apre in una nuova scheda)