erberkk/capturas-de-tela-da-loja

Capturas de tela da loja

Propósito

Capturas de tela que convertem, são fiéis ao aplicativo e se encaixam em todos os slots exigidos pelas lojas, produzidas por um script para que possam ser regeneradas em minutos quando a IU mudar.

Pré-requisitos

• Uma versão cuja IU está final para este lançamento.
• Um harness de captura no aplicativo (testes golden/integração Flutter, XCUITest, testes de captura de tela Espresso/Compose ou Fastlane snapshot) que possa renderizar telas com dados de demonstração determinísticos.
• Node.js 18+ e Chrome/Chromium para renderização (npm i em scripts/).
• Credenciais da API (accounts-and-tax) para upload.

Princípios

1. Capturas reais, não maquetes. Cada tela de telefone dentro de um quadro é uma captura do aplicativo enviado. IU redesenhada ou "melhorada" engana (diretriz 2.3) e fica desatualizada.
2. Os números devem corresponder ao aplicativo. Se um quadro mostra "1.850 passos" ou "12 min", o aplicativo deve produzir exatamente isso para os dados de demonstração. Gere os dados de demonstração no harness e faça uma asserção sobre eles no mesmo teste.
3. Se uma captura de tela mostra algo que o aplicativo não faz, corrija um deles. Construa o recurso ou altere o quadro. Nunca envie a lacuna.
4. Nenhuma outra plataforma nos quadros. Sem barras de status/navegação do Android no iOS, sem IU da Apple ou "App Store" no Play (2.3.10).
5. Mantenha a mesma ordem dos quadros em cada localidade e em cada dispositivo.

Matriz de dispositivos

Tabela completa com tamanhos lógicos e identificadores da API: references/device-matrix.md. Resumo (verifique em Especificações de captura de tela da Apple e Ativos de pré-visualização do Play):

Slot	Pixels (retrato)	Obrigatório?
iPhone grande Dynamic Island (6,9")	1320×2868 (também 1290×2796, 1260×2736)	Conjunto principal recomendado
iPhone médio Dynamic Island	1206×2622 ou 1179×2556	Pelo menos uma captura de tela obrigatória
iPhone Duo tela externa	1398×2034	Obrigatório a partir de abril de 2027 para aplicativos construídos com o SDK do iOS 27.1 ou posterior; adiciona o selo "otimizado para iPhone Duo"
iPhone Duo tela interna	2007×2853	Mesmo que externa
iPad 13"	2064×2752 (ou 2048×2732)	Obrigatório apenas se o aplicativo roda no iPad (não para aplicativos somente iPhone)
Telefone Play	ex. 1080×1920 ou 1080×2160 (lados 320–3840 px, lado longo ≤ 2× lado curto)	≥ 2 capturas de tela para publicar; ≥ 4 com ≥ 1080 px recomendado
Tablet Play 7" e 10"	1080–7680 px, 9:16 ou 16:9	Recomendado se o aplicativo suporta tablets
Gráfico de destaque do Play	1024×500	Obrigatório
Ícone do Play	512×512, PNG 32 bits	Obrigatório

Apple: até 10 por tamanho; PNG ou JPEG; sem canal alfa ou transparência. Play: até 8 por tipo de dispositivo; JPEG ou PNG 24 bits (sem alfa).

Ativos criativos da página de produto da App Store (App Store Connect mais recente, guia "Cabeçalho e resultados de pesquisa"):

• Cabeçalho: uma imagem larga no topo da página do produto, 3840×1646 ou 5244×2950. Opcional (o envio passa sem ela).
• Resultados de pesquisa: 5244×2950, 3840×2560 ou 1920×1280; se vazio, capturas de tela e visualizações são usadas.
• Envie pela página de versão ou pela Biblioteca de ativos (Enviar ativos criativos), depois escolha com Navegar ativos. Ativos enviados para a biblioteca permanecem lá para uso posterior.
• Nota de design: a loja sobrepõe o ícone, nome e botão Obter em parte do cabeçalho, então verifique o resultado na pré-visualização do console.
• Esses slots estão bloqueados enquanto a versão está Aguardando revisão. Adicione-os antes de enviar.

Procedimento

1. Planejar a história (APROVAÇÃO do storyboard)

Escreva um storyboard de 5–8 quadros: um título (≤ 6 palavras), uma linha de apoio, uma captura cada. Layout "panorâmico" opcional (o que o modelo agrupado faz): os quadros são fatias de uma tela larga, então as formas continuam pelas bordas dos quadros. Qualquer que seja o layout, qualquer oferta mostrada (início gratuito, teste) deve ser verdadeira.

2. Capturar telas reais

Capture cada tela no tamanho lógico × proporção de pixels do dispositivo alvo, para que o texto e o layout sejam exatamente o que esse dispositivo mostra. Exemplo Flutter (teste de widget/golden):

// iPhone 6,9": 440 x 956 pontos lógicos @3x = 1320 x 2868 px
tester.view.physicalSize = const Size(1320, 2868);
tester.view.devicePixelRatio = 3.0;
await tester.pumpWidget(App(demo: DemoData.storeShots(locale: 'en')));
await tester.pumpAndSettle();
expect(find.text('1.850 passos'), findsOneWidget);       // o número no título é real
await expectLater(find.byType(App), matchesGoldenFile('captures/en/iphone69/01_home.png'));

• Carregue fontes nos testes (caso contrário, a fonte de teste renderiza caixas).
• Relógio fixo, dados de demonstração fixos, sem rede.
• Oculte banners de depuração; defina a barra de status para um estado limpo (ou corte-a e não desenhe nenhuma).
• Capture cada localidade separadamente; nunca coloque IU em inglês dentro de um quadro localizado.

3. Compor quadros

Modelo: templates/panorama.html, renderizador: scripts/render.mjs.

cd scripts && npm i
node render.mjs ../templates/frames.example.json out/

O renderizador coloca todos os quadros em uma tela (largura = quadros × largura do quadro), carrega as capturas, espera pelas fontes e captura cada fatia de quadro no tamanho exato de pixel, para cada dispositivo na configuração. Ele também renderiza o gráfico de destaque 1024×500.

4. Verificar

node check-images.mjs out/

Falha em: dimensões incorretas para o dispositivo da pasta, canal alfa presente (tipo de cor PNG 4/6 ou bloco tRNS), mais de 10 (Apple) / 8 (Play) arquivos, lacunas na numeração. Em seguida, olhe cada imagem com zoom de 100%: texto cortado, IU de outra plataforma, strings de placeholder, números desatualizados.

5. Enviar via APIs (APROVAÇÃO antes de substituir conjuntos ativos)

• App Store Connect — scripts/upload-asc.mjs: encontre o appStoreVersion editável → seus appStoreVersionLocalizations → appScreenshotSets por screenshotDisplayType → exclua capturas de tela antigas → reserve (POST /v1/appScreenshots com fileName, fileSize) → envie as partes de uploadOperations → confirme (PATCH com uploaded: true e o MD5 sourceFileChecksum) → defina a ordem no relacionamento appScreenshots do conjunto. Docs: Enviando ativos para App Store Connect.
• Google Play — scripts/upload-play.mjs: edits.insert → edits.images.deleteall por idioma e tipo de imagem → edits.images.upload em ordem (phoneScreenshots, sevenInchScreenshots, tenInchScreenshots, featureGraphic) → edits.commit. Docs: edits.images.upload.

Ambos os scripts padrão para dry run; defina DRY_RUN=0 para escrever.

6. Ler de volta

Liste os ativos enviados por localidade e dispositivo (ambas as APIs) e compare a contagem e a ordem com a pasta local. A Apple processa os envios de forma assíncrona; aguarde até que cada ativo relate estado de entrega COMPLETE.

Pontos de decisão que precisam de aprovação humana

Storyboard e títulos, direção visual final, substituição de um conjunto de capturas de tela ativo, confirmação da edição do Play.

Verificação

• check-images.mjs passa; cada slot obrigatório da Apple tem pelo menos uma imagem; Play tem capturas de telefone e o gráfico de destaque.
• A ordem de leitura de volta corresponde; nenhum estado de ativo falhou.
• Cada número e recurso nos quadros foi verificado em relação à versão.

Armadilhas comuns

• Enviar apenas 6,9" e perder o slot médio obrigatório do Dynamic Island.
• PNGs exportados com canal alfa (comum em ferramentas de design e navegadores headless com fundos transparentes — sempre defina um fundo opaco do corpo).
• Usar a imagem 1320×2868 de 6,9" no Play: sua proporção excede o limite de 2:1 do Play; renderize um tamanho específico para o Play.
• Capturas de tela do iPad para um aplicativo somente iPhone (não necessário) — ou perdê-las quando o aplicativo roda no iPad.
• Um quadro mostrando uma linha de configurações ou resultado que o aplicativo não tem.
• Título traduzido, mas a captura ainda em inglês.