Guia de Integração: Single Page Applications (SPA) e URLs Mascaradas

Este guia explica como configurar aplicações do tipo Single Page Application (SPA) (como Flutter Web, React, Vue, Angular, Bubble) para funcionarem corretamente com o recurso de Mascaramento de URL (Route Aliasing) da Tenanci.

O Desafio: Roteamento Cliente vs. Servidor

Quando você utiliza a Tenanci para mascarar uma URL, acontece o seguinte cenário:

Usuário acessa: https://seu-dominio.com/ (Raiz).

Tenanci Proxy: Identifica que esta rota deve mostrar o conteúdo de https://seu-app.com/u/usuario-xyz.

Tenanci Proxy: Busca o HTML do perfil e entrega ao navegador.

Navegador: Carrega o site. A URL na barra de endereços permanece https://seu-dominio.com/.

O Problema:
Aplicações modernas (SPAs) possuem um Roteador Interno (Client-Side Router) que roda no navegador. Assim que o aplicativo inicia, este roteador olha para a URL do navegador para decidir qual tela mostrar.
Como ele vê a URL / (raiz), ele ignora o conteúdo da página de perfil que já foi carregado e força a renderização da Página Inicial (Home).

A Solução Tenanci: `window.TENANCI_INITIAL_ROUTE`

Para resolver isso, o Proxy da Tenanci injeta automaticamente uma variável global no HTML da página sempre que ocorre uma reescrita de rota.

Seu aplicativo deve verificar se essa variável existe na inicialização. Se existir, ele deve ignorar a URL do navegador e navegar internamente para a rota indicada.

Como Implementar

Abaixo, exemplos de como implementar essa verificação nas principais tecnologias.

1. Flutter Web

No Flutter, você deve ler a propriedade JavaScript na inicialização e passá-la como rota inicial ou navegar manualmente.

Exemplo (main.dart):

2. React (React Router)

No React, você pode definir o basename ou usar um useEffect para navegar assim que o app montar.

Opção A: Navegação Imperativa (Recomendada)

3. Bubble.io e Ferramentas No-Code

A maioria das ferramentas No-Code permite adicionar scripts personalizados ou fluxos "On Page Load".

Passo a Passo:

Vá nas configurações da página ou no fluxo de "Page is loaded".

Adicione uma ação do tipo "Run JavaScript".

Insira o seguinte código:

Nota: Em plataformas fechadas como Bubble, se o roteamento for muito restrito, pode ser necessário usar parâmetros de URL (query params) em vez de caminhos.

4. JavaScript Puro (Vanilla)

Se você não usa frameworks, pode manipular o histórico do navegador logo no início do <head> ou antes do fechamento do <body>.

Resumo

Configure o Alias na Tenanci (ex: / -> /u/perfil).

O Proxy Tenanci entrega o HTML e injeta window.TENANCI_INITIAL_ROUTE = "/u/perfil".

Seu App lê essa variável ao iniciar e navega para a tela correta.

SPA

Guia de Integração: Single Page Applications (SPA) e URLs Mascaradas#

O Desafio: Roteamento Cliente vs. Servidor#

A Solução Tenanci: window.TENANCI_INITIAL_ROUTE#

Como Implementar#

1. Flutter Web#

2. React (React Router)#

3. Bubble.io e Ferramentas No-Code#

4. JavaScript Puro (Vanilla)#

Resumo#