Flutter - InAppWebView 5.8.0 > 6.0.0 마이그레이션 가이드

개요

인앱웹뷰가 6.0.0으로 버전업이 되었다.
이번에 마이그레이션을 하면서 느낀점은 편의성이 많이 좋아진 것 같은데 자세히는 안써봐서 잘 모르겠다.
우선은 내 프로젝트에 있는 코드들을 마이그레이션하면서 수정하였던 부분들을 기준으로 기재하도록 하겠다.
포스팅에서 인앱웹뷰 마이그레이션의 기준은 5.8.0에서 6.0.0이므로 글을 읽기 전에 참고하길 바란다.

InAppWebview Migration

최소 필요 사양 변경

만약 앱이 실행이 되지 않거나 디버깅이 되지 않는다면 아래의 필요 사양을 꼭 확인해보자.
안드로이드 기준으로는 아마 compileSdk가 29~33 API 사이로 되어 있을 것이다.

다트 SDK : 2.17.0 이상, 4.0.0 미만
Flutter : 3.0.0 이상
Android : minSdkVersion 19 이상, compileSdk 34 이상, AGP 7.3.0 이상
iOS 9.0+ : Xcode Version 14.3 이상
MacOS 10.11+ : Xcode Version 14.3 이상

인앱웹뷰 옵션 클래스 변경 (InAppWebviewGroupOptions > InAppWebviewSettings )

기존의 InAppWebviewGroupOptions 클래스가 InAppWebviewSettings 클래스로 대체되었다.
기존의 InAppWebviewGroupOptions 클래스는 플랫폼별 설정 옵션을 따로 해주어야 하는 반면,
대체된 InAppWebviewSettings 클래스는 사용 가능한 모든 웹뷰 설정을 한꺼번에 지정할 수 있다.
즉, 이제 인앱웹뷰세팅에서 플랫폼 구분 없이 한꺼번에 지정이 가능하다.
아래는 내가 직접 사용하는 프로젝트에서의 코드를 마이그레이션한 코드이다.

기존

InAppWebViewGroupOptions options = InAppWebViewGroupOptions(
  // 플랫폼 상관없이 동작하는 옵션
  crossPlatform: InAppWebViewOptions(
    useShouldOverrideUrlLoading: true, // URL 로딩 제어
    mediaPlaybackRequiresUserGesture: false, // 미디어 자동 재생
    javaScriptEnabled: true, // 자바스크립트 실행 여부
    javaScriptCanOpenWindowsAutomatically: true, // 팝업 여부
  ),
  // 안드로이드 옵션
  android: AndroidInAppWebViewOptions(
    useHybridComposition: true, // 하이브리드 사용을 위한 안드로이드 웹뷰 최적화
    supportMultipleWindows: true, // 멀티 윈도우 허용
  ),
  // iOS 옵션
  ios: IOSInAppWebViewOptions(
    allowsInlineMediaPlayback: true, // 웹뷰 내 미디어 재생 허용
  ),
);

변경된 마이그레이션 코드

InAppWebViewSettings options = InAppWebViewSettings(
    useShouldOverrideUrlLoading: true, // URL 로딩 제어
    mediaPlaybackRequiresUserGesture: false, // 미디어 자동 재생
    javaScriptEnabled: true, // 자바스크립트 실행 여부
    javaScriptCanOpenWindowsAutomatically: true, // 팝업 여부
    useHybridComposition: true, // 하이브리드 사용을 위한 안드로이드 웹뷰 최적화
    supportMultipleWindows: true, // 멀티 윈도우 허용
    allowsInlineMediaPlayback: true, // 웹뷰 내 미디어 재생 허용
);

인앱웹뷰 위젯 생성 시 초기 설정 속성 변경 (InitialOptions > initialSettings)

인앱웹뷰 옵션 클래스가 인앱웹뷰 세팅 클래스로 변경되면서
위젯 생성 시 초기 설정 또한 변경 되었다.

기존

기존에서 초기 설정을 포함한 위젯 생성 코드는 initialOptions 로 옵션을 부여하였었다.

// options 변수는 InAppWebViewGroupOptions로 사전에 정의되어 있다고 가정
InAppWebView(
    initialOptions: options,
    // 생략
)

변경된 마이그레이션 코드

initialOptions가 아닌 initialSettings로 웹뷰 설정을 부여하도록 바뀌었다.

// options 변수는 InAppWebViewSettings로 사전에 정의되어 있다고 가정
InAppWebView(
    initialSettings: options,
    // 생략
)

웹 주소 정의 방식 변경 (Uri.parse > WebUri)

기존

기존의 방식은 인터넷 웹 주소(URI)를 Uri 추상 클래스의 파싱(parse) 메서드를 통해서 웹 주소를 웹뷰의 파라미터로 전달해주는 방법이였다.

Uri.parse('https://luvris2.tistory.com')

변경된 마이그레이션 코드

변경된 방식은 Uri.parse가 사용하는 URI의 원본 문자열을 파싱 없이 WebUri 클래스를 통해 그대로 사용할 수 있도록 변경되었다.

WebUri('https://luvris2.tistory.com')

또한, forceToStringRawValue 속성을 통해 URI 원본 문자열의 대소문자 손실을 방지할 수 있는 속성이 추가되었다.
InAppWebview 문서에 의하면 WebUri 클래스는 네이티브 플랫폼에서 전달되는 일부 문자열이 올바르게 전달되지 않아 대소문자 정보가 손실될 수 있다고 한다.
따라서 대소문자가 구분되어야하는 URI 주소라면 해당 옵션을 신경써주어야 한다.
forceToStringRawValue의 기본값은 false(대소문자 구분하지 않음)이다.
forceToStringRawValue의 속성 값을 true로 한다면 URI 원본 문자열의 대소문자를 그대로 유지한다.
WebUri 인스턴스 변수라면 .rawValue 메서드를 통해서 forceToStringRawValue와 같은 기능을 사용할 수 있다.

// forceToStringRawValue : false(기본값, 대소문자 구분하지 않음)
// forceToStringRawValue : true (대소문자 구분)
WebUri(url, forceToStringRawValue: false)

간단한 아래의 예제를 보자. uri.toString()을 통해 URI 원본 문자열을 확인해보는 샘플 코드이다.

// 대소문자가 있는 URI 원본 문자열
WebUri test = WebUri("https://LuVrIs2.tistory.com");

// toString()을 통해 URI 출력
print("toString()을 통해 URI 출력 : ${test.toString()}");

// rawValue 메서드를 통해 URI 출력 (대소문자 정보 유지)
print("rawValue 메서드를 통해 URI 출력 : ${test.rawValue}");

// forceToStringRawValue 속성을 true로 변경하여 URI 출력 (대소문자 정보 유지)
test.forceToStringRawValue = true;
print("forceToStringRawValue 속성을 true로 변경하여 URI 출력 : ${test.toString()}");

/* 차례대로 출력되는 값
toString()을 통해 URI 출력 : https://luvris2.tistory.com
rawValue 메서드를 통해 URI 출력 : https://LuVrIs2.tistory.com
forceToStringRawValue 속성을 true로 변경하여 URI 출력 : https://LuVrIs2.tistory.com
*/

사용되지 않는 클래스 및 속성

플랫폼 이름 접두사로 시작하는 모든 클래스/속성/메소드는 Deprecated 되고,
접두사가 없는 클래스/속성/메소드에서 사용하게 변경되었다.

AndroidInAppWebViewcontroller
AndroidServiceWorkerController
IOSCookieManager
AndroidOnPermissionRequest
iosOnNavigationRespon 등

// 예시
AndroidInAppWebViewController.setWebContentDebuggingEnabled(true); 
-> InAppWebViewController.setWebContentDebuggingEnabled(true);

AndroidOnPermissionRequest 관련 이벤트
-> PermissionReques 관련 이벤트

개요