Flutter 디지털 사이니지 앱 개발 가이드

1.1. 애플리케이션의 목적

본 문서는 Android 및 Android TV 플랫폼에서 작동하는 디지털 사이니지 클라이언트 애플리케이션을 Flutter를 통해 개발하는 과정을 안내한다. 이 애플리케이션은 서버 환경 및 PostgreSQL 데이터베이스와 통신하여 동적 콘텐츠(이미지 및 비디오)를 로컬에 다운로드하고, 이를 슬라이드쇼 형태로 재생하며, 주기적으로 콘텐츠를 갱신하는 것을 목표로 한다.

1.2. 핵심 기술 개요

개발에는 다음과 같은 핵심 기술이 사용된다:

• Flutter: Google에서 개발한 UI 툴킷으로, 단일 코드베이스를 사용하여 Android, iOS, 웹, 데스크톱 등 다양한 플랫폼을 위한 네이티브 애플리케이션을 구축할 수 있다. 본 프로젝트에서는 Android (일반 OS) 및 Android TV OS용 클라이언트 개발에 활용된다.
• Dart: Flutter 애플리케이션 개발에 사용되는 객체 지향 프로그래밍 언어이다.
• Android (Standard & TV OS): 애플리케이션이 배포될 대상 운영체제이다. 특히 Android TV OS의 특성을 고려한 UI/UX 및 네비게이션 구현이 중요하다.
• PostgreSQL: 백엔드 데이터베이스 시스템으로, 클라이언트 애플리케이션은 이 데이터베이스에 저장된 콘텐츠 메타데이터를 서버 API를 통해 조회하고 활용한다.

2.1. Flutter 프로젝트 초기화

Flutter 개발 환경(Flutter SDK, Android Studio 또는 VS Code 등의 IDE)이 사전에 구축되어 있다는 가정 하에, 다음 명령어를 사용하여 새로운 Flutter 프로젝트를 생성한다:

flutter create digital_signage_app

이 명령어는 digital_signage_app이라는 이름의 Flutter 프로젝트 기본 구조를 생성한다.

2.2. 필수 Android Manifest 구성 (android/app/src/main/AndroidManifest.xml)

애플리케이션의 올바른 작동과 특정 기능 활성화를 위해 AndroidManifest.xml 파일에 몇 가지 중요한 설정을 추가해야 한다.

인터넷 권한

서버 통신 및 파일 다운로드를 위해 필수적이다.

<uses-permission android:name="android.permission.INTERNET" />

이 권한은 애플리케이션이 네트워크에 접근하여 이미지/비디오 목록 및 실제 파일을 다운로드하는 데 기본적으로 요구된다.

저장 공간 권한

파일을 로컬 저장소에 다운로드하고 관리하기 위해서는 저장 공간 접근 권한이 필요하다. Android 버전별로 저장 공간 접근 방식에 차이가 있으므로 이를 고려해야 한다.

Android 10 (API 레벨 29) 미만 버전에서는 일반적으로 외부 저장소에 대한 광범위한 접근을 위해 다음 권한이 사용되었다:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

Android 10 이상에서는 Scoped Storage 모델이 도입되어 앱이 외부 저장소에 접근하는 방식이 변경되었다. 앱별 디렉토리(app-specific directories)에 파일을 저장하는 경우, 해당 앱의 파일에 대해서는 명시적인 저장 공간 권한이 필요하지 않을 수 있다. path_provider와 같은 플러그인은 이러한 앱별 디렉토리 경로를 얻는 데 사용된다.

그러나 flutter_downloader와 같은 다운로드 관리 플러그인이 공유 저장 공간을 사용하거나 특정 기능을 위해 더 넓은 접근 권한을 요구하는 경우, 여전히 위 권한들이 필요할 수 있으며, 런타임에 사용자에게 권한을 요청해야 한다. permission_handler 패키지는 런타임 권한 요청을 처리하는 표준적인 방법이다.

3.1. 부팅 시 자동 실행

애플리케이션(또는 콘텐츠 갱신을 위한 백그라운드 서비스)은 Android 장치(일반 또는 TV)가 부팅될 때 자동으로 시작되어야 한다.

핵심 Android 메커니즘

이는 android.intent.action.BOOT_COMPLETED 시스템 브로드캐스트를 수신하는 BroadcastReceiver를 사용하여 구현된다.

권한

AndroidManifest.xml에 android.permission.RECEIVE_BOOT_COMPLETED 권한이 필요하다.

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

BroadcastReceiver 구현 (Kotlin 예제)

package com.example.digital_signage_app // 앱의 패키지 이름으로 변경

import android.content.BroadcastReceiver
import android.content.Context
import android.content.Intent
import android.util.Log

class StartupReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        if (intent.action == Intent.ACTION_BOOT_COMPLETED) {
            Log.d("StartupReceiver", "Boot completed, attempting to start service or activity.")
            // 옵션 1: Flutter 액티비티 시작
            // val activityIntent = Intent(context, MainActivity::class.java).apply {
            //     flags = Intent.FLAG_ACTIVITY_NEW_TASK
            // }
            // context.startActivity(activityIntent)
            
            // 옵션 2: Flutter 백그라운드 서비스 시작 (플러그인 사용 권장)
            // 예: flutter_background_service 또는 workmanager
            // 특정 플러그인 문서를 참조하여 부팅 시 자동 시작 설정.
        }
    }
}

AndroidManifest.xml에 등록

<application ...>
    <receiver android:name=".StartupReceiver" android:enabled="true" android:exported="false">
        <intent-filter>
            <action android:name="android.intent.action.BOOT_COMPLETED" />
        </intent-filter>
    </receiver>
   ...
</application>

flutter_background_service, android_alarm_manager_plus, workmanager와 같은 플러그인을 활용하면 부팅 시 자동 실행 및 백그라운드 작업 관리를 더 쉽게 구현할 수 있다.

3.2. 전체 화면 모드

애플리케이션은 시스템 바(상태 바, 네비게이션 바)를 숨기고 전체 화면을 차지해야 한다. Flutter의 SystemChrome API를 사용한다.

import 'package:flutter/services.dart';

void enableFullScreenMode() {
  SystemChrome.setEnabledSystemUIMode(SystemUiMode.immersiveSticky);
  // 또는 이전 방식:
  // SystemChrome.setEnabledSystemUIOverlays([]); // 모든 오버레이 숨김
}

SystemUiMode.immersiveSticky는 사용자가 화면 가장자리에서 스와이프하면 시스템 바가 잠시 나타났다가 다시 사라지는 지속적인 전체 화면 모드이다. 일반적으로 main() 함수 또는 메인 앱 위젯의 initState에서 호출된다.

3.3. 사용자 인증

import 'package:flutter_secure_storage/flutter_secure_storage.dart';

final storage = FlutterSecureStorage();

// 토큰 저장
await storage.write(key: 'auth_token', value: receivedToken);

// 토큰 읽기
String? token = await storage.read(key: 'auth_token');

String? token = await storage.read(key: 'auth_token');
if (token != null && token.isNotEmpty) {
  // 서버로 토큰 유효성 검사 (선택 사항이지만 권장)
  // 유효하면 메인 앱 화면으로 이동.
} else {
  // 로그인 화면으로 이동.
}

3.4. 콘텐츠 가져오기 및 로컬 캐싱 (이미지/비디오)

// dio 패키지 사용 예시
import 'package:dio/dio.dart';

Future fetchFileList() async {
  Dio dio = Dio();
  String? token = await storage.read(key: 'auth_token'); // flutter_secure_storage 사용

  try {
    Response response = await dio.get(
      'YOUR_API_ENDPOINT/files',
      options: Options(
        headers: {
          'Authorization': 'Bearer $token',
        },
      ),
    );
    // response.data 처리 (파일 메타데이터 목록)
    print(response.data);
  } catch (e) {
    print('Error fetching file list: $e');
  }
}

import 'package:path_provider/path_provider.dart';
import 'package:flutter_downloader/flutter_downloader.dart';

Future downloadFile(String url, String fileName) async {
  final directory = await getApplicationDocumentsDirectory();
  final localPath = '${directory.path}/$fileName';

  final taskId = await FlutterDownloader.enqueue(
    url: url,
    savedDir: directory.path,
    fileName: fileName,
    showNotification: true, // 알림 표시 여부
    openFileFromNotification: true, // 알림 클릭 시 파일 열기 여부
  );
}

// main.dart에 FlutterDownloader 초기화 필요
// void main() async {
//   WidgetsFlutterBinding.ensureInitialized();
//   await FlutterDownloader.initialize(
//     debug: true // 디버그 로그 활성화
//   );
//   runApp(MyApp());
// }

// workmanager 사용 예시
import 'package:workmanager/workmanager.dart';

void callbackDispatcher() {
  Workmanager().executeTask((task, inputData) {
    print("Native called background task: $task"); // 실제 콘텐츠 새로고침 로직 호출
    // fetchFileList() 및 동기화 로직 수행
    return Future.value(true);
  });
}

void schedulePeriodicRefresh() {
  Workmanager().initialize(
    callbackDispatcher,
    isInDebugMode: true,
  );
  Workmanager().registerPeriodicTask(
    "contentRefreshTaskUniqueName", // 고유 이름
    "contentRefreshTask", // 작업 이름
    frequency: Duration(minutes: 30),
    constraints: Constraints(
      networkType: NetworkType.connected,
    ),
  );
}

3.5. 선택적 파일 동기화

주기적 새로고침 시, 로컬 파일 목록과 서버 파일 목록(메타데이터에 버전/타임스탬프 포함)을 비교한다. 새 파일이나 수정된 파일만 다운로드하고, 서버 목록에 없는 로컬 파일은 삭제한다.

로직 개요:

1. 서버에서 최신 파일 메타데이터 목록을 가져온다.
2. 로컬에 저장된 파일 메타데이터 목록(또는 실제 파일 정보)을 가져온다.
3. 두 목록을 비교하여 다음을 식별한다:
   • 다운로드할 파일: 서버에는 있지만 로컬에는 없거나, 로컬 버전보다 최신인 파일.
   • 삭제할 파일: 로컬에는 있지만 서버 목록에는 없는 파일.
4. 식별된 파일들을 다운로드하거나 삭제한다.

파일 내용의 해시(예: MD5, SHA256)를 사용하면 타임스탬프보다 더 정확한 변경 감지가 가능하다.

4.1. TV용 UI/UX 모범 사례

• 10피트 UI: 멀리서 보는 것을 고려하여 큰 글꼴, 선명한 시각 자료, 높은 대비를 사용한다.
• 간단한 네비게이션: D-패드 네비게이션은 직관적이고 예측 가능해야 한다.
• 포커스 하이라이트: 현재 포커스된 요소를 명확하게 표시한다.
• 레이아웃: 가로 방향을 주로 사용하며, 콘텐츠 탐색에는 그리드 레이아웃이 일반적이다.
• 혼잡함 피하기: UI를 깔끔하게 유지하고 콘텐츠에 집중한다.