SDK Development; The Good, The Bad, The Ugly

Some boring backstory intro

A few years ago, a friend roped me into a “simple” side project to make some extra cash. The plan? Build a few apps, slap on some ads, and watch the money roll in. Easy, right? Well… not quite. We quickly found ourselves tangled in a mess of issues. Google AdMob gave us trouble, some ad networks were outright shady, and others offered rates so bad, it wasn’t even worth the effort. After one particularly frustrating day, it hit me: “Why not build a library to handle all these ad networks and decide which ads to show based on the best deal?” Little did I know, this concept already had a name — ad mediation. Since we had a few adnetworks to play with, the idea of creating our own SDK seemed like a no-brainer.
To our surprise, the SDK became such a hit (in our scale) that it completely overshadowed the apps we were trying to monetize in the first place. Suddenly, the SDK was the star of the show, and our apps? Well, they took a back seat.
That was the start of my SDK-building journey.

Fast forward through a decade of working with SDKs — both my own and ones from big-name companies and niche B2B partners — and let’s just say, I’ve seen the good, the bad, and the downright ugly when it comes to SDKs. I think I qualify as a SDK expert.

Part 1: How NOT to develop a SDK (At least targetting the Android platform)?

0. Developing the SDK with a Client-Side Application Mindset

Why it’s a bad idea?
Sure, building an SDK like it’s just another app sounds tempting. But remember, your SDK is going to live in other people’s apps, all with their own unique setups and preferences. Treating it like a client-side app leads to all kinds of fun issues, like tightly coupled architecture, a complete lack of flexibility, and some deliciously unintended side effects. Client apps come with all kinds of assumptions — about UI, lifecycle, and direct access to device resources — that your SDK has no business messing with. It’s like crashing someone else’s dinner party and rearranging all their furniture.

I’m not saying you should disregard good practices for client-side apps. It’s equally important for them to have a good, maintainable architecture and remain flexible. However, client-side apps are generally more resilient to faults that would be unacceptable when developing an SDK. Ideally, there shouldn’t even be an option to create technical debt when building an SDK.
What to do instead:
Instead of treating your SDK like an app, think of it as a backend service that cannot be updated once live. Decouple your concerns, provide asynchronous operations, and for goodness’ sake, be lightweight and unobtrusive. Your SDK should blend into the background, flexible enough to work across a variety of apps without needing to know how they handle their UI, threading, or device resources. Be the guest that’s never noticed — until they need you.

Example: “I Control the UI Now, Mwahaha!”

class Sdk {
    fun showProgressDialog(context: Context) {
        // Let's hijack the UI without asking!
        ProgressDialog(context).apply {
            setTitle("Please wait...")
            setMessage("SDK is doing something super important!")
            show()
        }
    }
}

Because who doesn’t want their UI randomly hijacked by some SDK? You’ve spent hours perfecting your app’s UX, but sure, let’s just throw in this uninvited ProgressDialog in the middle of everything. Thanks, SDK!

Good Practice: “Wait, SDKs Shouldn’t Mess With UIs?”

class Sdk {
    fun performBackendOperation(callback: (Result<String>) -> Unit) {
        // Asynchronous backend logic without UI intervention
        callback(Result.success("Operation Completed!"))
    }
}

Look, mom, no UI! The SDK does what it’s supposed to: backend operations, leaving the app developer to decide how to show progress, if at all.

Wait, what if the UI is part of what our SDK is trying to offer?

You’re already going to ruin the experience of the poor developer trying to integrate your SDK into their app. You might think:

But the end user will have a good experience

And while that might be true in some cases, it’s often unlikely for various reasons, including:
1. Lack of Flexibility for Developers: Predefined UI components limit developers’ ability to customize the user interface, making it difficult to align the SDK’s UI with the app’s branding and design. Since the UI is fixed, integrators also lose the ability to embed custom analytics, making it harder to track user activity for marketing or product analysis. This leads to inconsistent user experiences and missed insights, negatively impacting the perception of both the app and the SDK.

2. Resource Conflicts: Bundling UI components can cause resource naming collisions (e.g., IDs, styles, or themes) between the SDK and the host app, leading to unexpected crashes or visual inconsistencies. These issues can require significant debugging effort, reducing developers’ trust in the SDK.

3. Increased Maintenance Complexity: Including UI in the SDK requires ongoing maintenance to ensure compatibility with various Android versions, devices, and design guidelines. This increases the maintenance burden, and delays or unaddressed issues can frustrate developers and users, making the SDK less appealing.

4. Larger SDK Size: Shipping UI components increases the overall size of the SDK, which contributes to larger app sizes. This can deter developers from adopting the SDK, and end-users may avoid downloading apps or uninstall them due to size concerns, indirectly affecting SDK adoption. (like yeah, let’s integrate “com.github.javad:awesome-animation:0.0.2” and add 5 more megabytes to poor developer’s app)

5. Limited Reusability and Scalability: UI components shipped with the SDK are often not reusable or scalable across different projects. Developers working on apps with custom flows or designs may need to bypass or rewrite the SDK’s UI. Additionally, because the UI is fixed, integrators cannot track user activity within the SDK for custom marketing or product analytics purposes, reducing its value and making it appear rigid and developer-unfriendly.

If you absolutely have to ship UI as part of your project, the best way to approach it is to make the UI optional and modular. Here’s how you can do it:

1. Separate UI and Core Logic: Create two distinct packages: one for the core functionality and one for the UI components. This allows developers to choose whether they want to use the provided UI or build their own while still leveraging the core logic of the SDK.
2. Provide Clear Documentation: Offer detailed instructions for implementing the SDK with and without the built-in UI. Include code samples and guidelines for developers who want to customize or replace the default UI.
3. Make the UI Customizable: If you include a UI package, ensure it is fully customizable. Allow developers to override styles, colors, fonts, and even layouts to match their app’s branding and design.
4. Design for Integration: Ensure the UI components follow Android’s Material Design guidelines and can adapt seamlessly to different themes, orientations, and screen sizes. Use isolated namespaces to avoid resource conflicts.
5. Support Analytics Hooks: Provide APIs or callbacks that allow developers to integrate their analytics and tracking solutions into the SDK’s UI. This ensures that they can still collect data and maintain insights into user behavior.
6. Offer a “Headless Mode”: For advanced users, offer a “headless” mode that exposes only the core logic, enabling developers to integrate it into their own UI without relying on your SDK’s visuals.

An ideal SDK with UI should have at least 2 importable modules, 1 for the core functionality, and one for UI.

1. Using 3rd Party Libraries Inside Your SDK

Why it’s a bad idea?
Sure, nothing says “I’m in a hurry” like cramming in every shiny third-party library you can find. But here’s the catch: it comes with a whole list of issues. Ever dealt with version conflicts? Yeah, enjoy those. Licensing problems? Even better! Or how about making the host app developers manage complex dependency resolution because your SDK decided to use a different version of Retrofit, OkHttp, Glide, and Lottie than they do? Just imagine the joy when their app breaks, and they have to dig through Maven hell to figure out which library caused the explosion. You’re welcome!
What to do instead:
Minimize external dependencies like you’re on a code diet. Especially for core functionality. If you absolutely must drag in third-party libraries (and hey, I get it, they’re useful), isolate them. Or better yet, give the app developers the option to exclude or replace them. And please, document what libraries you’re using so it doesn’t feel like a game of “surprise dependency roulette.” It’s a party no one wants to attend.

Example: “Let’s Bring the Whole Party! Retrofit, OkHttp, Glide, and Lottie!”

class Sdk {
    // Retrofit to fetch data
    private val retrofit = Retrofit.Builder()
        .baseUrl("https://api.example.com/")
        .build()

    // OkHttp for all the fancy HTTP interceptors
    private val client = OkHttpClient.Builder().build()

    // Glide to load images, of course
    fun loadImage(context: Context, imageUrl: String, imageView: ImageView) {
        Glide.with(context)
            .load(imageUrl)
            .into(imageView)
    }

    // And why not add Lottie animations for good measure?
    fun showLottieAnimation(context: Context, animationView: LottieAnimationView) {
        animationView.setAnimation("cool_animation.json")
        animationView.playAnimation()
    }
}

• Because why just load ads when you can load the entire internet along with them? Let’s add Retrofit for fetching some unnecessary data, OkHttp for all those fancy interceptors, Glide to load the most important image in history, and hey, let’s slap a Lottie animation on it too. What could go wrong? 🤷‍♂️
• I mean, who doesn’t love an SDK that bloats your app by 10MB with libraries it never even needed? Oh, and good luck dealing with version conflicts in your app! 😎

Good Practice: “Just Keep It Simple, Stupid”

class Sdk {
    // Avoid unnecessary dependencies
    fun performSimpleNetworkOperation(callback: (Result<String>) -> Unit) {
        // Use plain old URL and HttpURLConnection, or let the app manage HTTP libraries.
        callback(Result.success("Fetched data"))
    }

    // Let the app handle image loading and animations
    fun loadDataAndReturnUrl(callback: (String) -> Unit) {
        // Just return a URL and let the app handle loading the image or animation
        callback("https://image.example.com")
    }
}

Here’s an idea: let the developer decide if they want to use Retrofit, OkHttp, Glide, or Lottie. Stop packing your SDK like it’s the IKEA of dependencies. Simplicity wins the day.

1.1 Using Deprecated Libraries

Why it’s a bad idea? (as if them being a 3rd party is not bad enough)
Ah, deprecated libraries — like old, broken toys that should’ve been thrown out years ago, but somehow you just can’t let go. They no longer receive updates, bug fixes, or any kind of love. In fact, they bring along security vulnerabilities and compatibility issues like unwanted party crashers. If your SDK relies on them, congratulations: you’ve just created a ticking time bomb for your users’ apps.
What to do instead:
Keep up with the times. Refactor your SDK and ditch deprecated libraries before they sink the ship. Continuously monitor the libraries you’re using (yes, that means some extra work) and update them before they’re completely irrelevant — or worse, break something critical. Your users will thank you for not making them fight with zombie dependencies.

Example: “AsyncTask is My Best Friend”

class Sdk {
    fun fetchDataInBackground() {
        // Who cares if AsyncTask is deprecated? It’s a classic!
        object : AsyncTask<Void, Void, String>() {
            override fun doInBackground(vararg params: Void?): String {
                // Simulating a network call
                return "Data fetched from background"
            }

            override fun onPostExecute(result: String?) {
                // Handle result on the main thread
            }
        }.execute()
    }
}

Because who cares about Kotlin coroutines when we can use trusty old AsyncTask that Google has been telling us to avoid for years? Let’s keep that 2012 vibe going strong. (And yes, I first hand found someone use it in 2024)

Good Practice: “Welcome to the 2020s — We Have Coroutines Now”

class Sdk {
    fun fetchDataInBackground(callback: (Result<String>) -> Unit) {
        GlobalScope.launch(Dispatchers.IO) {
            try {
                val data = "Fetched data"
                withContext(Dispatchers.Main) {
                    callback(Result.success(data))
                }
            } catch (e: Exception) {
                withContext(Dispatchers.Main) {
                    callback(Result.failure(e))
                }
            }
        }
    }
}

Ah, Kotlin Coroutines, the cool, modern way to handle background tasks without dragging apps back to the dark ages. The best part? They don’t trigger ANRs and actually make you look like you know what you’re doing.

I’m not ranting about coroutines. I’m talking about those libraries buried six feet under in the graveyard of GitHub, last updated in 2019. Found some old but “reliable” library that’s no longer maintained? Great, now definitely don’t use its sketchy forks in an SDK you’re shipping for poor developers to suffer through. Always remember: if the original library was abandoned, there’s probably a good reason for it. Do everyone a favor and find a modern replacement instead.

2. Using Singletons and Global State Management

Why It’s a Bad Idea:

Ah yes, singletons — easy to set up, but a nightmare to live with when combined with mutable global state. They introduce unpredictable behavior, especially in multi-threaded environments, leading to race conditions, inconsistent states, and debugging nightmares. Need more than one instance of your SDK in the same app? Good luck with that. Worse, singletons often cause memory leaks by holding references to contexts or activities. They also hide dependencies, making code harder to test, maintain, and extend. Simply put, global state is a global headache.

What to Do Instead:

Use dependency injection or factory patterns to create and manage your SDK instances. This gives the client app control over the scope and lifecycle of your SDK components, ensuring predictable behavior. Avoid mutable global state — keep state context-aware and scoped to instances. If you need shared functionality, consider context-safe singletons with immutable state or thread-safe designs. And always design your SDK to support multiple instances where applicable. Responsible scoping leads to cleaner code and fewer headaches.

Example: “Global State, Global Headache”

object SdkSingleton {
    var globalAdState: String = "No ad loaded yet"

    fun loadAd() {
        // Modify global state at will!
        globalAdState = "Ad loaded!"
    }
}

Good Practice: “Let’s Scope This Like Adults”

class Sdk(private var adState: String) {
    fun loadAd(): Sdk {
        // Create a new instance with updated state
        return Sdk("Ad loaded!")
    }
}

// Create new instances without messing with global state
val sdkInstance = Sdk("No ad loaded")
val newSdkInstance = sdkInstance.loadAd()

Keep your global state to yourself, thank you. Scoping state to instances like a responsible developer means fewer headaches and less chaos.

3. Poor Documentation

Why it’s a bad idea?
So, you’ve built an amazing SDK, but forgot to tell anyone how to actually use it. Now developers are banging their heads against the wall trying to figure out what your methods do. Misuse, bugs, and frustrated support emails follow. But hey, it’s their fault for not reading your mind, right?
What to do instead:
Write documentation like you’re being graded on it. Clear, concise, and, most importantly, up-to-date. Include everything developers need: installation instructions, detailed API references, code examples, common use cases, and troubleshooting guides. And remember, just like your SDK, your docs should evolve. Developers don’t have time for guesswork; help them out!

Example: “Good Luck, You’ll Need It”

class Sdk {
    fun doSomethingSuperImportant() {
        // But I won’t tell you how or why
    }
}

Good Practice: “Let’s Be Nice — Write Documentation”

/**
 * Performs an important task that retrieves user data.
 *
 * @param userId ID of the user to fetch data for.
 * @return User data in a Result wrapper.
 */
class Sdk {
    fun fetchUserData(userId: String, callback: (Result<String>) -> Unit) {
        // Retrieves user data and passes it to the callback
        callback(Result.success("User data for $userId"))
    }
}

Imagine the joy on a developer’s face when they actually understand how your SDK works! Clear documentation is like a ray of sunshine on a cloudy day.

4. Bad Communication of Changes

Why it’s a bad idea?
Making breaking changes without telling anyone is the ultimate plot twist. You’ll leave developers scratching their heads when their app mysteriously starts crashing after your latest update. And when features disappear or behaviors change with no explanation? Well, you’ve just created a new level of frustration. Bonus points if the developer only finds out after deploying their app to production!
What to do instead:
Communicate like an adult. Use proper versioning (ever heard of semantic versioning? It’s your friend). Maintain a changelog that’s actually useful, marking breaking changes clearly, and providing migration guides. Offering beta releases to let developers adapt before the official update drops? Now that’s next-level professional.

5. Heavy-loading and Big Size of the AAR

Why it’s a bad idea?
Your SDK should be lean and mean, but instead, it’s bloated like a post-buffet nap. A large SDK increases app size, leading to longer build times, sluggish performance, and higher memory usage. You’ve just transformed that sleek app into a lumbering dinosaur. End users now get to enjoy painfully slow downloads, and developers get to spend their days trying to optimize around your behemoth of an SDK.
What to do instead:
Trim the fat. Optimize your SDK by stripping unused code and resources. Use ProGuard or R8 to shrink and obfuscate code, and modularize your SDK so developers can choose only the parts they need. The goal? A lightweight core with optional feature modules. Because no one likes dragging around unnecessary baggage.

Example: “Let’s Make This AAR the Size of a Small Planet”

// Packed with unnecessary resources like high-res images and massive JSON files
res/drawable/hd_background.png
res/animations/full_length_animation.json
asset/mother_nature.so

Good Practice: “Let’s Not Make Developers Hate Us”

// Use ProGuard to slim down the AAR 
android {
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}

// Split into modules so developers can choose what they actually need
implementation("com.example.sdk:core:1.0.0")
implementation("com.example.sdk:ad-module:1.0.0")

Part 2: An Ideal approach

1. SDKs Are Modules in Disguise

The process of developing an SDK closely resembles that of designing a module in a modular architecture, and adhering to clean architecture principles isn’t just “nice to have” — it’s essential. An SDK must behave like a guest in someone else’s app, blending seamlessly without imposing on the host app’s architecture. Let’s break this down technically:

Why Clean Architecture is Essential for SDKs

1. Decoupling Concerns:

• Clean architecture separates business logic (what the SDK does) from implementation details (how it does it). For example, the SDK should expose its core functionality via interfaces or abstract classes, while internal implementations remain private and modularized.
• This ensures the SDK is flexible and doesn’t directly tie its implementation to specific frameworks or third-party libraries.

interface AdLoader {
    fun loadAd(callback: (Result<String>) -> Unit)
}

class AdLoaderImpl(private val networkClient: NetworkClient) : AdLoader {
    override fun loadAd(callback: (Result<String>) -> Unit) {
        networkClient.fetchAd { result ->
            callback(result)
        }
    }
}

Here, AdLoader abstracts the business logic of loading ads, while AdLoaderImpl provides the implementation. The app integrating the SDK only interacts with the interface, keeping things modular and easy to test.

2. Testability:

• Clean architecture ensures your SDK’s core logic is independent of Android-specific APIs, making it easier to test. For instance, avoid tying core logic to Activity, Context, or ViewModel classes.
• Instead, inject platform-dependent dependencies where needed, keeping the core business logic free from platform concerns.

3. Scalability:

• Modular SDKs are easier to maintain and scale. If you decide to add a new feature (e.g., analytics integration), you can do so without overhauling the existing code. Separate the analytics feature into a module, and expose it only to apps that choose to include it.

How to Apply Clean Architecture to SDKs

1. Domain Layer: Handles the business rules and logic of your SDK. Expose only what’s necessary through interfaces and keep this layer entirely independent of third-party libraries or platform code.
2. Data Layer: Manages data sources (e.g., network or local storage). Use repository patterns to abstract data operations.
3. Interface Layer (Optional): If your SDK includes UI, provide it as an optional package, separate from the core SDK logic. Use Compose or Views but allow developers to customize it or bypass it entirely.
4. Dependency Injection: Design your SDK to work with DI frameworks like Dagger, Koin, or Hilt, or provide a way to inject dependencies manually. This gives integrators full control over lifecycle and scoping.

Key Takeaway:
Clean architecture makes your SDK predictable, maintainable, and easy to integrate. Developers can trust that it will not clash with their app’s architecture or create unwanted dependencies.

And I might not be the best person for teaching clean architecture. There are more than enough resources out there that you can learn from. The “Clean Architecture: A Craftsman’s Guide to Software Structure and Design” by uncle bob is the perfect resource.

Swallow the Hard Pill of Library Implementation

SDK development requires a different mindset compared to app development, particularly when it comes to handling dependencies. Relying on third-party libraries in your SDK can lead to dependency hell for developers integrating it into their apps. Here’s a deeper dive into why and how to handle this challenge:

Why Overusing Third-Party Libraries is Problematic

1. Version Conflicts: Apps integrating your SDK may already use the same libraries (e.g., Retrofit, OkHttp, Glide) but with different versions. If your SDK forces its version of these libraries, it can lead to dependency clashes that break the app. For example The host app uses Retrofit 2.9.0, but your SDK is built with Retrofit 2.5.0. The app fails to compile because Gradle doesn’t know which version to use. Even if it compiles, runtime crashes could occur due to API differences.
2. Increased APK Size: Every third-party library you include adds weight to the SDK. For instance, Glide adds several MBs of resources and code, which might not even be used if the app already has its own image-loading library, bloating the integrator’s app.
3. Licensing Issues: Not all libraries are compatible with commercial or open-source SDKs. Using a library with a restrictive license (e.g., GPL) can expose your SDK and its users to legal risks. Just because a project or developer hasn’t sued you yet, doesn’t mean what you’re doing is legal.

How to Avoid These Pitfalls

1. Implement Features Yourself: Yeah yeah “Don’t reinvent the wheel” and all, but we have the above problems to address, rememeber? Instead of relying on libraries for common tasks, consider implementing lightweight, custom solutions tailored to your SDK’s needs.

Example: For networking, instead of using Retrofit:

fun fetchAd(callback: (Result<String>) -> Unit) {
    val url = URL("https://api.example.com/ads")
    val connection = url.openConnection() as HttpURLConnection
    try {
        val data = connection.inputStream.bufferedReader().readText()
        callback(Result.success(data))
    } catch (e: Exception) {
        callback(Result.failure(e))
    } finally {
        connection.disconnect()
    }
}

This implementation avoids dragging in a large library and keeps your SDK lightweight.

2. Isolate Dependencies: If a library is unavoidable, wrap it in an abstraction layer so the host app doesn’t interact with it directly. This also makes it easier to replace the library in the future without breaking the SDK’s API.

Example:

interface ImageLoader {
    fun loadImage(url: String, imageView: ImageView)
}

class GlideImageLoader : ImageLoader {
    override fun loadImage(url: String, imageView: ImageView) {
        Glide.with(imageView.context).load(url).into(imageView)
    }
}

Again, do this as a last resort. It’s always better to have your own implementation of essential libraries for networking, asynchronous operations, etc.

3. Make Dependencies Optional: Use Gradle’s optional dependencies to allow developers to exclude libraries they don’t need.

implementation("com.example.sdk:core:1.0.0")
implementation("com.example.sdk:ui:1.0.0") // Include only if UI is needed

Does your SDK provides more than 1 functionality? Then chances are you’re gonna need a package per functionality. A very perfect and relatable example is how Firebase has designed its dependencies with its Android SDK.

Key Takeaway: By implementing features in-house and isolating dependencies, you ensure your SDK is lightweight, conflict-free, and safe to integrate. Yes, it’s more work upfront, but it’s worth it to avoid becoming the SDK developers hate using.

Conclusion:

Developing an SDK is not just about building functionality; it’s about crafting a developer-friendly experience that integrates seamlessly into diverse apps without causing headaches. As this article has outlined, creating an effective SDK requires careful consideration of architecture, dependencies, UI integration, and communication with developers. It’s a balancing act between providing robust functionality and maintaining flexibility, scalability, and simplicity.

By treating your SDK as a modular system adhering to clean architecture principles, you ensure maintainability, testability, and long-term compatibility. Writing your own libraries, while a harder path, avoids the pitfalls of third-party dependency conflicts, licensing issues, and bloated SDK sizes, making your SDK a lightweight, reliable addition to any app.

Ultimately, an SDK is a tool meant to empower developers, not frustrate them. Keep your design unobtrusive, your APIs intuitive, and your documentation thorough. If you approach SDK development with the same care you would a mission-critical backend service, you’ll create a product that developers trust and love to use.

SDK development may be challenging, but by applying these principles, you can turn the good, the bad, and the ugly into a toolkit that stands out in the best way possible. Remember, when developers integrate your SDK, they’re placing their trust in you — don’t let them down.