> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/build-for-mobile/develop/safe-area.md).

# 모바일 안전 영역

씬 UI가 모바일에서 안전하게 배치될 수 있는 영역 — 기기의 하드웨어 여백과 클라이언트 자체 컨트롤을 피한 곳.

휴대폰에서는 서로 무관한 두 가지가 UI가 안전하게 사용할 수 있는 화면 공간을 잠식합니다:

* **기기의 하드웨어 여백** — 노치나 카메라 컷아웃, 상태 표시줄, 홈 인디케이터, 둥근 모서리입니다. 그 아래에 그려진 UI는 일부가 가려지거나 탭하기 어렵습니다.
* **Decentraland 클라이언트 자체의 컨트롤** — 조이스틱, 채팅, 프로필, 카메라 컨트롤, 액션 버튼입니다. 그 아래에 놓인 씬 UI는 시각적으로 충돌하고 같은 탭 입력을 두고 경쟁합니다.

둘 중 어느 것도 직접 측정할 필요는 없습니다. 클라이언트는 런타임에 두 영역을 모두 알려 주고, SDK는 당신이 선택한 영역 안에 UI를 배치하며, 이를 위해 [`screenInset`](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md#screen-inset-area) 렌더러 옵션:

| 원하는 것                        | 전달할 값                                       |
| ---------------------------- | ------------------------------------------- |
| 하드웨어 여백을 피하기                 | 아무 것도 없음 — `screenInset: 'device'` 가 기본값입니다 |
| 하드웨어 여백을 피하기 **과** 클라이언트 컨트롤 | `screenInset: 'interactable'`               |
| 전체 화면, 여백은 직접 처리해야 함         | `screenInset: 'none'`                       |

```ts
// 모바일 컨트롤과 충돌하면 안 되는 씬 UI에 권장
ReactEcsRenderer.setUiRenderer(uiComponent, { screenInset: 'interactable' })
```

{% hint style="warning" %}
**클라이언트 지원**: `'interactable'` 모바일 클라이언트가 필요합니다 `1.12.1` 이상 버전이어야 합니다. 더 이전 클라이언트에서는 해당 영역이 0으로 보고되고 UI는 전체 화면을 덮는 방식으로 대체됩니다. 같은 릴리스에서 `'device'` Android와 iOS 간의 영역을 표준화합니다.

**데스크톱에서는 아무 일도 하지 않는 것이 아닙니다** — 데스크톱 클라이언트는 화면의 왼쪽 약 25%를 자체 UI용으로 확보하므로 `'interactable'` 데스크톱 레이아웃도 바뀝니다. 다음처럼 분기하세요: [`isMobile()`](/creator/content-creator-ko/build-for-mobile/develop/detect-platform.md) 휴대폰에서만 인셋을 적용하고 싶다면.
{% endhint %}

다음 [화면 인셋 영역](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md#screen-inset-area) 전체 참고 자료: 실제 기기에서의 세 영역을 나란히 본 모습, 렌더러별 동작, 그리고 이것들이 [가상 화면](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md#default-virtual-size).

## 클라이언트 컨트롤이 있는 위치

`'interactable'` 해당 영역을 제공합니다 **각 익스플로러가 씬 UI용으로 지정한** — 이는 모든 클라이언트 컨트롤이 그 밖에 있다는 뜻을 보장하려는 것이 아닙니다. 모바일 클라이언트에서는 기기 안전 영역에서 왼쪽 열(채팅, 프로필, 조이스틱, 이모트)을 뺀 영역이며, 오른쪽 아래의 액션 버튼은 그 영역 위에 그려집니다 **의도된 설계입니다**.

<figure><img src="https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-c0c75a80bed756d6b2b1483a7cca0cadef26c77e%2Fscreeninset-interactable.png?alt=media" alt="Scene UI inset to the area the mobile client reports as free of its own HUD"><figcaption><p><code>screenInset: 'interactable'</code> 모바일 클라이언트에서 <code>1.12.1</code>. 자주색 사각형은 씬 UI이고, 초록색 윤곽선은 상호작용 가능한 영역입니다. 왼쪽 열은 제외되며, 오른쪽 아래의 액션 버튼은 그 영역 위에 놓입니다.</p></figcaption></figure>

따라서 `'interactable'`, 다음은 혼잡한 영역으로 취급하세요:

* **오른쪽 아래** — 액션 버튼과 상호작용 버튼이 위에 그려집니다. 여기에 놓은 것은 여전히 접근 가능하지만, 탭 입력을 두고 경쟁합니다.
* **오른쪽 위** — 프로필과 카메라 컨트롤이 영역 바로 바깥에 있으므로, 그 모서리에 붙은 UI는 클라이언트 HUD의 일부처럼 보입니다.

해당 영역이 어디까지 포함하는지는 각 explorer의 판단이며 버전마다 달라질 수 있습니다. 런타임에 읽어 오고, 하드코딩하지 말며, 대상 플랫폼에서 확인하세요.

## 씬 UI를 둘 위치

* **화면 중앙** — 사용자가 읽고 응답해야 하는 대화상자 등, 조작이 필요한 모든 UI입니다.
* **상단 중앙** — 조작이 필요 없는 메시지, 상태, 알림입니다.
* **하단 중앙, 상호작용 버튼 위** — 상황에 맞는 힌트입니다.
* **오른쪽 아래 모서리는 아님** — 상호작용 가능 영역 안쪽이라도, 그곳은 액션 버튼의 자리입니다.

## 대신 UI의 일부를 감싸세요

다음으로 제외했다면 `screenInset: 'none'` 그리고 UI의 일부만 보호하고 싶다면, 그것을 다음으로 감싸세요 `ScreenInsetArea` 또는 `InteractableArea` 컴포넌트입니다. 각각은 대응하는 영역을 읽어 자식에게 적용합니다. 다음에서 import하세요 `@dcl/sdk/react-ecs`:

```tsx
import ReactEcs, { ReactEcsRenderer, UiEntity, ScreenInsetArea } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export function setupUi() {
  ReactEcsRenderer.setUiRenderer(() => (
    <ScreenInsetArea>
      {/* 100% × 100% 크기의 자식은 안전 인셋 영역을 정확히 채웁니다 */}
      <UiEntity
        uiTransform={{ width: '100%', height: '100%' }}
        uiBackground={{ color: Color4.create(0, 0, 0, 0.5) }}
      />
    </ScreenInsetArea>
  ), { screenInset: 'none' })
}
```

두 컴포넌트는 클라이언트가 알려 주는 값을 사용해 절대 위치로 배치되므로 `positionType` 과 `위치` 그들의 필드 중 `uiTransform` 는 예약되어 있으며 — 여기에 설정한 값은 모두 무시됩니다. 그 밖의 모든 `uiTransform` 속성(`padding`, `flexDirection`, `alignItems`, …) 및 UI 컴포넌트(`uiBackground`, `onMouseDown`, …)는 평소처럼 동작합니다. 예를 들어 회전하거나 시스템 바가 나타나거나 사라질 때 영역이 바뀌면 자동으로 반응하고, 다음을 보정합니다 [UI 스케일 팩터](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md#screen-virtual-scale), 따라서 가상 화면 크기가 무엇이든 여백이 올바르게 맞춰집니다.

{% hint style="warning" %}
**📔 인셋을 두 번 적용하지 마세요:** 다음의 `screenInset: 'none'` 위 코드 조각의 부분이 중요합니다. 렌더러도 같은 인셋을 적용하는데 UI를 컴포넌트로 다시 감싸면, UI가 여백의 두 배만큼 안쪽으로 밀립니다. 둘 중 하나만 선택하세요.
{% endhint %}

{% hint style="info" %}
**📱 모바일 전용:** 기기 인셋은 다음에서만 실제 값을 가집니다 **모바일 클라이언트**. 다음에서는 **데스크톱 클라이언트** 그 값은 `(0, 0, 0, 0)`0이며, `screenInset: 'device'` 와 `ScreenInsetArea` 컴포넌트는 그곳에서 아무 효과가 없으며 UI는 그것들이 없는 것과 정확히 동일하게 렌더링됩니다. 반면 상호작용 가능 영역은 기기 인셋과 달리, *가* 데스크톱에서도 0이 아닙니다.
{% endhint %}

## 왜 중요한가

클라이언트 컨트롤과 겹치는 씬 UI는 다음과 같은 문제가 생깁니다:

* 조이스틱, 상호작용 버튼, 또는 카메라 컨트롤 뒤에 일부가 가려집니다.
* 그 컨트롤들과 탭 입력을 두고 경쟁하게 되어 — 플레이어가 하나 또는 다른 하나를 실수로 누르게 됩니다.
* 모바일에서 씬이 망가진 것처럼 느껴지게 하여, 추천 노출과 유지율에 악영향을 줍니다.

반드시 실제 기기에서 다음을 사용해 확인하세요 [미리보기 QR 코드](/creator/content-creator-ko/build-for-mobile/develop/preview-on-mobile.md).

## 관련 항목

* [화면 인셋 영역](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md#screen-inset-area) — 전체 `screenInset` 참고 자료.
* [모바일용 UI 모범 사례](/creator/content-creator-ko/build-for-mobile/develop/ui-best-practices.md)
* [코드에서 플랫폼을 감지하세요](/creator/content-creator-ko/build-for-mobile/develop/detect-platform.md) — 다음을 사용하세요 `isMobile()` 레이아웃을 전환하려면.
* [화면 UI](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md)
* [UX 및 UI 가이드](/creator/content-creator-ko/sdk7/designing-the-experience/ux-ui-guide.md)


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-ko/build-for-mobile/develop/safe-area.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.