Wie migrieren Sie die Screenshot-Schnittstelle von App Store Connect API 4.5.1? 2026

Welche bisherigen Screenshot- und Vorschau-Ressourcen sind betroffen? In den Release-Notes zu App Store Connect API 4.5.1 führt Apple App Screenshot Sets, App Screenshots, App Preview Sets und App Previews als veraltet auf. Die Notes nennen außerdem veraltete Ressourcen für bestimmte In-App-Event-Medien. Sie nennen an dieser Stelle jedoch kein Datum, an dem diese alten Ressourcen unmittelbar außer Betrieb gehen. Prüfen Sie den Status daher in den offiziellen Release-Notes, statt einen Abschalttermin anzunehmen.

Inventarisieren Sie zunächst alle Aufrufe, die diese Ressourcen lesen, erzeugen, ändern oder löschen. Suchen Sie nicht nur im zentralen Upload-Skript. Häufig liegen abhängige Aufrufe auch in Release-Jobs, Admin-Werkzeugen und Wiederholungsroutinen. Ein übersehener Lesezugriff kann nach der Migration beispielsweise dazu führen, dass eine Pipeline alte Sets kontrolliert, während ein neuer Job bereits Assets über die Bibliothek verwaltet.

Halten Sie je Aufruf fest:

• verwendete Ressource und HTTP-Methode;
• zugehörige App, Version und Lokalisierung;
• Medientyp und Reihenfolge;
• aufrufendes System, Credential und verantwortliches Team;
• nachfolgende Schritte, die den Upload-Status oder die Store-Seite auswerten.

Ordnen Sie alte Beziehungen nicht automatisch eins zu eins um. Ein Screenshot-Set bündelt Medien für einen bestimmten bisherigen Kontext. Die neue Struktur arbeitet mit Assets und ihrer Zuordnung zu Store-Oberflächen. Die Migrationsanleitung zur App Asset Library beschreibt diesen Wechsel; die Übersicht der App-Asset-Library-Ressourcen hilft dabei, die neuen Ressourcenbeziehungen zu prüfen.

Frage: Wie migrieren Sie App Screenshot Sets in die App Asset Library? Erstellen Sie zuerst eine Zuordnung nach Anwendung, Lokalisierung, Medientyp und Zieloberfläche. Legen Sie dann fest, welche Assets weiterverwendet werden und welche neu erzeugt oder hochgeladen werden müssen. Übernehmen Sie nicht einfach die alte Set-ID als neues Placement: Ein Placement ist eine Zuordnung zu einer Oberfläche und kein Ersatzname für ein altes Screenshot-Set.

Achtung: Behandeln Sie eine Löschoperation für ein Asset als potenziell weitreichend, bis Ihre Tests das Gegenteil belegen. Wenn mehrere Oberflächen dasselbe Asset verwenden, muss Ihr Lösch- und Ersetzungsablauf die Beziehungen berücksichtigen und vor dem Entfernen die tatsächlichen Verknüpfungen prüfen.

Ein Asset kann für unterschiedliche Store-Kontexte relevant sein. In der neuen Modellierung müssen Sie deshalb Bild oder Video und seine Verwendung auseinanderhalten. Das Asset beschreibt das Medium; ein Placement ordnet es einer konkreten Oberfläche zu. Welche Beziehungen zulässig sind und wie die Zuordnung erfolgt, erläutert Apples Dokumentation zum Platzieren von Assets auf App-Store-Oberflächen.

Das ist besonders wichtig, wenn ein Team dieselben oder abgeleitete Medien in mehreren Bereichen verwendet: bei einer App-Version und deren Lokalisierungen, auf einer Custom Product Page oder im Zusammenhang mit einer Experimentseite. Prüfen Sie für jeden Zielkontext, ob tatsächlich dasselbe Asset verwendet werden soll. Eine identische Datei kann inhaltlich wiederverwendbar sein, während Sprache, Reihenfolge oder Marketingaussage eine getrennte Variante erfordern.

Legen Sie Ihre Zuordnung in einem versionierten Manifest oder einer vergleichbaren Konfiguration ab. Die konkrete Ablageform bleibt Ihre Architekturentscheidung. Wesentlich ist, dass die Pipeline alle Beziehungen explizit und prüfbar behandelt. Eine hilfreiche Zuordnung enthält mindestens:

• unveränderliche Kennung des Assets und Medientyp;
• App und Lokalisierung;
• Zieloberfläche beziehungsweise Placement;
• vorgesehene Anzeigereihenfolge;
• Herkunft der Datei und Version des Erzeugungsprozesses;
• Freigabestatus und Ergebnis der abschließenden Sichtprüfung.

Unterscheiden Sie dabei drei Fehlerklassen. Erstens kann das Asset selbst fehlen oder nicht verarbeitet sein. Zweitens kann das Asset vorhanden, aber dem falschen Placement zugeordnet sein. Drittens kann die Zuordnung korrekt sein, während die erwartete Reihenfolge oder Lokalisierung nicht stimmt. Diese Fehler sehen in einer automatisierten Statusprüfung ähnlich aus, verlangen aber unterschiedliche Korrekturen.

Für den Parallelbetrieb sollten alte und neue Ressourcenzuordnungen in einer nicht produktiven App oder einem getrennten Release-Pfad vergleichbar sein. Prüfen Sie nicht nur, ob die Anzahl der Medien übereinstimmt. Vergleichen Sie die Identität jeder Datei, ihre Lokalisierung, ihre Reihenfolge und ihr tatsächliches Ziel. Falls Ihre Freigabe sensible Veröffentlichungsrechte einschließt, koppeln Sie den neuen Upload-Pfad an eine gesonderte Prüfung Ihrer Mac- und CI-Umgebung für Teams; ein erfolgreicher API-Aufruf ersetzt keine kontrollierte Berechtigungsvergabe.

Frage: Müssen die Bildgrößen als dauerhafte Konstanten im Upload-Code stehen? Nein. Verwenden Sie die API-Referenzdaten für gültige Asset-Spezifikationen und lesen Sie die jeweils zurückgegebenen Darstellungsarten, Größen und Beschränkungen aus. Apple dokumentiert dafür eine Schnittstelle zum Abrufen von Asset-Spezifikationen. Ergänzend führt die offizielle Übersicht zu Screenshot-Spezifikationen die geltenden Anforderungen auf.

Die Release-Notes zu App Store Connect API 4.5.1 führen auch die Darstellungsart iPhone Duo auf. Daraus sollten Sie nicht ableiten, dass eine einmal gespeicherte Liste von Gerätekategorien dauerhaft vollständig bleibt. Ändern sich unterstützte Oberflächen oder Anforderungen, kann eine hart codierte Liste dazu führen, dass Ihre Pipeline neue Fälle übersieht oder Dateien nach überholten Annahmen validiert. Behandeln Sie die Spezifikationsdaten deshalb als Eingabe für die Validierung, nicht als unveränderliche Konfiguration.

Prüfen Sie die Validierung vor dem Upload. Sie sollte den Dateityp, die jeweils geltenden Abmessungen und Beschränkungen sowie die vorgesehene Oberfläche berücksichtigen. Bewahren Sie im Jobprotokoll auf, welche Spezifikationsdaten und welche Manifestversion für einen Lauf verwendet wurden. Wenn eine Vorgabe aus der API oder Dokumentation nicht klar auf den konkreten Upload anwendbar ist, stoppen Sie die automatische Freigabe und klären Sie den Fall anhand der aktuellen offiziellen Vorgaben.

In-App-Event-Medien benötigen einen eigenen Migrationspfad. Die veralteten Ressourcen für bestimmte Event-Medien und die neuen Assets aus der App Asset Library sind nicht bloß zwei unterschiedliche Namen für dieselbe Zuordnung. Prüfen Sie je Event-Lokalisierung, welche Medienarten eingesetzt werden, welche Zielposition erforderlich ist und welche Beziehungen die neue API verlangt. Die Release-Notes benennen die veralteten Ressourcen; die Dokumentation zur App Asset Library dient als Bezugspunkt für die neuen Ressourcen.

Führen Sie die Umstellung nicht gemeinsam mit der Migration von Versions-Screenshots in einem ungetesteten Schritt aus. Ein Event kann zeitlich begrenzt sein; ein Fehler in der Medienzuordnung betrifft dann womöglich eine andere Veröffentlichung als ein fehlerhafter Screenshot einer App-Version. Halten Sie daher je Event die Lokalisierung, das Asset, den Medientyp und das Placement getrennt fest. Verknüpfen Sie die Freigabe außerdem mit einer Prüfung des tatsächlich vorgesehenen Events.

Wenn dasselbe Bild in einem Event und auf einer Store-Seite verwendet wird, testen Sie die Ersetzung einzeln. Prüfen Sie, welche Placement-Beziehungen betroffen wären, bevor Sie ein altes Asset entfernen. Ein Automatismus, der beim Austausch eines Bildes alle bekannten Verknüpfungen löscht, kann eine weiterhin gültige Darstellung an anderer Stelle beeinträchtigen.

Frage: Welche Ressourcen sind für Screenshots und Videos von In-App-Events vorgesehen? Richten Sie die Umsetzung nicht nach einer pauschalen Annahme aus dem alten Ressourcennamen aus. Lesen Sie die aktuellen API-Beziehungen für Asset, Medientyp, Event-Lokalisierung und Zielposition nach und prüfen Sie diese in Ihrer Test-App. Die für die Migration maßgeblichen Namen und Beziehungen müssen aus den aktuellen Apple-Unterlagen stammen; ein Ereignis, das im alten Ablauf erfolgreich angelegt wurde, belegt nicht, dass seine neuen Medien korrekt platziert sind.

Ein API-Wechsel bedeutet nicht automatisch, dass der gesamte Build-Knoten neu eingerichtet werden muss. Entscheidend ist, wo die Medien entstehen und welche Werkzeuge der Job verwendet. Lädt eine Pipeline bereits fertige Bild- oder Videodateien aus einem anderen System hoch, betrifft die Änderung zunächst die API-Aufrufe, die Beziehungskonfiguration und die Statusprüfung. Erzeugt ein Job dagegen Screenshots in macOS, führt er macOS-spezifische Werkzeuge aus oder hängt er von einem Mac-Simulator ab, muss genau dieser Teil der Ausführung in der Mac-CI-Teststrecke mitgeprüft werden.

Trennen Sie die Verantwortlichkeiten: Der Job, der Screenshots erzeugt, muss nicht zwangsläufig der Job sein, der Assets hochlädt und Placements anlegt. Diese Trennung erleichtert es, Fehler auf die richtige Stufe zurückzuführen. Sie verhindert zugleich, dass ein erfolgreicher Screenshot-Test als Beweis für einen erfolgreichen Upload oder eine korrekte Store-Darstellung gilt.

Frage: Wie weisen Sie nach, dass ein Screenshot-Upload abgeschlossen und korrekt angezeigt ist? Behandeln Sie den HTTP-Erfolg als Beleg für die jeweilige API-Operation, nicht als abschließenden Nachweis der Veröffentlichung. Apples Upload-Anleitung beschreibt den Upload-Ablauf. Ihre Pipeline muss zusätzlich den zurückgegebenen Ressourcenstatus beziehungsweise den erforderlichen Verarbeitungszustand prüfen und anschließend die Placement-Beziehung sowie die sichtbare Store-Seite kontrollieren.

Ein belastbarer Freigabenachweis enthält mindestens:

• Request-ID, Ressourcen-ID und Zeitstempel des Upload-Schritts;
• Ergebnis des Uploads und beobachteten Verarbeitungsstatus;
• verknüpfte App, Lokalisierung, Medientyp und Placement;
• geprüfte Reihenfolge und Ergebnis der Sichtkontrolle;
• Entscheidung über Freigabe oder Rückfall sowie den verantwortlichen Job.

Bei einem API-Erfolg, aber noch ausstehender Verarbeitung, darf der Job die Seite nicht als erfolgreich aktualisiert melden. Bei einem verarbeiteten Asset ohne erwartete Anzeige prüfen Sie zuerst Placement, Lokalisierung und Zieloberfläche. Ist die Seite korrekt, aber die Reihenfolge falsch, beheben Sie die Zuordnung statt das Asset erneut hochzuladen. Diese Trennung verhindert unnötige Wiederholungen und liefert eine nachvollziehbare Fehlerdiagnose.

Für die Umsetzung empfiehlt sich dieser Ablauf:

1. Abhängigkeiten erfassen. Suchen Sie nach Lese-, Schreib- und Löschaufrufen für alte Screenshot-, Vorschau- und Event-Medien. Erfassen Sie auch manuelle Skripte und Wiederholungsjobs.
2. Medien und Ziele abbilden. Erstellen Sie für jede Datei eine Zuordnung aus App, Lokalisierung, Medientyp, Reihenfolge und Zieloberfläche. Markieren Sie Mehrfachverwendungen ausdrücklich.
3. Spezifikationen dynamisch prüfen. Rufen Sie die aktuellen Referenzdaten ab und lassen Sie den Job Dateien gegen die geltenden Anforderungen validieren. Beenden Sie den Lauf bei einer nicht unterstützten Kombination, statt stillschweigend eine alte Annahme zu verwenden.
4. Isoliert hochladen. Testen Sie die neuen Upload- und Ressourcenbeziehungen in einer nicht produktiven App oder einem getrennten Release-Pfad. Bewahren Sie Ressourcen-IDs und Statusmeldungen auf.
5. Verarbeitung und Placement getrennt abnehmen. Warten Sie auf den erforderlichen Verarbeitungszustand. Prüfen Sie anschließend Lokalisierung, Zielseite und Reihenfolge anhand der realen Darstellung.
6. Fehler und Rückfall erproben. Simulieren Sie in der Teststrecke fehlende Medien, eine ungültige Zuordnung und einen nicht abgeschlossenen Verarbeitungsschritt. Halten Sie fest, wie Sie einen Release stoppen und zur bekannten funktionierenden Route zurückkehren.
7. Schrittweise freigeben. Schalten Sie zunächst einen begrenzten, kontrollierbaren Pfad um. Vergleichen Sie die Belege mit dem bisherigen Ablauf und erweitern Sie die Freigabe erst, wenn die neue Route reproduzierbar geprüft werden kann.

Betriebshinweis: Protokollieren Sie nicht nur den Status „erfolgreich“. Eine spätere Prüfung braucht die Ressourcen-ID, den beobachteten Zustand, die Placement-Zuordnung und das Ergebnis der Sichtkontrolle. Ohne diese Belege lässt sich ein Fehler nach dem Wechsel schwer von einem Fehler bei der Asset-Verarbeitung unterscheiden.

Nutzen Sie für den Freigabeentscheid folgende Bedingungen:

• Wenn die Pipeline alte Ressourcen nur für Screenshots oder Vorschauen einer App-Version verwendet, dann migrieren Sie zuerst diesen klar abgegrenzten Pfad und prüfen Sie Lokalisierung, Reihenfolge und Darstellung. Andernfalls trennen Sie Versionsmedien, Custom Product Pages und Event-Medien vor der Implementierung.
• Wenn Medien in mehreren Store-Kontexten genutzt werden, dann verwalten Sie Assets und Placements getrennt und testen Sie Ersetzung und Löschung auf Seiteneffekte. Andernfalls kann eine einfachere Zuordnung genügen, sofern sie den Zielkontext dennoch explizit benennt.
• Wenn der Upload erfolgreich ist, aber Verarbeitung oder sichtbare Darstellung nicht bestätigt sind, dann bleibt die Veröffentlichung gesperrt. Andernfalls dokumentieren Sie die geprüften Zustände und geben den Pfad entsprechend Ihrer Release-Regeln frei.
• Wenn die Screenshot-Erzeugung macOS, Simulatoren oder Mac-spezifische Werkzeuge voraussetzt, dann testen Sie diese Stufe in Ihrer Mac CI. Andernfalls ändern Sie für die API-Migration nicht automatisch den Build-Knoten; prüfen Sie zunächst nur Upload, Zuordnung und Statusabnahme.

Die Entscheidung schützt vor zwei entgegengesetzten Fehlern: Eine veraltete API zu ignorieren, bis sie die Release-Pipeline tatsächlich blockiert, und wegen einer noch nicht bestätigten unmittelbaren Abschaltung unnötig den gesamten macOS-Build umzubauen. Apple bestätigt die Kennzeichnung als veraltet, aber die hier herangezogenen Release-Notes nennen keinen unmittelbaren Abschalttermin. Planen Sie daher eine kontrollierte Migration, statt einen nicht dokumentierten Zeitplan zu erfinden.

Eine Migration lohnt sich nicht, wenn sie nur den Endpunkt ersetzt und die Beziehungen zwischen Lokalisierung, Medium und Store-Oberfläche ungetestet lässt. Der technische Freigabepunkt ist erst erreicht, wenn Ihre Pipeline Assets reproduzierbar hochlädt, den Verarbeitungsstatus belegt, die richtige Placement-Zuordnung herstellt und die erwartete Darstellung prüft. Halten Sie bis dahin eine kontrollierte Rückfallmöglichkeit bereit; leiten Sie aus dem Status „veraltet“ keinen sofortigen Ausfall ab.

Wenn Ihre Medienerzeugung tatsächlich macOS voraussetzt, vergleichen Sie vor einer Änderung des CI-Knotens die Anforderungen an Ausführung, Zugriff und Betrieb mit den verfügbaren Mac-Optionen. Für einen zeitlich begrenzten Test oder einen zusätzlichen Mac-CI-Knoten kann eine Mietlösung gegenüber dem Kauf sinnvoll sein, wenn Sie keine dauerhaft ausgelastete Hardware benötigen; bei stabiler Dauerlast oder erforderlichen physischen Schnittstellen kann ein eigener Mac besser passen. Prüfen Sie dazu die Preis- und Mietoptionen von CALMVPS. Wenn die Screenshots außerhalb von macOS entstehen, schließen Sie zunächst die API-Migration und die Placement-Abnahme ab, statt allein wegen App Store Connect API 4.5.1 einen neuen Mac-Knoten zu beschaffen.