Flutter-bleepy developers

시작하기

간편하게 웹뷰 URL 호출만으로 런처를 실행하고 Client Admin에서 프로모션을 생성하여 발급받은 Secret Key에 연동된 게임을 실행합니다. 웹뷰를 구성하여 게임을 실행하고 등록한 프로모션을 진행해보세요.

WebView 구성하기

Flutter 가이드 문서는 아래 2가지 라이브러리를 필수로 사용합니다. * 필수,선택에 따라 알맞은 패키지를 설치해 주세요.

WebView 패키지 (v6) : flutter_inappwebview (필수) *v5를 사용하고 계신 클라이언트는 [Migration Guide] 링크를 참고하여 마이그레이션을 권장드립니다.
화면 활성화 여부 판단 패키지 : visibility_detector *블리피 런처 화면 백그라운드 전환 시 WebView의 pause , resume 상태 등 체크 시 필요합니다.

yaml

// pubspec.yaml dependencies: flutter: sdk: flutter # The following adds the Cupertino Icons font to your application. # Use with the CupertinoIcons class for iOS style icons. flutter_inappwebview: ^6.0.0 visibility_detector: ^0.4.0+2

1단계 : 블리피 런처 위젯 추가

Flutter 프로젝트 내에 블리피 런처를 구동하기 위해서는 WebView를 사용하는 위젯을 생성해야 합니다. 다음 가이드를 따라 진행해주시기 바랍니다.

1. dart 파일 생성

기본적으로 lib 폴더 경로에 블리피 런처가 구동될 dart 파일을 생성합니다. 가이드에서는 screens 폴더를 생성 후 bleepy_screen.dart 파일을 생성하였습니다.

2. Navigator 추가

블리피 런처 페이지 위젯으로 이동하기 위한 라우터를 추가합니다.

3. InAppWebViewSettings 옵션 추가

WebView에 사용될 옵션 값을 정의합니다.

4. WebView에 런처 URL 로드

위젯 페이지 내 InAppWebView 를 추가하고 {런처 URL}을 요청합니다.

dart

// lib/screens/bleepy_screen.dart class _BleepyLauncherScreenState extends State<BleepyLauncherScreen> { InAppWebViewController? webViewController; @override Widget build(BuildContext context) { final GlobalKey webViewKey = GlobalKey(); // 웹뷰 옵션 InAppWebViewSettings options = InAppWebViewSettings( ... javaScriptEnabled: true, // javascript 실행 여부 useHybridComposition: true, // hybrid 사용을 위한 android 웹뷰 최적화 ... ); return InAppWebView( key: webViewKey, initialUrlRequest: URLRequest(url: WebUri({런처 URL})), initialSettings: options, onWebViewCreated: (controller) { webViewController = controller; } ) } }

2단계 : 위젯 백그라운드 처리 추가

블리피 런처를 WebView 내에 구동하면 자바스크립트 로직이 핑 전송 API를 지속적 호출합니다. 따라서 위젯이 백그라운드로 이동 되었으면 inactive 상태로 처리가 되어야 합니다. 그러나 런처 위젯에서 다른 위젯으로 Navigator 를 통한 라우팅 시 예외적인 케이스가 존재합니다.

AOS - inactive 상태로 변경되지 않습니다.
IOS - inactive 상태로 변경됩니다.

AOS의 경우 라우팅 시 inactive 상태로 변경되지 않는 이슈가 있어 직접 컨트롤이 필요합니다. 다음 가이드를 따라 코드를 추가해 주세요.

1. LifeCycle 감지 설정 추가

위젯의 LifeCycle 감지를 위해 with WidgetsBindingObserver 를 사용하도록 생성합니다.

initState 에서 addObserver 를 호출합니다.
dispose 에서 removeObserver 를 호출합니다.

해당 처리들은 VisibilityDetector 라이브러리가 정상 동작하기 위해서 필요합니다.

dart

// lib/screens/bleepy_screen.dart class _BleepyLauncherScreenState extends State<BleepyLauncherScreen> with WidgetsBindingObserver{ ... @override void initState() { super.initState(); // 최초 위젯 실행 시 호출 WidgetsBinding.instance.addObserver(this); } @override void dispose() { // 위젯이 메모리에서 제거될 때 호출 WidgetsBinding.instance.removeObserver(this); super.dispose(); } ... }

2. VisibilityDetector 라이브러리 추가

VisibilityDetector 라이브러리는 현재 화면이 활성화되었는지 여부를 판단할 수 있는 라이브러리 입니다. 화면의 비활성화/활성화 여부에 따라 아래와 같은 처리가 필요합니다.

화면 비활성화 시
- WebView pause
화면 활성화 시
- WebView resume

VisibilityDetector 라이브러리는 아래 옵션 표를 참고합니다.

Interface function	Type	Description
key	key	key 값으로 필수 입력합니다.
onVisibilityChanged	void Function(VisibilityInfo)	화면의 활성화 여부 변경될 때 호출되는 콜백 메소드 입니다. VisibilityInfo 내 visibleFraction 값으로 활성화 판단합니다. `double` 형으로 전달되며 `1.0` 은 활성화, `0.0` 은 비활성화 입니다.

dart

// lib/screens/bleepy_screen.dart @override Widget build(BuildContext context) { ... // VisibilityDetector 추가 return VisibilityDetector( key: const Key("banner-screen-visibility-detector"), onVisibilityChanged: (visibilityInfo) { // visibility change event var visibleFlag = visibilityInfo.visibleFraction.toInt(); if(visibleFlag == 1){ // 화면 보여질 때 실행 webViewController?.resume(); } else { // 화면 안 보여질 때 실행 webViewController?.pause(); } }, child: SafeArea(...) ); }

3단계 : Javascript Handler 추가

블리피 런처와 Flutter 어플리케이션 간의 통신을 수행하기 위해 Javascript Handler 추가가 필요합니다. 자바스크립트 핸들러 작성 시 handlerName 값은 꼭 BlpLauncher 로 작성해야 합니다.

아래 표는 블리피 런처로부터 전달 받는 이벤트 케이스 입니다.

handlerName	Type	Description
BlpLauncher	closeLauncher	블리피 런처의 Back 버튼 UI 클릭 시 (뒤로가기 처리)

dart

// lib/screens/bleepy_screen.dart InAppWebView( key: webViewKey, initialUrlRequest: URLRequest(url: WebUri(widget.launcherUrl)), initialSettings: options, onWebViewCreated: (controller) { webViewController = controller; // 자바스크립트 핸들러 추가 controller.addJavaScriptHandler(handlerName: 'BlpLauncher', callback: (message) { final data = jsonDecode(message[0]); final key = data['type']; switch (key) { case "closeLauncher": closeLauncher(); break; default: break; } }); } )

1. closeLauncher()

블리피 런처의 Back 버튼 UI 클릭 시 Flutter에서는 뒤로가기 처리를 수행합니다.

dart

// lib/screens/bleepy_screen.dart // 런처 종료 void closeLauncher() { Navigator.of(context).pop(); }

4단계 : 런처 스크린 세로모드 고정 로직 추가

service.dart 패키지를 추가합니다. SystemChrome.setPreferredOrientations 통해 런처 스크린을 세로모드로 고정합니다.

dart

// lib/screens/bleepy_screen.dart // 화면 고정을 위해 상단에 다음 패키지를 추가 import 'package:flutter/services.dart'; @override Widget build(BuildContext context) { // ... // 세로 위아래 방향 고정 SystemChrome.setPreferredOrientations([DeviceOrientation.portraitUp, DeviceOrientation.portraitDown]); return VisibilityDetector( ... child: SafeArea(...) ); }

개발에 대한 추가 설명이 더 필요하신가요?

"[Client Admin] 로그인 → 오른쪽 하단 채널톡 위젯" 클릭 후 개발 카테고리에 문의 남겨주시면 기술 개발팀에서 확인 후 연락드리겠습니다.

v1.0.6