[Flutter] 모바일 앱에 백그라운드 알림 기능 추가하기 (Android)

업무에서 사용하는 관제 대시보드 화면을 앱으로 만드는 과정 중에서 알림 기능이 필요했습니다. 

Flutter 앱에 주기적인 백그라운드 알림 기능을 추가하는 과정에서 시행착오, 전체 코드, 트러블 슈팅까지 기록해 보겠습니다.

추가한 기능은 간단하게 15분 마다 주기적인 알람이 오도록 하기 + 알림 테스트 버튼을 사용해서 현재 시간 알람 받기를 구현했습니다. 이렇게 테스트 한 후 실제로 필요한 알람 기능을 자유자재로 구현하면 되겠죠. 

 

목차

1. 필요한 패키지 설치
2. Android 설정
3. 알림 서비스 구현
4. 앱 초기화
5. UI에 테스트 버튼 추가
6. 트러블슈팅

---

1. 필요한 패키지 설치

pubspec.yaml 수정

dependencies:
  flutter:
    sdk: flutter
  
  # 알림 관련 패키지
  flutter_local_notifications: ^17.2.3
  workmanager:
    git:
      url: https://github.com/fluttercommunity/flutter_workmanager.git
      ref: main
      path: workmanager  # 중요!
  permission_handler: ^11.1.0

주의사항

• workmanager는 pub.dev의 최신 버전(0.5.2)이 Flutter 3.29+와 호환되지 않습니다
• GitHub에서 직접 가져와야 하며, 반드시 path: workmanager를 지정해야 합니다

flutter pub get

---

2. Android 설정

2.1 build.gradle.kts 설정

android/app/build.gradle.kts 파일 수정

plugins {
    id("com.android.application")
    id("kotlin-android")
    id("dev.flutter.flutter-gradle-plugin")
}

android {
    namespace = "com.example.test_project"
    compileSdk = 36  // 최신 SDK 사용

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
        isCoreLibraryDesugaringEnabled = true  // 주의: is 접두사
    }

    kotlinOptions {
        jvmTarget = "17"
    }

    defaultConfig {
        applicationId = "com.example.test_project"
        minSdk = flutter.minSdkVersion
        targetSdk = 36
        versionCode = 1
        versionName = "1.0"
    }

    buildTypes {
        release {
            signingConfig = signingConfigs.getByName("debug")
        }
    }
}

flutter {
    source = "../.."
}

dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.4")
}

주의: Kotlin DSL에서는 coreLibraryDesugaringEnabled 대신 isCoreLibraryDesugaringEnabled를 사용합니다.

2.2 AndroidManifest.xml 권한 추가

android/app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- 기존 권한들 -->
    <uses-permission android:name="android.permission.INTERNET" />
    
    <!-- 알림 권한 추가 (Android 13+) -->
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
    
    <!-- 백그라운드 작업 권한 -->
    <uses-permission android:name="android.permission.WAKE_LOCK"/>
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

    <application
        android:label="test_project"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher">

        <!-- WorkManager 서비스 -->
        <service
            android:name="androidx.work.impl.foreground.SystemForegroundService"
            android:foregroundServiceType="dataSync"
            android:exported="false" />

        <!-- 부팅 시 자동 시작 리시버 -->
        <receiver
            android:name="androidx.work.impl.utils.ForceStopRunnable$BroadcastReceiver"
            android:enabled="true"
            android:exported="false" />

        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:launchMode="singleTop"
            android:theme="@style/LaunchTheme"
            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
            android:hardwareAccelerated="true"
            android:windowSoftInputMode="adjustResize">

            <meta-data
                android:name="io.flutter.embedding.android.NormalTheme"
                android:resource="@style/NormalTheme" />

            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>
        </activity>

        <meta-data
            android:name="flutterEmbedding"
            android:value="2" />
    </application>
</manifest>

---

3. 알림 서비스 구현

lib/data/services/notification_service.dart 생성:

import 'package:flutter/foundation.dart';
import 'package:flutter_local_notifications/flutter_local_notifications.dart';
import 'package:intl/intl.dart';
import 'package:permission_handler/permission_handler.dart';
import 'package:workmanager/workmanager.dart';

class NotificationService {
  static const String _channelId = 'periodic_notification';
  static const String _channelName = '주기적 알림';
  static const String _taskName = 'periodicTask';

  static final FlutterLocalNotificationsPlugin _notifications =
      FlutterLocalNotificationsPlugin();

  /// 알림 서비스 초기화
  static Future<void> init() async {
    debugPrint('🔵 알림 서비스 초기화 시작');

    // Android 13 이상 알림 권한 요청
    await _requestPermission();

    // Android 설정
    const androidSettings = AndroidInitializationSettings('@mipmap/ic_launcher');
    const iosSettings = DarwinInitializationSettings(
      requestAlertPermission: true,
      requestBadgePermission: true,
      requestSoundPermission: true,
    );

    const initSettings = InitializationSettings(
      android: androidSettings,
      iOS: iosSettings,
    );

    final result = await _notifications.initialize(
      initSettings,
      onDidReceiveNotificationResponse: (details) {
        debugPrint('📱 알림 클릭: ${details.payload}');
      },
    );

    debugPrint('✅ 알림 초기화 결과: $result');

    // 알림 채널 생성
    const androidChannel = AndroidNotificationChannel(
      _channelId,
      _channelName,
      description: '주기적인 알림을 받습니다',
      importance: Importance.max,
      enableVibration: true,
      playSound: true,
      enableLights: true,
    );

    final platform = _notifications.resolvePlatformSpecificImplementation<
        AndroidFlutterLocalNotificationsPlugin>();

    if (platform != null) {
      await platform.createNotificationChannel(androidChannel);
      debugPrint('✅ 알림 채널 생성 완료: $_channelId');
    }
  }

  /// 알림 권한 요청
  static Future<void> _requestPermission() async {
    final status = await Permission.notification.status;
    debugPrint('📱 현재 알림 권한: $status');

    if (status.isDenied || status.isPermanentlyDenied) {
      final result = await Permission.notification.request();
      debugPrint('📱 알림 권한 요청 결과: $result');
    }
  }

  /// 백그라운드 작업 시작
  static Future<void> startBackgroundTask() async {
    await Workmanager().initialize(
      callbackDispatcher,
    );

    await Workmanager().registerPeriodicTask(
      _taskName,
      _taskName,
      frequency: const Duration(minutes: 15), // Android 최소값
      constraints: Constraints(
        networkType: NetworkType.notRequired,
      ),
    );

    debugPrint('✅ 백그라운드 작업 시작');
  }

  /// 알림 표시
  static Future<void> showNotification() async {
    debugPrint('🔵 알림 표시 시도');
    
    try {
      final now = DateTime.now();
      final formattedDate = DateFormat('yyyy-MM-dd HH:mm:ss').format(now);

      const androidDetails = AndroidNotificationDetails(
        _channelId,
        _channelName,
        channelDescription: '주기적인 알림을 받습니다',
        importance: Importance.max,
        priority: Priority.high,
        showWhen: true,
        enableVibration: true,
        playSound: true,
        enableLights: true,
        icon: '@mipmap/ic_launcher',
        ticker: '새 알림',
      );

      const details = NotificationDetails(android: androidDetails);

      final id = now.millisecondsSinceEpoch ~/ 1000;
      
      await _notifications.show(
        id,
        '테스트 앱',
        '지금은 $formattedDate입니다.',
        details,
        payload: formattedDate,
      );

      debugPrint('✅ 알림 표시 완료: ID=$id');
    } catch (e) {
      debugPrint('❌ 알림 표시 실패: $e');
    }
  }

  /// 백그라운드 작업 중지
  static Future<void> stopBackgroundTask() async {
    await Workmanager().cancelAll();
    debugPrint('✅ 백그라운드 작업 중지');
  }
}

/// 백그라운드에서 실행될 콜백
@pragma('vm:entry-point')
void callbackDispatcher() {
  Workmanager().executeTask((task, inputData) async {
    await NotificationService.showNotification();
    return Future.value(true);
  });
}

---

4. 앱 초기화

lib/main.dart

import 'package:flutter/material.dart';
import 'app.dart';
import 'data/services/notification_service.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 알림 서비스 초기화 (await 필수!)
  await NotificationService.init();
  await NotificationService.startBackgroundTask();

  runApp(const App());
}

---

5. UI에 테스트 버튼 추가

대시보드 화면에 테스트 버튼을 추가합니다.

// 알림 테스트 버튼
Container(
  padding: const EdgeInsets.symmetric(horizontal: 16),
  child: ElevatedButton(
    onPressed: () async {
      debugPrint('🔵 알림 테스트 버튼 클릭됨');
      try {
        await NotificationService.showNotification();
        debugPrint('✅ 알림 요청 완료');
      } catch (e) {
        debugPrint('❌ 알림 요청 실패: $e');
      }
    },
    style: ElevatedButton.styleFrom(
      backgroundColor: Colors.blue[700],
      minimumSize: const Size(double.infinity, 40),
    ),
    child: const Text(
      '알림 테스트',
      style: TextStyle(color: Colors.white),
    ),
  ),
),

---

6. 트러블슈팅

문제 1: workmanager 버전 충돌

에러:

Unresolved reference: shim
Unresolved reference: PluginRegistrantCallback

원인: pub.dev의 workmanager 0.5.2가 Flutter 3.29+와 호환되지 않음

해결: GitHub에서 직접 가져오기

workmanager:
  git:
    url: https://github.com/fluttercommunity/flutter_workmanager.git
    ref: main
    path: workmanager  # 이 부분 중요!

 

문제 2: flutter_local_notifications 빌드 에러

에러:

error: reference to bigLargeIcon is ambiguous

원인: flutter_local_notifications 16.3.0이 Android SDK 36과 호환되지 않음

해결: 최신 버전으로 업데이트

flutter_local_notifications: ^17.2.3

 

문제 3: NetworkType.not_required 에러

에러:

Unresolved reference: not_required

원인: workmanager 최신 버전에서 API가 변경됨

해결: snake_case를 camelCase로 변경

// 변경 전
networkType: NetworkType.not_required

// 변경 후
networkType: NetworkType.notRequired

 

문제 4: coreLibraryDesugaringEnabled 에러

에러:

Unresolved reference: coreLibraryDesugaringEnabled

원인: Kotlin DSL에서는 boolean 프로퍼티에 is 접두사 사용

해결:

compileOptions {
    isCoreLibraryDesugaringEnabled = true  // is 추가
}

 

문제 5: 알림이 표시되지 않음

증상: 로그는 정상인데 알림이 안 보임

I/NotificationManager: notify(0, null, Notification...

원인:

1. 알림 권한이 허용되지 않음
2. 앱을 재설치하지 않고 업데이트함

해결:

# 앱 완전히 삭제
adb uninstall com.example.test_project

# 클린 빌드
flutter clean
flutter pub get

# 재설치
flutter run

재설치 후 설정 > 애플리케이션 > 앱 이름 > 알림에서,

• ✅ 알림 허용
• ✅ 소리 및 진동
• ✅ 잠금화면에서 내용 표시

모두 켜져 있는지 확인!

 

문제 6: 삼성 갤럭시 추가 설정 

삼성 기기의 경우 배터리 최적화 때문에 백그라운드 알림이 제한될 수 있다고 합니다. 그럼 아래와 같은 추가 설정이 필요합니다.

추가 설정:

1. 설정 > 배터리 > 배터리 사용량 > test_project → "제한 없음"
2. 설정 > 앱 > test_project > 백그라운드 사용 제한 → "제한 안 함"

---

테스트 방법

즉시 알림 테스트 (디버그 모드)

flutter run

• 앱 실행 후 "알림 테스트" 버튼 클릭
• 즉시 알림이 표시되어야 함

백그라운드 알림 테스트 (APK)

# Release APK 빌드
flutter build apk --release

# APK 위치
# build/app/outputs/flutter-apk/app-release.apk

• APK를 폰에 설치
• 앱 실행 후 백그라운드로 전환
• 15분마다 알림 확인

---

로그 확인

정상 동작 시 다음 로그가 표시됩니다:

앱 초기화:

🔵 알림 서비스 초기화 시작
📱 현재 알림 권한: granted
✅ 알림 초기화 결과: true
✅ 알림 채널 생성 완료: periodic_notification
✅ 백그라운드 작업 시작

버튼 클릭:

🔵 알림 테스트 버튼 클릭됨
🔵 알림 표시 시도
✅ 알림 표시 완료: ID=1728389045
✅ 알림 요청 완료

---

결론

Flutter에서 백그라운드 알림을 구현하는 것은 여러 단계와 설정이 필요합니다:

1. ✅ 최신 패키지 버전 사용 (호환성 확인 필수)
2. ✅ Android 권한 및 서비스 설정
3. ✅ 알림 채널 생성
4. ✅ 권한 요청 구현
5. ✅ 앱 완전 재설치로 테스트

특히 Flutter 3.29+ 환경에서는 workmanager를 GitHub에서 직접 가져와야 하는 점이 중요했습니다.

이제 앱이 백그라운드에서도 주기적으로 알림을 보낼 수 있습니다! 🎉

성공적으로 알림이 온다!!!!

---

참고 자료

• flutter_local_notifications 공식 문서
• workmanager GitHub
• permission_handler 공식 문서
• Android WorkManager 가이드