Especificação de Contratos: Web App Manifest & Ícones PWA

Esta especificação define os contratos de interface das rotas de Progressive Web App (PWA) no servidor Nitro e na renderização isomórfica Nuxt 4.

1. Rota Canônica do Manifest

  • Caminho: /manifest.webmanifest

  • Método: GET, HEAD

  • Content-Type: application/manifest+json; charset=utf-8

  • Roteamento: Mapeado via server/routes/manifest.webmanifest.ts.

1.1 Cabeçalhos HTTP

Cabeçalho Valor / Diretiva

Content-Type

application/manifest+json; charset=utf-8

Cache-Control

public, s-maxage=3600, stale-while-revalidate=86400

Vercel-CDN-Cache-Control

s-maxage=3600, stale-while-revalidate=86400

Vary

Host, Accept-Encoding

1.2 Parâmetros de Consulta (Query String)

Parâmetro Tipo Obrigatório Regra de Validação

domain

string

Não

Aceito estritamente em ambiente de desenvolvimento (localhost) ou suítes de teste para emular a resolução de host do parceiro. Em produção, este parâmetro é ignorado e o cabeçalho Host é soberano.

1.3 Estrutura do Payload JSON

Campo Tipo Descrição

id

string

Identificador único de instalação. Sempre "/" em produção (resolvido relativamente à origem da requisição), ou "/?" + domain em testes locais.

name

string

Nome empresarial da marca parceira (ex.: "Rocketz").

short_name

string

Nome resumido para launchers e gavetas de aplicativos (máx. 12 caracteres).

description

string

Descrição institucional da plataforma corporativa.

start_url

string

URL de entrada do aplicativo ("/" ou "/?domain=…​" em testes locais).

scope

string

Escopo de navegação ("/").

display

string

Modo de exibição ("standalone").

display_override

string[]

Preferência por janelas integradas (["window-controls-overlay"]).

theme_color

string

Cor estática da barra de título do aplicativo ("#131314").

background_color

string

Cor estática da splash screen nativa ("#131314").

icons

object[]

Coleção de variantes de ícones (192x192 e 512x512 para propósitos any e maskable).

2. Endpoint Gerador de Ícones

  • Caminho: /api/pwa-icon

  • Métodos: GET, HEAD

  • Content-Type: image/png

  • Roteamento: Mapeado via server/api/pwa-icon.ts.

2.1 Parâmetros de Consulta (Query String)

Parâmetro Tipo Obrigatório Regra de Validação

size

integer

Sim

Aceita estritamente 180, 192 ou 512. Valores divergentes resultam em HTTP 400 Bad Request.

purpose

string

Não

Aceita 'any' ou 'maskable'. Padrão: 'any'.

v

string

Não

Hash ou timestamp de versão de branding utilizado para cache busting determinístico.

domain

string

Não

Domínio do parceiro para resolução de logo/monograma em testes locais (ignorado em produção).

2.2 Cabeçalhos HTTP de Resposta

Cabeçalho Valor / Diretiva

Content-Type

image/png

Content-Length

<tamanho_em_bytes>

Cache-Control

public, s-maxage=86400, stale-while-revalidate=604800

Vercel-CDN-Cache-Control

s-maxage=86400, stale-while-revalidate=604800

Vary

Host, Accept-Encoding

3. Metatags SSR de Integração (Apple Safari & Web Clips)

Injetadas sincronamente durante o Server-Side Rendering no app/app.vue com resolução reativa de domínio:

<!-- Manifesto Canônico W3C (sensível a ?domain= em ambiente local) -->
<link rel="manifest" href="/manifest.webmanifest?domain=app.rocketz.me">

<!-- Ícone Web Clip para iOS / iPadOS -->
<link rel="apple-touch-icon" sizes="180x180" href="/api/pwa-icon?size=180&purpose=any&domain=app.rocketz.me">

<!-- Título e Modo Standalone no iOS -->
<meta name="apple-mobile-web-app-title" content="{partnerName}">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">