When you're working in Kotlin Multiplatform (KMP), the goal is to share as much logic as possible. But let's be honest: you can't write a single piece of code that handles both an Android File API and an iOS File API. They are fundamentally different beasts. This is where the expect and actual keywords come in.

Think of expect as a contract. You're telling the compiler, "I promise that every platform this project targets will provide a specific implementation for this declaration." The actual keyword is where you fulfill that promise.

Drafting the platform contract in commonMain

Let's build a simple utility that returns the device's model name. I want to use this in my shared business logic to tag analytics events, but the way you get the device model on Android is totally different from how you do it on iOS.

First, I'll head over to the commonMain source set. I don't know how the platform will get the name yet; I just know that I need a function that returns a String.

// In commonMain
expect fun getDeviceModel(): String

Notice there's no body here. No curly braces. It's just a signature. If I try to call getDeviceModel() inside another function in commonMain, the compiler lets me do it because it trusts that by the time the app actually runs, a real implementation will exist.

Fulfilling the contract for Android

Now I need to move into the androidMain source set to provide the actual implementation. On Android, I can just grab this from the android.os.Build class.

// In androidMain
import android.os.Build

actual fun getDeviceModel(): String {
    return Build.MODEL
}

Hitting a visibility wall

Here is where I usually trip up when I'm moving fast. I decided that I didn't want this function to be exposed to the rest of my Android app—only to the shared module. So, I tried to make it internal:

// In androidMain
internal actual fun getDeviceModel(): String { 
    return Build.MODEL 
}

Immediately, the IDE turns red. The compiler throws a fit, telling me that the actual declaration must have the same visibility as the expect declaration. It makes sense: if the common code expects a public function, you can't suddenly make it internal on one platform and break the contract. I'll remove the internal modifier and keep it public to match the expect side.

Completing the set for iOS

If I try to build the project now, it'll fail. Why? Because I'm targeting iOS too, and I haven't told the compiler how to handle getDeviceModel() on Apple's side. The expect keyword is a strict requirement; you can't leave any platform hanging.

I'll jump into iosMain and use the UIDevice API from the iOS SDK, which Kotlin Multiplatform makes available to us via its interop layers.

// In iosMain
import platform.UIKit.UIDevice

actual fun getDeviceModel(): String {
    return UIDevice.currentDevice.model
}

Now the puzzle is complete. When the Android app compiles, it swaps the expect call for the Android actual. When the iOS app compiles, it swaps it for the iOS actual. The shared logic remains clean and platform-agnostic, while we still get to touch the "metal" of the underlying OS.

📋 Practical Task

Implement a Platform-Specific UUID Generator

You are building a shared library that needs to generate a unique identifier (UUID) for a user session. Since you want to use the native platform's built-in UUID generator rather than a third-party library, you need to use expect and actual.

• In the commonMain source set, create an expect function named generateUUID() that returns a String.
• In the androidMain source set, provide the actual implementation using java.util.UUID.randomUUID().toString().
• In the iosMain source set, provide the actual implementation using platform.Foundation.NSUUID().UUIDString().

Ensure that the visibility modifiers (public/internal) match across all three declarations to avoid compiler errors.