Chạy App Trên iOS (macOS + Xcode)

Mục Tiêu Bài Học

Sau bài này bạn chạy được cùng app của khóa học trên iOS Simulator, từ Xcode và từ terminal, và hiểu Kotlin code đi vào app iOS bằng đường nào.

Đây là bài tùy chọn. Nó cần một máy Mac. Nếu bạn dùng Windows hoặc Linux, bỏ qua bài này: mọi phần còn lại của khóa đều làm được trên Android.

Bạn Cần Gì

Chạy trên Simulator không cần Apple Developer Program. Chạy trên iPhone thật thì cần một Apple ID và một team trong Xcode, phần cuối bài có nói.

Phần 1: Kotlin Đi Vào App iOS Như Thế Nào

Trên Android, :app là một Gradle module và depend thẳng vào code Kotlin. iOS không đọc được Gradle module. Xcode chỉ link với framework.

Vì vậy module :shared-app build toàn bộ code Kotlin dùng chung (các feature, :core, :data, :domain...) thành một static framework tên Shared. Project Xcode trong iosApp/ có một build phase tên "Build Shared framework" chạy lệnh:

./gradlew :shared-app:embedAndSignAppleFrameworkForXcode

Phía Swift chỉ có hai file nhỏ:

• iosApp/iosApp/iOSApp.swift gọi SharedKoinKt.doInitApp() khi app khởi động.
• iosApp/iosApp/ContentView.swift bọc MainViewControllerKt.MainViewController(), một UIViewController chứa toàn bộ giao diện Compose Multiplatform.

Mọi màn hình bạn thấy trên iOS đều là code Kotlin trong commonMain, giống hệt trên Android.

Mô hình này (một framework Kotlin, một app shell Swift mỏng, Xcode gọi Gradle trong build phase) là cách tích hợp phổ biến của các project KMP. Tham khảo: iOS integration methods.

Phần 2: Tạo Config.xcconfig

Android đọc Supabase URL, các key và flag từ local.properties. iOS không có BuildConfig, nên giá trị đi đường khác:

iosApp/Configuration/Config.xcconfig
-> Info.plist (các dòng $(SUPABASE_URL), $(SUPABASE_PUBLISHABLE_KEY)...)
-> iosAppBuildConfig() trong shared-app/src/iosMain/.../SharedKoin.kt
-> AppBuildConfig, cùng data class mà Android điền từ BuildConfig

Tạo file từ template ở repo root:

cp iosApp/Configuration/Config.xcconfig.example iosApp/Configuration/Config.xcconfig

Config.xcconfig đã nằm trong .gitignore. Mở nó và điền:

Vì sao có dòng SLASH = /? Trong file xcconfig, // mở đầu một comment. Nếu bạn dán thẳng URL đầy đủ, giá trị bị cắt ngay sau https:. Template định nghĩa SLASH riêng rồi ghép lại.

Flag PREMIUM_GATE_ENABLED chỉ bật khi giá trị đúng bằng true. Gõ sai thì tính năng trả phí bị tắt, và đó là hướng an toàn.

Google Sign-In Trên iOS

Google không cho một web client redirect về custom URL scheme của app, nên iOS cần một iOS OAuth client riêng trong Google Cloud Console, tạo với bundle ID com.creative.kta. Sau khi tạo:

1. Điền client ID vào GOOGLE_IOS_CLIENT_ID và bản viết ngược vào GOOGLE_IOS_CLIENT_ID_REVERSED. Info.plist khai báo bản viết ngược trong CFBundleURLSchemes để Google redirect về được app.
2. Thêm iOS client ID này vào Google provider trong Supabase Auth, nếu không Supabase từ chối token vì sai audience.

Lúc khởi động, hàm checkGoogleSignInConfiguration log cảnh báo nếu GOOGLE_IOS_CLIENT_ID trống, và log lỗi nếu URL scheme trong Info.plist không khớp với client ID.

Phần 3: Chạy Từ Xcode

1. Mở iosApp/iosApp.xcodeproj bằng Xcode.
2. Chọn scheme iosApp và một iPhone Simulator ở thanh công cụ.
3. Bấm Run (Cmd + R).

Lần build đầu rất chậm. Gradle tải toolchain Kotlin/Native rồi compile mọi module cho iOS. Các lần sau nhanh hơn nhiều nhờ cache. Theo dõi tiến độ trong Report navigator của Xcode, mục build phase "Build Shared framework".

App mở lên với cùng màn hình Splash và Menu như Android, kể cả mọi chuỗi bạn đã sửa trong commonMain.

Phần 4: Build Từ Terminal

xcodebuild -project iosApp/iosApp.xcodeproj -scheme iosApp -sdk iphonesimulator \
  -destination 'platform=iOS Simulator,name=iPhone 16' build

Thay iPhone 16 bằng tên một Simulator có trên máy bạn (xcrun simctl list devices available liệt kê chúng).

Đừng dùng -destination 'generic/platform=iOS Simulator'. Destination generic yêu cầu build cả kiến trúc x86_64, trong khi không module nào khai báo target đó, và bước sync Compose resources sẽ fail.

Phần 5: Chạy Test Trên iOS

Trên Mac, allTests của mỗi KMP module chạy test trên cả JVM và iOS Simulator:

./gradlew :core:iosSimulatorArm64Test
./gradlew :feature:game:allTests

commonTest chạy hai lần, một lần trên JVM và một lần trên Kotlin/Native. Một test có thể pass trên JVM và fail trên iOS, ví dụ khi code chung vô tình dựa vào hành vi chỉ JVM mới có. Vì vậy Android xanh chưa có nghĩa là iOS xanh.

Khác Biệt Bạn Sẽ Thấy Trên iOS

Các khác biệt này nằm ở Koin binding của từng nền tảng (DataModule.ios.kt so với DataModule.android.kt). Giao diện chung không có nhánh if (platform) nào.

Bảng Xử Lý Lỗi

Checkpoint

Bạn hoàn tất bài này khi:

• App chạy trên iOS Simulator và vào được Menu,
• Splash và Menu hiện giống bản Android,
• Lệnh xcodebuild ở Phần 4 kết thúc với BUILD SUCCEEDED,
• git status không liệt kê iosApp/Configuration/Config.xcconfig.