erberkk/store-screenshots

Was macht store-screenshots?

Zweck

Screenshots, die konvertieren, der App treu sind und jeden Slot passen, den die Stores verlangen. Sie werden von einem Skript erstellt, sodass sie bei UI-Änderungen in Minuten neu generiert werden können.

Voraussetzungen

• Ein Build, dessen UI für diese Version final ist.
• Ein Aufnahme-Harness in der App (Flutter Golden/Integrationstests, XCUITest, Espresso/Compose-Screenshot-Tests oder Fastlane Snapshot), der Bildschirme mit deterministischen Demodaten rendern kann.
• Node.js 18+ und Chrome/Chromium für das Rendering (npm i in scripts/).
• API-Anmeldedaten (accounts-and-tax) für den Upload.

Prinzipien

1. Echte Aufnahmen, keine Mockups. Jeder Telefonbildschirm innerhalb eines Rahmens ist eine Aufnahme der ausgelieferten App. Neu gezeichnete oder „verbesserte“ UI führt in die Irre (Richtlinie 2.3) und wird schnell veraltet.
2. Zahlen müssen mit der App übereinstimmen. Wenn ein Rahmen „1.850 Schritte“ oder „12 Min“ zeigt, muss die App genau das für die Demodaten produzieren. Generiere die Demodaten im Harness und überprüfe sie im selben Test.
3. Wenn ein Screenshot etwas zeigt, was die App nicht tut, korrigiere eines von beiden. Entweder baue die Funktion oder ändere den Rahmen. Liefere nie die Lücke aus.
4. Keine andere Plattform in den Rahmen. Keine Android-Status-/Navigationsleisten auf iOS, keine Apple-UI oder „App Store“ auf Play (2.3.10).
5. Behalte dieselbe Rahmenreihenfolge in jedem Gebietsschema und auf jedem Gerät.

Gerätematrix

Vollständige Tabelle mit logischen Größen und API-Kennungen: references/device-matrix.md. Zusammenfassung (überprüfe unter Apple-Screenshot-Spezifikationen und Play-Vorschau-Assets):

Slot	Pixel (Hochformat)	Erforderlich?
iPhone großes Dynamic Island (6,9")	1320×2868 (auch 1290×2796, 1260×2736)	Empfohlenes Hauptset
iPhone mittleres Dynamic Island	1206×2622 oder 1179×2556	Mindestens ein Screenshot erforderlich
iPhone Duo äußeres Display	1398×2034	Erforderlich ab April 2027 für Apps, die mit dem iOS 27.1 SDK oder neuer erstellt wurden; fügt das Abzeichen „Optimiert für iPhone Duo“ hinzu
iPhone Duo inneres Display	2007×2853	Wie äußeres Display
iPad 13"	2064×2752 (oder 2048×2732)	Nur erforderlich, wenn die App auf iPad läuft (nicht für iPhone-only-Apps)
Play-Telefon	z. B. 1080×1920 oder 1080×2160 (Seiten 320–3840 px, lange Seite ≤ 2× kurze Seite)	≥ 2 Screenshots für Veröffentlichung; ≥ 4 bei ≥ 1080 px empfohlen
Play 7" und 10"-Tablet	1080–7680 px, 9:16 oder 16:9	Empfohlen, wenn die App Tablets unterstützt
Play-Feature-Graphic	1024×500	Erforderlich
Play-Symbol	512×512, 32-Bit-PNG	Erforderlich

Apple: bis zu 10 pro Größe; PNG oder JPEG; kein Alphakanal oder Transparenz. Play: bis zu 8 pro Gerätetyp; JPEG oder 24-Bit-PNG (kein Alpha).

App Store-Produktseiten-Kreativ-Assets (neueres App Store Connect, Registerkarte «Header und Suchergebnisse»):

• Header: ein breites Bild oben auf der Produktseite, 3840×1646 oder 5244×2950. Optional (Einreichung ist auch ohne möglich).
• Suchergebnisse: 5244×2950, 3840×2560 oder 1920×1280; wenn leer, werden Screenshots und Vorschauen verwendet.
• Hochladen über die Versionsseite oder die Asset-Bibliothek (Kreativ-Assets hochladen), dann mit «Assets durchsuchen» auswählen. In der Bibliothek hochgeladene Assets bleiben für spätere Verwendung erhalten.
• Designhinweis: Der Store überlagert das Symbol, den Namen und den „Get“-Button auf einem Teil des Headers. Überprüfe das Ergebnis daher in der Konsolenvorschau.
• Diese Slots sind gesperrt, während die Version auf Überprüfung wartet. Füge sie vor dem Einreichen hinzu.

Vorgehensweise

1. Die Geschichte planen (GENEHMIGUNG des Storyboards)

Ein Storyboard mit 5–8 Bildschirmausschnitten schreiben: eine Überschrift (≤ 6 Wörter), eine unterstützende Zeile, ein Bildschirmausschnitt pro Frame. Optionales „Panorama“-Layout (was die gebündelte Vorlage tut): Bildschirmausschnitte sind Teile einer breiten Leinwand, sodass Formen über Rahmenkanten hinweg weiterlaufen. Welches Layout auch immer verwendet wird, jedes Angebot (kostenloser Start, Testversion) muss wahr sein.

2. Echte Bildschirme aufnehmen

Jeden Bildschirm in der logischen Größe × Pixeldichte des Zielgeräts aufnehmen, sodass Text und Layout exakt dem entsprechen, was das Gerät zeigt. Flutter-Beispiel (Widget/Golden-Test):

// 6,9" iPhone: 440 x 956 logische Punkte @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 steps'), findsOneWidget);       // die Zahl in der Überschrift ist echt
await expectLater(find.byType(App), matchesGoldenFile('captures/en/iphone69/01_home.png'));

• Schriftarten in Tests laden (sonst rendert der Test Schriftart-Boxen).
• Feste Uhrzeit, feste Demodaten, kein Netzwerk.
• Debug-Banner ausblenden; die Statusleiste auf einen sauberen Zustand setzen (oder sie zuschneiden und keine zeichnen).
• Jedes Gebietsschema separat aufnehmen; niemals englische UI in einen lokalisierten Bildschirmausschnitt einfügen.

3. Bildschirmausschnitte zusammensetzen

Vorlage: templates/panorama.html, Renderer: scripts/render.mjs.

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

Der Renderer legt alle Bildschirmausschnitte auf einer Leinwand an (Breite = Bildschirmausschnitte × Rahmenbreite), lädt die Aufnahmen, wartet auf Schriften und erstellt Screenshots von jedem Rahmenausschnitt in exakter Pixelgröße, für jedes Gerät in der Konfiguration. Er rendert auch das 1024×500-Feature-Graphic.

4. Prüfen

node check-images.mjs out/

Fehlschläge bei: falschen Abmessungen für das Gerät des Ordners, vorhandenem Alphakanal (PNG-Farbtyp 4/6 oder tRNS-Chunk), mehr als 10 (Apple) / 8 (Play) Dateien, Lücken in der Nummerierung. Dann jedes Bild bei 100 % Zoom ansehen: abgeschnittener Text, UI einer anderen Plattform, Platzhalterstrings, veraltete Zahlen.

5. Über APIs hochladen (GENEHMIGUNG vor dem Ersetzen von Live-Sets)

• App Store Connect — scripts/upload-asc.mjs: Finde die bearbeitbare appStoreVersion → deren appStoreVersionLocalizations → appScreenshotSets pro screenshotDisplayType → alte Screenshots löschen → reservieren (POST /v1/appScreenshots mit fileName, fileSize) → die Teile aus uploadOperations hochladen → committen (PATCH mit uploaded: true und dem MD5-sourceFileChecksum) → die Reihenfolge über die appScreenshots-Beziehung des Sets festlegen. Dokumentation: Assets hochladen.
• Google Play — scripts/upload-play.mjs: edits.insert → edits.images.deleteall pro Sprache und Bildtyp → edits.images.upload in der richtigen Reihenfolge (phoneScreenshots, sevenInchScreenshots, tenInchScreenshots, featureGraphic) → edits.commit. Dokumentation: edits.images.upload.

Beide Skripte standardmäßig im Trockenmodus; setze DRY_RUN=0 zum Schreiben.

6. Rücklesen

Liste die hochgeladenen Assets pro Sprache und Gerät (beide APIs) auf und vergleiche Anzahl und Reihenfolge mit dem lokalen Ordner. Apple verarbeitet Uploads asynchron; warte, bis jedes Asset den Lieferstatus COMPLETE meldet.

Entscheidungspunkte, die menschliche Genehmigung erfordern

Storyboard und Überschriften, finale visuelle Ausrichtung, Ersetzen eines Live-Screenshot-Sets, Committen der Play-Bearbeitung.

Überprüfung

• check-images.mjs besteht; jeder erforderliche Apple-Slot hat mindestens ein Bild; Play hat Telefonaufnahmen und das Feature-Graphic.
• Rücklesereihenfolge stimmt überein; keine fehlgeschlagenen Asset-Status.
• Jede Zahl und jedes Feature in den Bildschirmausschnitten wurde gegen den Build überprüft.

Häufige Fallstricke

• Nur 6,9" hochladen und den erforderlichen mittleren Dynamic-Island-Slot vergessen.
• PNGs, die mit einem Alphakanal exportiert wurden (häufig bei Designtools und Headless-Browsern mit transparentem Hintergrund – immer einen undurchsichtigen Hintergrund setzen).
• Das 6,9" 1320×2868-Bild auf Play verwenden: sein Seitenverhältnis überschreitet Plays 2:1-Limit; eine Play-spezifische Größe rendern.
• iPad-Screenshots für eine iPhone-only-App (nicht nötig) – oder sie fehlen, wenn die App auf iPad läuft.
• Ein Bildschirmausschnitt, der eine Einstellungszeile oder ein Ergebnis zeigt, das die App nicht hat.
• Überschrift übersetzt, aber die Aufnahme ist noch auf Englisch.