> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/integration/props.md).

# WebView의 속성 제어하기

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

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

{% hint style="info" %}
**지원 환경**

* 실행 환경: WebView, 토스 앱
* SDK 버전: WebView 3.x 이상
  {% endhint %}

## WebView 속성 설정 방법

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

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

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

{% hint style="warning" %}
SDK 2.x의 `granite.config.ts`와 `webViewProps`는 SDK 3.x에서 각각 `apps-in-toss.config.ts`, `webView`로 이름이 바뀌었어요. 하위 옵션은 동일해요.
{% endhint %}

## 사용 가능한 WebView 속성

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

```ts
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 공식 문서](https://developer.android.com/reference/android/view/View#OVER_SCROLL_NEVER)

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

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

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

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

참고: [react-native-webview mediaPlaybackRequiresUserAction](https://github.com/react-native-webview/react-native-webview/blob/v13.6.2/docs/Reference.md#mediaplaybackrequiresuseraction)

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

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

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

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

참고: [react-native-webview allowsBackForwardNavigationGestures](https://github.com/react-native-webview/react-native-webview/blob/v13.6.2/docs/Reference.md#allowsBackForwardNavigationGestures)

## 설정 예시

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

```ts
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 속성은 런타임이 아닌 설정 단계에서 적용돼요.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/integration/props.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.