Building Android SDKs other apps can depend on
Writing code for your own app and writing code other apps depend on are different jobs. In your own app, a bad API is a refactor. In an SDK, a bad API is something every customer has to work around until you can ship a major version, and they'll upgrade on their schedule, not yours. I've built SDKs and shared UI libraries that several apps and teams use at once. These are the rules I follow.
An SDK is a promise
Everything public is a promise: every class, every function, every default value and every behavior someone can observe. People will depend on things you never meant as features. So the work is less about what the SDK can do and more about what it commits to.
Three questions I ask about every public API before it ships:
- Can I change the implementation behind it without changing the signature?
- Is the easy path the correct path? If a customer can call things in the wrong order, some of them will.
- Would I be comfortable supporting it for years? If not, it shouldn't be public yet.
Keep the public surface small
Kotlin defaults to public, which is the wrong default for a library. I turn on explicit API mode so the compiler makes us decide, every time, whether something is part of the contract:
kotlin { explicitApi()}Then I make the contract visible in code review with the binary compatibility validator. It writes the public API to a checked-in .api file, and the build fails if that file changes without someone updating it on purpose:
// build.gradle.kts (root)plugins { id("org.jetbrains.kotlinx.binary-compatibility-validator") version "0.16.3"}apiValidation { ignoredProjects += listOf("sample", "test-fixtures") nonPublicMarkers += "com.example.sdk.InternalSdkApi"}That one file changes the conversation. Instead of noticing an API change after it ships, the diff shows up in the pull request, where someone can ask whether it should be public at all.
Behind the surface, I keep the entry point small and configuration explicit. One builder, sensible defaults, and nothing global:
public class ExampleSdk private constructor( internal val config: SdkConfig,) { public class Builder(private val context: Context) { private var environment: Environment = Environment.Production private var logger: SdkLogger = SdkLogger.None public fun environment(value: Environment): Builder = apply { environment = value } public fun logger(value: SdkLogger): Builder = apply { logger = value } public fun build(): ExampleSdk = ExampleSdk(SdkConfig(context.applicationContext, environment, logger)) }}Split it into pieces people can pick
A single all-in-one artifact is convenient to publish and painful to use. Customers who need one feature pay for all of them in app size, method count and transitive dependencies. So I split large SDKs into independent modules with a shared core, and publish a BOM so the versions always line up.
// a customer's app/build.gradle.ktsdependencies { implementation(platform("com.example.sdk:sdk-bom:3.2.0")) implementation("com.example.sdk:core") implementation("com.example.sdk:ui") // only what this app needs}Your dependencies are their problem
Every library your SDK pulls in becomes a library your customer has to resolve against their own versions. A heavy or fast-moving dependency in an SDK causes version conflicts in apps you've never seen. So I'm strict about it:
- Use
implementation, notapi, unless a type from that library genuinely appears in the public API. - Replace heavy dependencies with a small amount of your own code when you only use a sliver of them.
- Keep
minSdkas low as the product allows, and don't raise it in a minor release. - Ship consumer R8 rules with the artifact, so customers don't have to discover your keep rules from a crash in their release build.
android { defaultConfig { minSdk = 24 consumerProguardFiles("consumer-rules.pro") }}Make the UI themeable and accessible
A shared UI component that looks like the SDK instead of like the app gets rewritten by every customer. I expose design tokens instead of hard-coded styles, so one codebase can look native in several products:
// A plain class, not a data class: copy() and componentN() would become// part of the public API and could never change without breaking callers.@Immutablepublic class SdkColors( public val primary: Color, public val onPrimary: Color, public val surface: Color, public val onSurface: Color,)public val LocalSdkColors: ProvidableCompositionLocal<SdkColors> = staticCompositionLocalOf { error("Wrap SDK UI in SdkTheme") }@Composablepublic fun SdkTheme(colors: SdkColors, content: @Composable () -> Unit) { CompositionLocalProvider(LocalSdkColors provides colors, content = content)}Accessibility goes in at the same time, not at the end: content descriptions on every icon-only control, touch targets of at least 48dp, text that scales with the user's font size, and screens tested with TalkBack. Retrofitting accessibility into a component that five apps already use is much harder than building it in.
Change it without breaking anyone
You will get some APIs wrong. The question is how you fix them. I follow semantic versioning strictly, and I remove things in steps across releases so nobody is surprised:
@Deprecated( message = "Use open(itemId, options) so options can grow without new overloads.", replaceWith = ReplaceWith("open(itemId, OpenOptions(readOnly = readOnly))"), level = DeprecationLevel.WARNING, // next minor: ERROR, next major: removed)public fun open(itemId: String, readOnly: Boolean): Session = open(itemId, OpenOptions(readOnly = readOnly))ReplaceWith lets the IDE migrate a customer's code for them with one click. The deprecation level gives everyone at least one release to move before anything breaks.
Test it like a customer would
- A sample app in the repository that uses only the public API. If the sample needs an internal class, the API is missing something.
- Integration tests against the published artifacts, not the source modules, so packaging and R8 rules are tested too.
- A compatibility check against the previous release, so an upgrade that should be painless actually is.
- A changelog written for the customer: what changed, why, and exactly what they need to do.
The best SDK is one people stop thinking about: easy to add, hard to misuse, and boring to upgrade. Every rule above is in service of that.