Hybrid SDK Architecture: One Shared Layer Between Frameworks and Native Stores
Supporting several cross-platform frameworks alongside native iOS and Android creates a maintenance problem: every purchase feature must be rebuilt, tested, and debugged in multiple languages. A shared intermediary can shrink that duplication. Instead of each hybrid SDK talking directly to a native SDK, all of them route through a common wrapper that handles type conversion once, then delegates store-specific work to the native layer.
Why six SDKs create a duplication problem
The challenge starts with scale. Two native SDKs plus four hybrid frameworks — Flutter, React Native, Unity, and Cordova — means six codebases to keep in step. A feature shipped on one platform still needs equivalents elsewhere, and each release forces switching between languages and toolchains. Hybrid frameworks promise one codebase for iOS and Android, and sometimes desktop or web, so developers expect SDK support in the framework they already use.
Purchases cannot be handled purely in the hybrid layer. They must eventually reach the native in-app purchasing libraries — StoreKit on Apple platforms and BillingClient on Google platforms. That creates a translation problem: values written in Dart, JavaScript, or C# have to become Swift or Kotlin, and results have to travel back in a form each framework's messaging system accepts.
Three stages down, one callback chain back
The architecture uses three stages on the way down, and a callback chain on the way back.
First, the call is created at the message-passing layer. Each hybrid SDK is a thin interface shaped to feel natural in its framework. The Android React Native layer, for example, accepts a different object type than Cordova does. This is the only layer app developers interact with directly.
Second, the call goes to a shared intermediary library, purchases-hybrid-common. Rather than each hybrid SDK calling a native SDK on its own, every hybrid SDK depends on this common layer, which in turn depends on the native libraries. The common layer performs shared type transformations and routes the call onward.
Third, the native layer does the platform-specific work: fetching products, starting a purchase, and talking to the store. Results then propagate back up the same chain.
Use this as a design checklist when evaluating a hybrid SDK:
- Is there a single place where native types are converted to framework-neutral maps?
- Does each hybrid SDK only handle its own messaging types, rather than re-implementing parsing?
- Are asynchronous results and errors wrapped in one uniform callback interface?
- Can a new hybrid framework be added by writing a thin adapter, not a new parsing layer?
Worked example: tracing getOfferings in both directions
Retrieving offerings — the packages available for purchase, such as yearly, monthly, and lifetime options — is a useful walk-through because it is asynchronous and returns a custom type, so both directions need special handling. The protected modules code0001 through code0009 show each step in sequence.
On the way down, the app calls the hybrid SDK, which sends the method name across the platform channel. On Android with Flutter, the plugin receives the method call and forwards it to the common layer. The common layer calls the native Android SDK, which fetches offerings and invokes a success or error callback.
On the way back, the common layer converts the native offerings object into a plain map. This conversion is the heart of the design. Framework messaging layers only accept a restricted set of types — Flutter uses a standard codec, Cordova accepts strings, byte arrays, JSON arrays, and JSON objects — so a Kotlin object cannot cross the boundary directly. Converting to a map in one shared place defines the keys once, avoiding copied parsing code and the bugs that come with it. Each hybrid SDK then only converts that map into whatever its own messaging layer expects, without knowing the individual key-value pairs. The plugin passes the map back through its result callback, which fulfills the asynchronous future in Dart, and the hybrid SDK rebuilds a typed offerings object from the map.
What centralising the conversion bought — and what is next
Before the shared layer existed, every hybrid framework carried its own logic for breaking native classes into acceptable types. The same JSON-like parsing was copied across all hybrid SDKs for every type. Centralising it reduced both effort and defects.
Two improvement directions remain open. Moving more Java and Objective-C code to Kotlin and Swift would modernise the native side, and third-party serialisation libraries could replace hand-written mapping. A rawData property on native classes, which preserves the backend JSON object, offers another path: it aids debugging, lets customers reach backend properties without waiting for a release, and could eventually simplify or remove some of the shared parsing.