> 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-pt/criar-para-mobile/desenvolver/safe-area.md).

# Área Segura no Mobile

Onde a UI da scene pode ficar com segurança no mobile — fora das margens de hardware do dispositivo e dos próprios controles do client.

Num telemóvel, duas coisas não relacionadas reduzem o espaço do ecrã que a sua UI pode usar em segurança:

* **As margens físicas do dispositivo** — o entalhe ou recorte da câmara, a barra de estado, o indicador do ecrã principal e os cantos arredondados. A UI desenhada por baixo destes elementos fica parcialmente oculta ou é difícil de tocar.
* **Os próprios controlos do cliente Decentraland** — joystick, chat, perfil, controlos da câmara e botões de ação. A UI da Scene colocada por baixo destes elementos entra em conflito visual e compete pelos mesmos toques.

Não precisa de medir nenhum deles. O cliente comunica ambas as áreas em runtime e o SDK posiciona a sua UI dentro da área que escolher, com a opção do renderer [`screenInset`](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-inset-area) :

| O que pretende                                                         | O que indicar                                   |
| ---------------------------------------------------------------------- | ----------------------------------------------- |
| Fora das margens físicas do dispositivo                                | nada — `screenInset: 'device'` é a predefinição |
| Fora das margens físicas do dispositivo **e** dos controlos do cliente | `screenInset: 'interactable'`                   |
| O ecrã inteiro; as margens ficam a seu cargo                           | `screenInset: 'none'`                           |

```ts
// Recomendado para UI da Scene que não deve entrar em conflito com os controlos móveis
ReactEcsRenderer.setUiRenderer(uiComponent, { screenInset: 'interactable' })
```

{% hint style="warning" %}
**Suporte do cliente**: `'interactable'` requer o cliente móvel `1.12.1` ou uma versão mais recente. Nos clientes mais antigos, a área é comunicada como zero e a UI passa a cobrir o ecrã inteiro. Essa mesma versão normaliza a área `'device'` entre Android e iOS.

**Não é uma opção sem efeito no computador** — o cliente para computador reserva cerca de 25% do lado esquerdo do ecrã para a sua própria UI, por isso `'interactable'` também altera o seu layout no computador. Use uma condição com [`isMobile()`](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/detect-platform.md) se só quiser aplicar o inset nos telemóveis.
{% endhint %}

Consulte [Área de inset do ecrã](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-inset-area) para ver a referência completa: as três áreas lado a lado num dispositivo real, o comportamento por renderer e a relação com o [ecrã virtual](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#default-virtual-size).

## Onde ficam os controlos do cliente

`'interactable'` dá-lhe a área que **cada designação do Explorer define para a UI da Scene** — isso não significa deliberadamente que todos os controlos do cliente fiquem fora dela. No cliente móvel, é a área segura do dispositivo menos a coluna do lado esquerdo (chat, perfil, joystick, emotes); os botões de ação no canto inferior direito são desenhados sobre a área **por conceção**.

<figure><img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-e68f1a62cc357cbe24e75f24c58db7d37a4f4ee2%2Fscreeninset-interactable.webp?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> no cliente móvel <code>1.12.1</code>. O retângulo magenta representa a UI da Scene; o contorno verde indica a área interativa. A coluna do lado esquerdo é excluída; os botões de ação no canto inferior direito ficam sobre a área.</p></figcaption></figure>

Por isso, mesmo com `'interactable'`, considere estas áreas congestionadas:

* **Inferior direito** — os botões de ação e o botão de interação são desenhados por cima. Tudo o que colocar aqui continua acessível, mas disputa espaço com os toques.
* **Superior direito** — os controlos do perfil e da câmara ficam mesmo fora da área, por isso, uma UI encostada a esse canto parece fazer parte do HUD do cliente.

O que a área abrange depende de cada Explorer e pode mudar entre versões. Consulte-a em runtime, nunca a defina diretamente no código e verifique-a nas plataformas que pretende suportar.

## Onde colocar a UI da cena

* **Centro do ecrã** — diálogos com ações e tudo o que o jogador precisa de ler e a que precisa de responder.
* **Centro superior** — mensagens sem ações, estado e notificações.
* **Centro inferior, acima do botão de interação** — sugestões sensíveis ao contexto.
* **Não use o canto inferior direito** — mesmo dentro da área interativa, esse espaço pertence aos botões de ação.

## Em alternativa, envolva parte da UI

Se optou por não usar `screenInset: 'none'` e quiser proteger apenas parte da UI, envolva-a no componente `ScreenInsetArea` ou no componente `InteractableArea` . Cada um lê a área correspondente e aplica-a aos respetivos elementos descendentes. Importe-os de `@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>
      {/* Um elemento descendente com 100% × 100% preenche exatamente a área segura */}
      <UiEntity
        uiTransform={{ width: '100%', height: '100%' }}
        uiBackground={{ color: Color4.create(0, 0, 0, 0.5) }}
      />
    </ScreenInsetArea>
  ), { screenInset: 'none' })
}
```

Ambos os componentes posicionam-se de forma absoluta, usando os valores comunicados pelo cliente. Por isso, os campos `positionType` e `position` de `uiTransform` são reservados — qualquer valor que definir para eles será ignorado. Todas as outras `uiTransform` propriedades (`padding`, `flexDirection`, `alignItems`, …) e componentes de UI (`uiBackground`, `onMouseDown`, …) funcionam como habitualmente. Reagem automaticamente quando a área muda, por exemplo, ao rodar o ecrã ou quando as barras do sistema aparecem ou desaparecem, e compensam o [fator de escala da UI](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-virtual-scale), para que as margens fiquem corretamente posicionadas, seja qual for o tamanho do ecrã virtual.

{% hint style="warning" %}
**📔 Não aplique o inset duas vezes:** o `screenInset: 'none'` no trecho acima é importante. Envolver a sua UI num componente enquanto o renderer também aplica o inset correspondente desloca a sua UI para dentro pelo dobro da margem. Escolha uma opção ou outra.
{% endhint %}

{% hint style="info" %}
**📱 Apenas em dispositivos móveis:** os insets do dispositivo só têm valores reais no **cliente para dispositivos móveis**. No **cliente para computador** são `(0, 0, 0, 0)`, por isso `screenInset: 'device'` e o componente `ScreenInsetArea` não têm qualquer efeito nesse caso, e a sua UI é renderizada exatamente como seria sem eles. Ao contrário dos insets do dispositivo, a área interativa *é* diferente de zero no computador.
{% endhint %}

## Porque é importante

A UI da Scene que se sobrepõe aos controlos do cliente pode:

* Ficar parcialmente oculta atrás do joystick, do botão de interação ou dos controlos da câmara.
* Entrar em conflito com esses controlos ao tocar no ecrã — os jogadores podem ativar um ou outro por acidente.
* Fazer com que a sua Scene pareça avariada em dispositivos móveis, prejudicando a sua inclusão em destaques e a retenção de jogadores.

Verifique sempre num dispositivo real, usando o [código QR de pré-visualização](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/preview-on-mobile.md).

## Relacionados

* [Área de inset do ecrã](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-inset-area) — a referência completa de `screenInset` .
* [Práticas recomendadas de UI para dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/ui-best-practices.md)
* [Detetar a plataforma no código](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/detect-platform.md) — use `isMobile()` para alternar entre layouts.
* [UI no ecrã](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md)
* [Guia de UX e UI](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/conceber-a-experiencia/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-pt/criar-para-mobile/desenvolver/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.
