Flutter 튜토리얼 56편: Android 플랫폼 통합

Why#

NOTE

Flutter 앱을 Android 기기나 에뮬레이터에서 실행하려면 Android SDK와 개발 도구가 필요합니다. Android Studio가 이 모든 것을 한 번에 설치하고 관리할 수 있게 해줍니다.

1
Flutter SDK → Android Studio → Android SDK → 에뮬레이터/기기

What#

NOTE

Android 개발에 필요한 구성 요소입니다.

구성 요소	역할
Android Studio	IDE와 SDK 관리 도구
Android SDK	Android 앱 빌드에 필요한 라이브러리
SDK Platform-Tools	ADB 등 명령줄 도구
Android Emulator	가상 기기에서 앱 테스트

How#

TIP

1. Android Studio 설치

Android Studio 공식 사이트에서 다운로드하여 설치합니다.

2. SDK Manager에서 필요한 도구 설치

Android Studio 실행 후 Tools > SDK Manager를 엽니다.

SDK Platforms 탭에서:

• API Level 36 이상 선택

SDK Tools 탭에서 다음을 선택합니다:

• Android SDK Build-Tools
• Android SDK Command-line Tools
• Android Emulator
• Android SDK Platform-Tools

3. 라이선스 동의

1
flutter doctor --android-licenses

각 라이선스를 읽고 ‘y’를 입력하여 동의합니다.

4. 에뮬레이터 설정

Tools > Device Manager에서 Create Virtual Device를 클릭합니다.

1
1. Phone 또는 Tablet 선택
2
2. 기기 정의 선택 (예: Pixel 6)
3
3. 시스템 이미지 선택 (x86 또는 ARM)
4
4. Graphics acceleration: Hardware 선택
5
5. Finish 클릭

5. 설정 확인

1
flutter doctor

Android toolchain과 Android Studio 항목이 녹색 체크로 표시되어야 합니다.

1
flutter emulators && flutter devices

설정된 에뮬레이터와 연결된 기기 목록이 표시됩니다.

Watch out#

WARNING

실제 Android 기기에서 테스트하려면 개발자 옵션을 활성화해야 합니다.

1
설정 → 휴대전화 정보 → 빌드 번호 7회 탭
2
설정 → 개발자 옵션 → USB 디버깅 활성화

USB로 연결 후 기기에서 디버깅 허용 팝업이 뜨면 승인합니다.

결론: Android Studio와 SDK를 설치하고 라이선스에 동의하면 Flutter 앱을 에뮬레이터나 실제 기기에서 실행할 수 있습니다.

Why#

NOTE

앱이 시작될 때 Flutter 엔진이 초기화되는 동안 빈 화면이 보이면 사용자 경험이 나빠집니다. 스플래시 화면을 설정하면 앱 로고나 브랜드 이미지를 표시하며 자연스럽게 앱을 시작할 수 있습니다.

1
앱 실행 → 스플래시 화면 표시 → Flutter 엔진 초기화 → 앱 화면

What#

NOTE

Android 스플래시 화면은 두 가지 방식으로 구현할 수 있습니다.

방식	지원 버전	특징
LaunchTheme	모든 버전	windowBackground로 Drawable 표시
SplashScreen API	Android 12+	아이콘 애니메이션, 배경색 등 세부 설정

Android 12 미만과 이상을 모두 지원하려면 두 가지를 함께 구현합니다.

How#

TIP

1. 스플래시 이미지 준비

android/app/src/main/res/drawable/ 폴더에 이미지를 추가합니다.

launch_background.xml (기본 생성됨):

1
<?xml version="1.0" encoding="utf-8"?>
2
<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
3
    <item android:drawable="@color/splash_background"/>
4
    <item>
5
        <bitmap
6
            android:gravity="center"
7
            android:src="@drawable/splash_logo"/>
8
    </item>
9
</layer-list>

2. styles.xml에 테마 정의

android/app/src/main/res/values/styles.xml:

1
<?xml version="1.0" encoding="utf-8"?>
2
<resources>
3
    <!-- 스플래시 화면 테마 -->
4
    <style name="LaunchTheme" parent="@android:style/Theme.Black.NoTitleBar">
5
        <item name="android:windowBackground">@drawable/launch_background</item>
6
    </style>
7

8
    <!-- 일반 테마 (스플래시 후 적용) -->
9
    <style name="NormalTheme" parent="@android:style/Theme.Black.NoTitleBar">
10
        <item name="android:windowBackground">@drawable/normal_background</item>
11
    </style>
12
</resources>

3. AndroidManifest.xml 설정

1
<activity
2
    android:name=".MainActivity"
3
    android:theme="@style/LaunchTheme"
4
    android:launchMode="singleTop"
5
    android:exported="true">
6

7
    <!-- Flutter가 NormalTheme으로 전환하도록 설정 -->
8
    <meta-data
9
        android:name="io.flutter.embedding.android.NormalTheme"
10
        android:resource="@style/NormalTheme"/>
11

12
    <intent-filter>
13
        <action android:name="android.intent.action.MAIN"/>
14
        <category android:name="android.intent.category.LAUNCHER"/>
15
    </intent-filter>
16
</activity>

4. Android 12+ SplashScreen API 사용

android/app/src/main/res/values-v31/styles.xml (Android 12용):

1
<?xml version="1.0" encoding="utf-8"?>
2
<resources>
3
    <style name="LaunchTheme" parent="@android:style/Theme.Black.NoTitleBar">
4
        <item name="android:windowSplashScreenBackground">@color/splash_background</item>
5
        <item name="android:windowSplashScreenAnimatedIcon">@drawable/splash_logo</item>
6
    </style>
7
</resources>

5. 스플래시 애니메이션 제어 (선택)

MainActivity.kt:

1
import android.os.Build
2
import android.os.Bundle
3
import androidx.core.view.WindowCompat
4
import io.flutter.embedding.android.FlutterActivity
5

6
class MainActivity : FlutterActivity() {
7
    override fun onCreate(savedInstanceState: Bundle?) {
8
        WindowCompat.setDecorFitsSystemWindows(window, false)
9

10
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
11
            // 스플래시 화면 페이드 아웃 애니메이션 비활성화
12
            splashScreen.setOnExitAnimationListener { splashScreenView ->
13
                splashScreenView.remove()
14
            }
15
        }
16

17
        super.onCreate(savedInstanceState)
18
    }
19
}

Watch out#

WARNING

NormalTheme의 배경색은 Flutter UI의 주요 배경색과 비슷해야 합니다. 그렇지 않으면 스플래시 화면과 앱 화면 사이에 색상 깜빡임이 발생합니다.

1
<!-- ❌ 스플래시는 파란색, 앱은 흰색 → 깜빡임 -->
2
<style name="LaunchTheme">
3
    <item name="android:windowBackground">@color/blue</item>
4
</style>
5
<style name="NormalTheme">
6
    <item name="android:windowBackground">@color/white</item>
7
</style>
8

9
<!-- ✅ 두 테마의 배경색을 비슷하게 -->
10
<style name="LaunchTheme">
11
    <item name="android:windowBackground">@color/white</item>
12
</style>
13
<style name="NormalTheme">
14
    <item name="android:windowBackground">@color/white</item>
15
</style>

결론: LaunchTheme과 NormalTheme을 설정하고 AndroidManifest.xml에서 연결하면 앱 시작 시 스플래시 화면이 표시됩니다.

Why#

NOTE

지도, 웹뷰, 광고 SDK 등 기존 Android 네이티브 뷰를 Flutter 위젯 트리에 직접 포함해야 할 때가 있습니다. Platform Views를 사용하면 네이티브 뷰를 Flutter 앱에 임베드할 수 있습니다.

1
Flutter 위젯 트리 ← Platform View ← Android 네이티브 뷰

What#

NOTE

Android Platform Views에는 두 가지 모드가 있습니다.

모드	특징	사용 사례
Hybrid Composition	네이티브 뷰와 Flutter 위젯 혼합	대부분의 경우 권장
Texture Layer	텍스처로 렌더링, 성능 우수	단순 뷰, 터치 불필요 시

Hybrid Composition이 기본이며 대부분의 경우 권장됩니다.

How#

TIP

1. 플랫폼 뷰 팩토리 생성

android/app/src/main/kotlin/.../NativeViewFactory.kt:

1
package com.example.myapp
2

3
import android.content.Context
4
import android.view.View
5
import android.widget.TextView
6
import io.flutter.plugin.platform.PlatformView
7
import io.flutter.plugin.platform.PlatformViewFactory
8
import io.flutter.plugin.common.StandardMessageCodec
9

10
class NativeViewFactory : PlatformViewFactory(StandardMessageCodec.INSTANCE) {
11
    override fun create(context: Context, viewId: Int, args: Any?): PlatformView {
12
        val creationParams = args as Map<String, Any>?
13
        return NativeView(context, viewId, creationParams)
14
    }
15
}
16

17
class NativeView(
18
    context: Context,
19
    id: Int,
20
    creationParams: Map<String, Any>?
21
) : PlatformView {
22
    private val textView: TextView = TextView(context).apply {
23
        text = creationParams?.get("text") as? String ?: "Hello from Android!"
24
        textSize = 24f
25
    }
26

27
    override fun getView(): View = textView
28

29
    override fun dispose() {}
30
}

2. MainActivity에서 팩토리 등록

MainActivity.kt:

1
package com.example.myapp
2

3
import io.flutter.embedding.android.FlutterActivity
4
import io.flutter.embedding.engine.FlutterEngine
5

6
class MainActivity : FlutterActivity() {
7
    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
8
        super.configureFlutterEngine(flutterEngine)
9

10
        flutterEngine
11
            .platformViewsController
12
            .registry
13
            .registerViewFactory(
14
                "native-view", // viewType 식별자
15
                NativeViewFactory()
16
            )
17
    }
18
}

3. Flutter에서 Platform View 사용

1
import 'package:flutter/material.dart';
2
import 'package:flutter/services.dart';
3

4
class NativeViewExample extends StatelessWidget {
5
  const NativeViewExample({super.key});
6

7
  @override
8
  Widget build(BuildContext context) {
9
    // viewType은 Android에서 등록한 것과 일치해야 함
10
    const String viewType = 'native-view';
11

12
    // creationParams로 초기 데이터 전달
13
    final Map<String, dynamic> creationParams = {
14
      'text': 'Flutter에서 전달한 텍스트',
15
    };
16

17
    return Scaffold(
18
      appBar: AppBar(title: const Text('Platform View 예제')),
19
      body: Column(
20
        children: [
21
          const Text('Flutter 위젯'),
22

23
          // Platform View 임베드
24
          SizedBox(
25
            height: 100,
26
            child: AndroidView(
27
              viewType: viewType,
28
              creationParams: creationParams,
29
              creationParamsCodec: const StandardMessageCodec(),
30
            ),
31
          ),
32

33
          const Text('Flutter 위젯 계속'),
34
        ],
35
      ),
36
    );
37
  }
38
}

Hybrid Composition 명시적 사용

1
AndroidView(
2
  viewType: viewType,
3
  creationParams: creationParams,
4
  creationParamsCodec: const StandardMessageCodec(),
5
  // Hybrid Composition 강제 (기본값)
6
  layoutDirection: TextDirection.ltr,
7
)

Watch out#

WARNING

Platform Views는 성능 오버헤드가 있습니다. 스크롤 리스트 안에 여러 Platform View를 넣으면 성능이 저하됩니다.

1
// ❌ 리스트 아이템마다 Platform View
2
ListView.builder(
3
  itemCount: 100,
4
  itemBuilder: (context, index) => AndroidView(
5
    viewType: 'native-view',
6
  ),
7
)
8

9
// ✅ Platform View 개수 최소화
10
Column(
11
  children: [
12
    Expanded(child: FlutterListView()), // Flutter 위젯 사용
13
    SizedBox(
14
      height: 200,
15
      child: AndroidView(viewType: 'map-view'), // 하나의 지도만
16
    ),
17
  ],
18
)

또한 Platform View 위에 Flutter 위젯을 겹치면 추가 오버헤드가 발생합니다.

결론: PlatformViewFactory를 구현하고 등록하면 AndroidView 위젯으로 네이티브 뷰를 Flutter에 임베드할 수 있습니다.

Why#

NOTE

Android 시스템은 메모리가 부족하면 백그라운드 앱을 강제 종료합니다. 사용자가 다시 앱으로 돌아왔을 때 이전 상태를 복원하지 않으면 처음부터 다시 시작해야 합니다.

1
앱 실행 → 백그라운드 → 시스템 종료 → 앱 복귀 → 상태 복원

What#

NOTE

Flutter의 RestorationMixin을 사용하면 Android의 상태 저장/복원 메커니즘과 통합됩니다.

클래스	역할
RestorationMixin	State 클래스에 복원 기능 추가
RestorableProperty	복원 가능한 값 래퍼
RestorationScope	복원 컨텍스트 제공

How#

TIP

1. MaterialApp에 restorationScopeId 설정

1
void main() {
2
  runApp(const MyApp());
3
}
4

5
class MyApp extends StatelessWidget {
6
  const MyApp({super.key});
7

8
  @override
9
  Widget build(BuildContext context) {
10
    return MaterialApp(
11
      // 복원 범위 ID 설정
12
      restorationScopeId: 'app',
13
      title: 'Restoration Demo',
14
      home: const CounterPage(),
15
    );
16
  }
17
}

2. State에 RestorationMixin 적용

1
class CounterPage extends StatefulWidget {
2
  const CounterPage({super.key});
3

4
  @override
5
  State<CounterPage> createState() => _CounterPageState();
6
}
7

8
class _CounterPageState extends State<CounterPage> with RestorationMixin {
9
  // 복원 가능한 정수 값
10
  final RestorableInt _counter = RestorableInt(0);
11

12
  @override
13
  // 이 위젯의 고유 복원 ID
14
  String? get restorationId => 'counter_page';
15

16
  @override
17
  void restoreState(RestorationBucket? oldBucket, bool initialRestore) {
18
    // 복원 가능한 속성 등록
19
    registerForRestoration(_counter, 'counter');
20
  }
21

22
  @override
23
  void dispose() {
24
    _counter.dispose();
25
    super.dispose();
26
  }
27

28
  void _incrementCounter() {
29
    setState(() {
30
      _counter.value++;
31
    });
32
  }
33

34
  @override
35
  Widget build(BuildContext context) {
36
    return Scaffold(
37
      appBar: AppBar(title: const Text('카운터')),
38
      body: Center(
39
        child: Text(
40
          '${_counter.value}',
41
          style: Theme.of(context).textTheme.headlineMedium,
42
        ),
43
      ),
44
      floatingActionButton: FloatingActionButton(
45
        onPressed: _incrementCounter,
46
        child: const Icon(Icons.add),
47
      ),
48
    );
49
  }
50
}

3. 다양한 RestorableProperty 사용

1
class _FormPageState extends State<FormPage> with RestorationMixin {
2
  // 다양한 타입의 복원 가능 속성
3
  final RestorableInt _selectedIndex = RestorableInt(0);
4
  final RestorableDouble _sliderValue = RestorableDouble(0.5);
5
  final RestorableBool _isChecked = RestorableBool(false);
6
  final RestorableString _inputText = RestorableString('');
7
  final RestorableTextEditingController _controller =
8
      RestorableTextEditingController();
9

10
  @override
11
  String? get restorationId => 'form_page';
12

13
  @override
14
  void restoreState(RestorationBucket? oldBucket, bool initialRestore) {
15
    registerForRestoration(_selectedIndex, 'selected_index');
16
    registerForRestoration(_sliderValue, 'slider_value');
17
    registerForRestoration(_isChecked, 'is_checked');
18
    registerForRestoration(_inputText, 'input_text');
19
    registerForRestoration(_controller, 'text_controller');
20
  }
21

22
  @override
23
  void dispose() {
24
    _selectedIndex.dispose();
25
    _sliderValue.dispose();
26
    _isChecked.dispose();
27
    _inputText.dispose();
28
    _controller.dispose();
29
    super.dispose();
30
  }
31

32
  @override
33
  Widget build(BuildContext context) {
34
    return Scaffold(
35
      body: Column(
36
        children: [
37
          TextField(controller: _controller.value),
38
          Slider(
39
            value: _sliderValue.value,
40
            onChanged: (v) => setState(() => _sliderValue.value = v),
41
          ),
42
          Checkbox(
43
            value: _isChecked.value,
44
            onChanged: (v) => setState(() => _isChecked.value = v ?? false),
45
          ),
46
        ],
47
      ),
48
    );
49
  }
50
}

4. 네비게이션 상태 복원

1
class MyApp extends StatelessWidget {
2
  const MyApp({super.key});
3

4
  @override
5
  Widget build(BuildContext context) {
6
    return MaterialApp(
7
      restorationScopeId: 'app',
8
      // 네비게이터 상태도 복원
9
      home: const Navigator(
10
        restorationScopeId: 'navigator',
11
        pages: [
12
          MaterialPage(child: HomePage()),
13
        ],
14
        onPopPage: (route, result) => route.didPop(result),
15
      ),
16
    );
17
  }
18
}

Watch out#

WARNING

모든 데이터를 복원하려 하지 마세요. 상태 복원 데이터는 직렬화되어 저장되므로 큰 데이터는 성능에 영향을 줍니다.

1
// ❌ 대용량 데이터 복원 시도
2
class _ListPageState extends State<ListPage> with RestorationMixin {
3
  final RestorableValue<List<Product>> _products = ...; // 수백 개 아이템
4
}
5

6
// ✅ 필요한 상태만 복원 (ID, 스크롤 위치 등)
7
class _ListPageState extends State<ListPage> with RestorationMixin {
8
  final RestorableInt _selectedProductId = RestorableInt(-1);
9
  final RestorableDouble _scrollOffset = RestorableDouble(0);
10

11
  // 실제 데이터는 복원 후 다시 로드
12
}

복원 ID는 앱 전체에서 고유해야 합니다.

결론: RestorationMixin과 RestorableProperty를 사용하면 시스템이 앱을 종료해도 사용자 상태를 복원할 수 있습니다.