Versioning
All four native SDKs — iOS, Android, Flutter, and React Native — reached 1.0 together. This page describes the compatibility promise that comes with that.
Semantic versioning
From 1.0 on, every SDK follows semantic versioning:
- Major (
1.x→2.0) — the only place breaking changes to the public API can happen. Each major ships with a migration guide. - Minor (
1.0→1.1) — new APIs, new ad formats, and new features. Existing code keeps compiling and behaving as documented. - Patch (
1.0.0→1.0.1) — bug fixes only.
During 0.x, minor releases could carry breaking changes; that ends at 1.0. The 0.x → 1.0 upgrade itself is a breaking release — each SDK's migration guide covers it: iOS, Android, Flutter, React Native.
The JavaScript (script-tag) SDK is delivered from Koah's servers and versions independently — see the JavaScript SDK docs.
What counts as public API
The stability promise covers the documented, public surface of each package: the types, functions, components, and configuration keys described in each SDK's Reference pages.
It does not cover internals, even where a language can't fully hide them: entry points named internal or internal-testing, symbols documented as internal, and undocumented behavior such as exact network timing or retry cadence. Ad formats and creative content are server-driven and evolve continuously without SDK updates — an SDK that receives a value it doesn't recognize degrades safely rather than breaking.
Deprecations
When an API is superseded inside a major, we deprecate rather than remove it: the deprecated form keeps working for the remainder of the major, a compiler or runtime warning points at its replacement, and the changelog entry documents the migration. Removal happens in the next major, never in a minor or patch.
Stable releases and prereleases
1.0.0 is stable on all four core SDKs and no longer in beta. Use the stable versions below. If you installed a 1.0 beta, replace the prerelease pin with the stable version and refresh your dependencies.
| SDK | Registry | Install the stable release |
|---|---|---|
| Android | Maven Central | implementation("com.koahlabs:koah-android:1.0.0") |
| iOS | Swift Package Manager | Select Up to Next Major Version, starting at 1.1.0, in Xcode |
| Flutter | pub.dev | koah_flutter: ^1.0.0 |
| React Native | npm | npm install --save-exact koah-react-native@1.0.1 |
The iOS and Flutter examples allow compatible stable updates within the current major version: starting at 1.0.0, both ranges exclude 2.0.0. Existing lockfiles keep their resolved versions until you update dependencies. Android and the npm command above use exact versions.
Future alpha, beta, or release-candidate versions are opt-in test releases, not the recommended production version. Pin a prerelease explicitly when testing one; do not rely on a stable version range or npm's latest tag to select it.
Need help upgrading? Email support@koahlabs.com.