Mobile SDK development

An app owns its process. It decides when it starts, which thread does what, how much it logs, and what happens when it crashes. An SDK owns none of that. Somebody else's app initializes your code, on a thread of their choosing, possibly before their first screen exists, next to other SDKs, compiled with their build settings, their minimum OS version, their dependency versions and their release configuration.

That changes what the deliverable is. The public surface becomes the product: a small number of entry points that are safe to call early, safe to call twice, and documented as to which thread they expect and what they do when they fail. An SDK that throws from an initializer takes the host app down with it, and the crash report lands on their desk with your class names in it. Their user blames them.

The second thing an integrator inherits is your dependency list. Every library you pull in is a library you force on them, at a version that has to coexist with whatever they already use. Gradle resolves a version conflict by taking the highest request, so a transitive dependency you bumped casually can change the behaviour of code you have never seen. Keeping the footprint small is a compatibility decision, not a style preference.

Native Android and iOS are one problem. React Native, Flutter and Unity add a wrapper layer, and the wrapper is where most breakage happens, because its whole job is forwarding calls one way and callbacks the other way while preserving things the underlying SDK cares about: which thread it is on, which lifecycle object it is attached to, and whether a callback fires once or twice.

None of those survive a naive bridge. A promise resolved twice crashes some runtimes and silently does nothing on others. A callback delivered on a background thread reaches code that then touches a view, which is a main-thread-only operation on both platforms. An object identity that the native SDK uses to correlate a request with its result gets recreated across the bridge and the correlation is lost. These are not exotic bugs; they are the default outcome of writing the wrapper by hand and testing it once on the happy path.

On Android, release builds run R8, which shrinks, renames and optimizes based on what it can prove is reachable. Anything resolved by name at runtime is invisible to that analysis: a class named in a string, an adapter looked up reflectively, an entry point referenced from a manifest or a configuration file, a field name a serializer expects. The code compiles. The debug build works. The release build fails, or worse, quietly does nothing.

Keep rules are the fix, and reading the source cannot tell you whether yours are correct. A rule is a pattern; whether it matched the classes you meant is a property of the output, not of the rule. This is the single most common reason an SDK behaves differently at a customer's site than in your own project, because the customer builds release and you build debug all day.

An SDK also has to carry its own rules rather than documenting them. Rules in an integration guide get pasted once and never updated, so a customer on an old copy of your instructions is running last year's configuration against this year's library. Shipping them with the artifact makes the correct configuration the default one.

Unit tests structurally cannot catch this class of problem. They run against compiled classes in a test configuration, not against the shrunk, renamed bundle that ships. A class can pass every test and then be absent from the artifact a customer installs. The same gap covers packaging: a resource that did not get bundled, a slice missing from a framework, a transitive dependency that resolved locally because of a project path reference and does not exist for anyone consuming the published version.

So the verification that matters is mechanical and physical. Build the thing you will publish, consume it the way a customer will, look inside it, and then run it.

Host apps upgrade an SDK during a sprint that is about something else. That is the situation your version numbers have to survive. Semantic versioning honestly applied, deprecation before removal, and one short migration note per breaking change cover most of it. Removing a method in a minor version is the fastest way to be pinned to an old release forever.

The subtler breaking change is a dependency bump. If your library requires a newer version of a third-party SDK, you have changed the host app's build whether or not your own API moved, and if their code depends on the older behaviour, your minor upgrade broke them. Compile against the oldest version you claim to support, test against the newest, and say in writing which range you actually cover.

That statement of coverage is worth maintaining as a table: minimum OS versions, minimum React Native, Flutter or Unity versions, and which versions of any SDK you integrate with. Most support conversations are really requests for that table.

An SDK does not ship to a store, but every one of its customers does, so store requirements become your requirements one step removed. Anything your library declares gets merged into the host's manifest, including permissions, which means a permission you added for an optional feature is a permission somebody now has to justify in a review or a data-safety declaration. Apple's privacy manifest and signing rules for third-party SDKs sit in the same category: they are conditions on your artifact that the app developer cannot satisfy on your behalf.

Platform deadlines also arrive as your problem, because a target API level requirement or a new declaration form reaches the app first and the app cannot move until its SDKs have. Being ahead of that is a large part of what makes an SDK pleasant to depend on.

The last piece is documentation and samples, which are part of the product rather than an afterthought. A working sample app per platform, resolved from the published artifact, is simultaneously the integration guide, the regression test and the reproduction case a support conversation starts from.