Flutter로 앱을 만들다 보면 Dart에서는 할 수 없는 일을 만나는 때가 온다. 기기 배터리 잔량 읽기, 특정 기기의 센서, 이미 Kotlin이나 Swift로 만들어 둔 코드 재사용 같은 것들이다. 이런 건 Android와 iOS 운영체제만 알고 있는 일이다. 마침 이 시리즈를 읽는 사람은 Kotlin과 Swift를 이미 안다. 이 글은 그 경험을 살릴 차례다.

Dart 쪽에서 배터리 잔량을 알고 싶다고 하자. 일단 "그런 함수가 있겠지" 하고 부르면 이렇게 된다.

final level = await MethodChannel('samples.flutter.dev/battery')
    .invokeMethod<int>('getBatteryLevel');

앱에서 이 줄이 실행되면 이런 에러가 난다.

MissingPluginException(No implementation found for method getBatteryLevel on channel samples.flutter.dev/battery)

Dart 코드는 문제가 없다. 받아줄 네이티브 쪽이 아직 없어서 난 에러다.

원인: Dart는 질문만 던질 뿐이고, 답은 네이티브가 한다

Flutter 앱은 Dart 코드와 Android, iOS 코드가 한 앱 안에 같이 들어 있다. 이 둘이 서로 메시지를 주고받는 통로가 플랫폼 채널이다.

• Dart(클라이언트): MethodChannel로 "이 이름의 메서드를 호출해 달라"는 메시지를 보낸다
• Android(호스트): MethodChannel로 받아서 처리하고 결과를 돌려준다
• iOS(호스트): FlutterMethodChannel로 받아서 처리하고 결과를 돌려준다

둘은 채널 이름(문자열)으로 만난다. 위 에러는 같은 이름의 채널을 듣고 있는 쪽이 없다는 뜻이다. 이제 네이티브 쪽을 채우자.

1단계: Dart 쪽에서 채널을 만든다

import 'package:flutter/services.dart';

class BatteryService {
  static const _channel = MethodChannel('samples.flutter.dev/battery');

  Future<int?> getBatteryLevel() async {
    try {
      return await _channel.invokeMethod<int>('getBatteryLevel');
    } on PlatformException catch (e) {
      print('배터리를 읽지 못했어요: ${e.message}');
      return null;
    }
  }
}

• MethodChannel('채널 이름'): 채널 이름은 앱마다 겹치지 않게 도메인/기능 모양으로 짓는다. 네이티브 쪽과 글자까지 똑같아야 한다
• invokeMethod<int>('메서드 이름'): 네이티브의 메서드를 부른다. 네이티브가 올 때까지 기다리니 await가 필요하다
• PlatformException: 네이티브가 "실패했다"고 돌려주면 이 예외로 온다. 비동기 글의 try/catch, HTTP 글의 DioException과 같은 자리다

이 클래스는 앞서 배운 Service 계층에 두는 게 맞다. 화면이 채널을 직접 알면 계층이 무너진다. 화면은 BatteryService.getBatteryLevel()만 부르고, 그게 채널로 가는지 플러그인으로 가는지 모르게 한다.

2단계: Android(Kotlin) 쪽에서 받는다

android/app/src/main/kotlin/.../MainActivity.kt를 연다.

import android.os.BatteryManager
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugin.common.MethodChannel

class MainActivity : FlutterActivity() {
    private val CHANNEL = "samples.flutter.dev/battery"

    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        super.configureFlutterEngine(flutterEngine)

        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL)
            .setMethodCallHandler { call, result ->
                if (call.method == "getBatteryLevel") {
                    val level = getBatteryLevel()
                    if (level != -1) {
                        result.success(level)
                    } else {
                        result.error("UNAVAILABLE", "Battery level not available.", null)
                    }
                } else {
                    result.notImplemented()
                }
            }
    }

    private fun getBatteryLevel(): Int {
        val manager = getSystemService(BATTERY_SERVICE) as BatteryManager
        return manager.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY)
    }
}

• configureFlutterEngine: Flutter 엔진이 준비될 때 호출된다. 여기서 채널을 연다
• MethodChannel(binaryMessenger, CHANNEL): Dart와 같은 이름의 채널을 연다
• setMethodCallHandler { call, result -> ... }: Dart가 invokeMethod를 부르면 이 람다가 실행된다. 트레일링 람다와 it 없이 이름을 직접 붙인 call, result다
• call.method: Dart가 부른 메서드 이름이다. 이름에 따라 분기한다
• result.success(값): 성공 결과를 돌려준다. Dart에서는 invokeMethod의 반환값이 된다
• result.error(코드, 메시지, 상세): 실패를 돌려준다. Dart에서는 PlatformException이 된다
• result.notImplemented(): 모르는 메서드라고 돌려준다. Dart에서는 MissingPluginException이 된다

Kotlin을 아는 사람에게는 익숙한 코드다. 새로 배우는 건 result 세 가지 응답뿐이다.

3단계: iOS(Swift) 쪽에서 받는다

ios/Runner/AppDelegate.swift를 연다.

import UIKit
import Flutter

@main
@objc class AppDelegate: FlutterAppDelegate {
    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        let controller = window?.rootViewController as! FlutterViewController
        let batteryChannel = FlutterMethodChannel(
            name: "samples.flutter.dev/battery",
            binaryMessenger: controller.binaryMessenger
        )

        batteryChannel.setMethodCallHandler { [weak self] (call, result) in
            guard call.method == "getBatteryLevel" else {
                result(FlutterMethodNotImplemented)
                return
            }
            self?.receiveBatteryLevel(result: result)
        }

        GeneratedPluginRegistrant.register(with: self)
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }

    private func receiveBatteryLevel(result: FlutterResult) {
        let device = UIDevice.current
        device.isBatteryMonitoringEnabled = true
        if device.batteryState == .unknown {
            result(FlutterError(code: "UNAVAILABLE", message: "Battery level not available.", details: nil))
        } else {
            result(Int(device.batteryLevel * 100))
        }
    }
}

• FlutterMethodChannel(name:binaryMessenger:): Dart와 같은 이름의 채널을 연다
• setMethodCallHandler: Dart의 호출을 받는 클로저다
• result(값): 성공, result(FlutterError(...)): 실패, result(FlutterMethodNotImplemented): 모르는 메서드다. Kotlin의 success, error, notImplemented와 짝이다

Flutter 버전이 올라가면서 iOS 프로젝트 템플릿의 AppDelegate 모양이 바뀌는 중이라, 위 코드가 내 프로젝트의 AppDelegate와 다를 수 있다. 채널을 만들고 핸들러를 거는 핵심 두 줄(FlutterMethodChannel과 setMethodCallHandler)은 같으니, 공식 문서의 현재 코드를 확인하고 내 프로젝트에 맞춰 넣는다.

삽질 포인트 1: 코드를 고치고 hot reload를 눌렀는데 그대로다

Dart 코드와 달리 네이티브 코드는 hot reload로 반영되지 않는다. Kotlin이나 Swift를 고쳤다면 앱을 완전히 끄고 다시 빌드해서 실행해야 한다. 처음 채널을 만들고 MissingPluginException이 계속 난다면 앱을 새로 빌드했는지부터 확인한다.

삽질 포인트 2: 채널 이름이 한 글자만 달라도 안 만난다

Dart의 'samples.flutter.dev/battery'와 Kotlin의 CHANNEL, Swift의 name은 문자열 비교라서 대소문자와 오타까지 일치해야 한다. 같은 이름을 상수로 한 곳에 두고 복사하는 습관이 좋다. 메서드 이름(getBatteryLevel)도 마찬가지다.

삽질 포인트 3: 무거운 일을 채널 핸들러 안에서 한다

채널 핸들러는 기본적으로 플랫폼의 메인(UI) 스레드에서 실행된다. 핸들러 안에서 오래 걸리는 일을 하면 앱이 멈춘다. 파일 읽기나 계산처럼 시간이 걸리는 건 별도 스레드나 코루틴에서 하고, 끝나면 result.success를 부른다.

값을 주고받기: 인자와 타입

Dart에서 값을 같이 보낼 때는 Map에 담는다.

final result = await _channel.invokeMethod<String>('greet', {'name': '홍길동'});

// Kotlin
val name = call.argument<String>("name")
result.success("안녕, $name")

// Swift
let args = call.arguments as? [String: Any]
let name = args?["name"] as? String ?? ""
result("안녕, \(name)")

채널로 주고받을 수 있는 타입은 표준 코덱이 지원하는 것으로 한정된다. 숫자, 불리언, 문자열, List, Map, null 같은 기본 타입이다. User 같은 내가 만든 클래스는 그대로 못 보내서 Map으로 바꿔서 보내고 받는 쪽에서 다시 만든다. 타입이 많아지면 Map의 키 이름을 양쪽에서 맞추다 오타가 나기 쉬운데, 이때는 Pigeon이라는 도구가 Dart, Kotlin, Swift의 타입이 있는 코드를 생성해 준다.

먼저 플러그인을 찾아본다

배터리, 카메라, 위치 같은 흔한 기능은 이미 누군가 플랫폼 채널로 만들어서 플러그인으로 공개해 두었다. 직접 만들기 전에 pub.dev에서 먼저 찾아본다. 예를 들어 배터리는 battery_plus 같은 패키지가 있다. 플러그인이 없거나, 회사 내부 SDK, 기기 전용 기능처럼 내가 직접 연결해야 하는 경우에 이 글의 방법을 쓴다. 플러그인도 속을 열어보면 같은 MethodChannel로 만들어져 있다.

Android, iOS 쪽 관점으로 정리하면

• Dart가 부르는 방법: MethodChannel('이름').invokeMethod('메서드', 인자)
• Android가 받는 방법: MethodChannel(binaryMessenger, '이름').setMethodCallHandler { call, result -> }
• iOS가 받는 방법: FlutterMethodChannel(name:binaryMessenger:).setMethodCallHandler { call, result in }
• 성공 응답: Kotlin result.success(값) / Swift result(값)
• 실패 응답: Kotlin result.error(...) / Swift result(FlutterError(...)) / Dart에서는 PlatformException
• 모르는 메서드: Kotlin result.notImplemented() / Swift result(FlutterMethodNotImplemented) / Dart에서는 MissingPluginException

네이티브 쪽은 평소에 쓰던 Kotlin과 Swift 그대로다. Flutter 때문에 새로 배울 건 채널 이름으로 만나고, call.method로 분기하고, result로 돌려준다는 세 가지 규칙이 전부다. 네이티브 경험이 있으면 Flutter가 못 하는 일을 직접 메꿀 수 있다는 점이 이 시리즈의 강점이기도 하다.

정리

• Dart에서 할 수 없는 기기 기능은 MethodChannel로 Android와 iOS의 네이티브 코드를 불러서 해결한다
• Dart와 네이티브는 채널 이름(문자열)으로 만나고, 받아줄 쪽이 없으면 MissingPluginException이 난다
• Dart는 invokeMethod로 부르고, Android는 MethodChannel, iOS는 FlutterMethodChannel의 setMethodCallHandler로 받아서 call.method로 분기한다
• 성공은 result.success, 실패는 result.error(Dart에서는 PlatformException), 모르는 메서드는 notImplemented로 돌려준다
• 네이티브 코드를 고치면 hot reload가 아니라 앱을 새로 빌드해야 하고, 핸들러 안에서 무거운 일을 하면 앱이 멈춘다
• 주고받을 수 있는 타입은 기본 타입으로 한정되므로 내 클래스는 Map으로 바꾸고, 타입이 많아지면 Pigeon을 쓴다
• 채널 호출은 Service 계층에 두고, 직접 만들기 전에 플러그인이 있는지 먼저 확인한다

다음 글에서는 Firebase를 앱에 연동하는 방법(Auth, Firestore, FCM)을 다뤄보겠다.