WebView의 속성 제어하기

이 문서에서는 WebView의 동작 방식을 제어하기 위해 apps-in-toss.config.ts에서 설정할 수 있는 webView 옵션을 설명해요.

스크롤 동작, 미디어 재생 방식, 제스처 사용 여부처럼 사용자 경험에 직접적인 영향을 주는 WebView 속성을 서비스 성격에 맞게 조정할 수 있어요.

지원 환경

• 실행 환경: WebView, 토스 앱
• SDK 버전: WebView 3.x 이상

WebView 속성 설정 방법

WebView 속성은 apps-in-toss.config.ts 파일의 webView 항목에서 설정해요.

import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  webView: {
    // WebView 동작 관련 옵션
  },
});

SDK 2.x의 granite.config.ts와 webViewProps는 SDK 3.x에서 각각 apps-in-toss.config.ts, webView로 이름이 바뀌었어요. 하위 옵션은 동일해요.

사용 가능한 WebView 속성

webView에는 아래 속성을 설정할 수 있어요.

webView?: {
  allowsInlineMediaPlayback?: boolean;
  bounces?: boolean;
  pullToRefreshEnabled?: boolean;
  overScrollMode?: 'always' | 'content' | 'never';
  mediaPlaybackRequiresUserAction?: boolean;
  allowsBackForwardNavigationGestures?: boolean;
};

인라인 미디어 재생 허용 (allowsInlineMediaPlayback)

HTML5 비디오를 전체 화면이 아닌 WebView 내부에서 인라인으로 재생할지 설정해요.

iOS 전용 속성이며, true로 설정한 뒤 <video> 태그에 webkit-playsinline 속성이 있어야 인라인 재생이 가능해요.

항목	내용
타입	boolean
기본값	false
플랫폼	iOS

스크롤 바운스 효과 사용 (bounces)

스크롤 영역의 끝에 도달했을 때 튕기는 바운스 효과를 사용할지 설정해요.

iOS 전용 속성이며 기본값은 true예요.

항목	내용
타입	boolean
기본값	true
플랫폼	iOS

당겨서 새로고침 활성화 (pullToRefreshEnabled)

아래로 당겨서 새로고침하는 Pull-to-Refresh 동작을 활성화할지 설정해요.

iOS 전용 옵션이며 기본값은 true예요. 이 값을 true로 설정하면 bounces 옵션도 자동으로 true로 설정돼요.

항목	내용
타입	boolean
기본값	true
플랫폼	iOS

오버스크롤 동작 방식 설정 (overScrollMode)

스크롤 콘텐츠의 끝에 도달했을 때 Android에서 오버스크롤 효과를 어떻게 처리할지 설정해요.

항목	내용
타입	'always' | 'content' | 'never'
기본값	'always'
플랫폼	Android

각 값의 의미는 아래와 같아요.

값	설명
'always'	콘텐츠 크기와 관계없이 오버스크롤 효과를 허용해요.
'content'	콘텐츠가 WebView보다 클 때만 오버스크롤 효과를 허용해요.
'never'	오버스크롤 효과를 사용하지 않아요.

참고: Android 공식 문서

미디어 자동 재생 제한 (mediaPlaybackRequiresUserAction)

오디오 또는 비디오가 자동으로 재생되지 않도록 제한할지 설정해요.

이 값을 true로 설정하면 사용자가 직접 탭해야 미디어가 재생돼요. Android에서는 버전 17 이상에서만 이 옵션이 적용돼요.

항목	내용
타입	boolean
기본값	true
플랫폼	iOS, Android

참고: react-native-webview mediaPlaybackRequiresUserAction

스와이프 뒤로가기/앞으로가기 허용 (allowsBackForwardNavigationGestures)

좌우 스와이프 제스처로 뒤로 가기 또는 앞으로 가기 탐색을 허용할지 설정해요.

이 값을 false로 설정하면 사용자가 스와이프 제스처로 페이지 이동을 할 수 없어요.

항목	내용
타입	boolean
기본값	true
플랫폼	iOS

참고: react-native-webview allowsBackForwardNavigationGestures

설정 예시

아래 예시는 WebView의 스크롤 동작과 미디어 재생 방식을 함께 설정한 예시예요.

import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  webView: {
    bounces: true,
    pullToRefreshEnabled: true,
    allowsInlineMediaPlayback: false,
    overScrollMode: 'never',
  },
});

참고사항

• 일부 WebView 속성은 iOS 또는 Android 전용이에요. 플랫폼별 동작 차이를 꼭 확인해 주세요.
• 사용자 경험에 영향을 크게 주는 옵션은 서비스 성격에 맞춰 신중히 설정하는 것을 권장해요.
• WebView 속성은 런타임이 아닌 설정 단계에서 적용돼요.