Make your Android application work on iOS – tutorial

Decide what code to make cross-platform

Decide which code of your Android application is better to share for iOS and which to keep native. A simple rule is: share what you want to reuse as much as possible. The business logic is often the same for both Android and iOS, so it's a great candidate for reuse.

In your sample Android application, the business logic is stored in the package com.jetbrains.simplelogin.androidapp.data. Your future iOS application will use the same logic, so you should make it cross-platform, as well.

Create a shared module for cross-platform code

The cross-platform code used for both iOS and Android will be stored in a shared module. Starting with the Meerkat version, Android Studio provides a wizard for creating such shared modules.

Create a shared module and connect it to both the existing Android application and your future iOS application:

1. In Android Studio, select File | New | New Module from the main menu.

2. In the list of templates, select Kotlin Multiplatform Shared Module. Leave the library name shared and enter the package name com.jetbrains.simplelogin.shared.

3. Click Finish. The wizard creates a shared module, changes the build script accordingly, and starts a Gradle sync.

4. When the setup is complete, you will see the following file structure in the shared directory:

   

5. Make sure that the kotlin.androidLibrary.minSdk property in the shared/build.gradle.kts file matches the value of the same property in the app/build.gradle.kts file.

Add code to the shared module

Now that you have a shared module, add some common code to be shared in the commonMain/kotlin/com.jetbrains.simplelogin.shared directory:

1. Create a new Greeting class with the following code:

   package com.jetbrains.simplelogin.shared
   
   class Greeting {
       private val platform = getPlatform()
   
       fun greet(): String {
           return "Hello, ${platform.name}!"
       }
   }

2. Replace the code in created files with the following:

   • In commonMain/Platform.kt:

     package com.jetbrains.simplelogin.shared
     
     interface Platform {
         val name: String
     }
     
     expect fun getPlatform(): Platform

   • In androidMain/Platform.android.kt:

     package com.jetbrains.simplelogin.shared
     
     import android.os.Build
     
     class AndroidPlatform : Platform {
         override val name: String = "Android ${Build.VERSION.SDK_INT}"
     }
     
     actual fun getPlatform(): Platform = AndroidPlatform()

   • In iosMain/Platform.ios.kt:

     package com.jetbrains.simplelogin.shared
     
     import platform.UIKit.UIDevice
     
     class IOSPlatform: Platform {
         override val name: String = UIDevice.currentDevice.systemName() + " " + UIDevice.currentDevice.systemVersion
     }
     
     actual fun getPlatform(): Platform = IOSPlatform()

If you want to better understand the layout of the resulting project, see the basics of Kotlin Multiplatform project structure.

Add a dependency on the shared module to your Android application

To use cross-platform code in your Android application, connect the shared module to it, move the business logic code there, and make this code cross-platform.

1. Add a dependency on the shared module to the app/build.gradle.kts file:

   dependencies {
       // ...
       implementation(project(":shared"))
   }

2. Sync the Gradle files as suggested by the IDE or using the File | Sync Project with Gradle Files menu item.

   

3. In the app/src/main/java/ directory, open the LoginActivity.kt file in the com.jetbrains.simplelogin.androidapp.ui.login package.

4. To make sure that the shared module is successfully connected to your application, dump the greet() function result to the log by adding a Log.i() call to the onCreate() method:

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       Log.i("Login Activity", "Hello from shared module: " + (Greeting().greet()))
   
       // ...
   }

5. Follow Android Studio's suggestions to import missing classes.

6. In the toolbar, click the app dropdown, then click the debug icon:

   

7. In the Logcat tool window, search for "Hello" in the log, and you'll find the greeting from the shared module:

   

Make the business logic cross-platform

You can now extract the business logic code to the Kotlin Multiplatform shared module and make it platform-independent. This is necessary for reusing the code for both Android and iOS.

1. Move the business logic code com.jetbrains.simplelogin.androidapp.data from the app directory to the com.jetbrains.simplelogin.shared package in the shared/src/commonMain directory.

   

2. When Android Studio asks what you'd like to do, select to move the package and then approve the refactoring.

   

3. Ignore all warnings about platform-dependent code and click Continue.

   

4. Remove Android-specific code by replacing it with cross-platform Kotlin code or connecting to Android-specific APIs using expected and actual declarations. See the following sections for details:

   Replace Android-specific code with cross-platform code

   To make your code work well on both Android and iOS, replace all JVM dependencies with Kotlin dependencies in the moved data directory wherever possible.

   1. In the LoginDataSource class, replace IOException in the login() function with RuntimeException. IOException is not available in Kotlin/JVM.

      // Before
      return Result.Error(IOException("Error logging in", e))

      // After
      return Result.Error(RuntimeException("Error logging in", e))

   2. Remove the import directive for IOException as well:

      import java.io.IOException

   3. In the LoginDataValidator class, replace the Patterns class from the android.utils package with a Kotlin regular expression matching the pattern for email validation:

      // Before
      private fun isEmailValid(email: String) = Patterns.EMAIL_ADDRESS.matcher(email).matches()

      // After
      private fun isEmailValid(email: String) = emailRegex.matches(email)
      
      companion object {
          private val emailRegex =
              ("[a-zA-Z0-9\\+\\.\\_\\%\\-\\+]{1,256}" +
                  "\\@" +
                  "[a-zA-Z0-9][a-zA-Z0-9\\-]{0,64}" +
                  "(" +
                  "\\." +
                  "[a-zA-Z0-9][a-zA-Z0-9\\-]{0,25}" +
                  ")+").toRegex()
      }

   4. Remove the import directive for the Patterns class:

      import android.util.Patterns

   Connect to platform-specific APIs from the cross-platform code

   In the LoginDataSource class, a universally unique identifier (UUID) for fakeUser is generated using the java.util.UUID class, which is not available for iOS.

   val fakeUser = LoggedInUser(java.util.UUID.randomUUID().toString(), "Jane Doe")

   Even though the Kotlin standard library provides an experimental class for UUID generation, let's use platform-specific functionality for this case to practice doing that.

   Provide the expect declaration for the randomUUID() function in the shared code and its actual implementations for each platform – Android and iOS – in the corresponding source sets. You can learn more about connecting to platform-specific APIs.

   1. Change the java.util.UUID.randomUUID() call in the login() function to a randomUUID() call, which you will implement for each platform:

      val fakeUser = LoggedInUser(randomUUID(), "Jane Doe")

   2. Create the Utils.kt file in the com.jetbrains.simplelogin.shared package of the shared/src/commonMain directory and provide the expect declaration:

      package com.jetbrains.simplelogin.shared
      
      expect fun randomUUID(): String

   3. Create the Utils.android.kt file in the com.jetbrains.simplelogin.shared package of the shared/src/androidMain directory and provide the actual implementation for randomUUID() in Android:

      package com.jetbrains.simplelogin.shared
      
      import java.util.*
      
      actual fun randomUUID() = UUID.randomUUID().toString()

   4. Create the Utils.ios.kt file in the com.jetbrains.simplelogin.shared of the shared/src/iosMain directory and provide the actual implementation for randomUUID() in iOS:

      package com.jetbrains.simplelogin.shared
      
      import platform.Foundation.NSUUID
      
      actual fun randomUUID(): String = NSUUID().UUIDString()

   5. Import the randomUUID function in the LoginDataSource.kt file of the shared/src/commonMain directory:

      import com.jetbrains.simplelogin.shared.randomUUID

Now, Kotlin will use platform-specific implementations of UUID for Android and iOS.

Run your cross-platform application on Android

Run your cross-platform application for Android to make sure it works.

Create an iOS project in Xcode

1. In Xcode, click File | New | Project.

2. Select a template for an iOS app and click Next.

   

3. As the product name, specify "simpleLoginIOS" and click Next.

   

4. As the location for your project, select the directory that stores your cross-platform application, for example, kmp-integration-sample.

In Android Studio, you'll get the following structure:

You can rename the simpleLoginIOS directory to iosApp for consistency with other top-level directories of your cross-platform project. To do that, close Xcode and then rename the simpleLoginIOS directory to iosApp. If you rename the folder with Xcode open, you'll get a warning and may corrupt your project.

Configure the iOS project to use a KMP framework

You can set up integration between the iOS app and the framework built by Kotlin Multiplatform directly. Alternatives to this method are covered in the iOS integration methods overview, but they are beyond the scope of this tutorial.

1. In Xcode, open the iOS project settings by double-clicking the project name in the Project navigator.

2. In the Targets section on the left, select simpleLoginIOS, then click the Build Phases tab.

3. Click the + icon and select New Run Script Phase.

   

   The new phase is created at the bottom of the list.

4. Click the > icon to expand the created Run Script item, then paste the following script in the text field:

   cd "$SRCROOT/.."
   ./gradlew :shared:embedAndSignAppleFrameworkForXcode

   

5. Move the Run Script phase higher in the order, placing it before the Compile Sources phase:

   

6. Click the Build Settings tab, then find and disable the User Script Sandboxing option under Build Options:

   

   note

   If you have a custom build configuration different from the default Debug or Release, on the Build Settings tab, add the KOTLIN_FRAMEWORK_BUILD_TYPE setting under User-Defined and set it to Debug or Release.

7. Build the project in Xcode (Product | Build in the main menu). If everything is configured correctly, the project should build successfully (you can safely ignore the "build phase will be run during every build" warning)

   tip

   Build may fail if you built the project before disabling the User Script Sandboxing option: the Gradle daemon process may be sandboxed and needs to be restarted. Stop it before building the project again by running this command in the project directory (kmp-integration-sample in our example):

   ./gradlew --stop

Set up an iOS run configuration in Android Studio

When you made sure that Xcode is set up correctly, you can set up a run configuration for the iOS app in Android Studio:

1. Select Run | Edit configurations in the main menu.

2. To add a new configuration, click the plus sign and choose iOS Application.

3. Name the configuration "SimpleLoginIOS".

4. In the Xcode project file field, select the location of the simpleLoginIOS.xcodeproj file.

5. Choose a simulation environment from the Execution target list and click OK:

   

6. Check the newly created configuration by pressing the run button to build and launch the iOS app:

   

Use the shared module in the iOS project

The build.gradle.kts file of the shared module defines the binaries.framework.baseName property for each iOS target as sharedKit. This is the name of the framework that Kotlin Multiplatform builds for the iOS app to consume.

To test the integration, add a call to common code in Swift code:

1. In Android Studio, open the iosApp/simpleloginIOS/ContentView.swift file and import the framework:

   import sharedKit

2. To check that it is properly connected, change the ContentView structure to use the greet() function from the shared module of your cross-platform app:

   struct ContentView: View {
       var body: some View {
           Text(Greeting().greet())
           .padding()
       }
   }

3. Run the app using the Android Studio iOS run configuration to see the result:

   

4. Update code in the ContentView.swift file again to use the business logic from the shared module to render the application UI:

   import SwiftUI
    {...}

5. In the simpleLoginIOSApp.swift file, import the sharedKit module and specify the arguments for the ContentView() function:

   import SwiftUI
   import sharedKit
   
   @main
   struct SimpleLoginIOSApp: App {
       var body: some Scene {
           WindowGroup {
               ContentView(viewModel: .init(loginRepository: LoginRepository(dataSource: LoginDataSource()), loginValidator: LoginDataValidator()))
           }
       }
   }

6. Run the iOS run configuration again to see that the iOS app shows the login form.

7. Enter "Jane" as the username and "password" as the password.

8. As you have set up the integration earlier, the iOS app validates input using common code: