Comment migrer l’interface de capture d’écran de l’App Store Connect API 4.5.1 ? 2026

Le changement ne consiste pas à remplacer un nom de ressource par un autre dans le code. L’ancien modèle s’appuyait sur des ensembles de captures ou d’aperçus auxquels les fichiers étaient rattachés. App Asset Library organise les images et vidéos comme des ressources réutilisables, puis les associe à des surfaces de l’App Store au moyen d’emplacements. La documentation de migration d’Apple décrit cette nouvelle organisation.

Les notes de version signalent comme obsolètes App Screenshot Sets, App Screenshots, App Preview Sets et App Previews, ainsi que certaines ressources de médias liées aux événements intégrés à l’application. La formulation « obsolète » n’indique pas, à elle seule, une date d’arrêt immédiat. Ne supprimez donc pas les appels existants sur la seule base de cette mention ; planifiez leur remplacement et vérifiez les informations de prise en charge publiées par Apple avant de fixer une échéance interne.

La présentation officielle d’App Asset Library permet de vérifier les ressources disponibles dans le modèle cible. Dans votre dépôt, recherchez les noms des anciennes ressources, les identifiants enregistrés en base, les tâches de publication et les scripts qui reconstruisent les associations à partir d’un nom de fichier. Une migration limitée aux appels réseau laisse souvent intacte la partie la plus risquée : les données qui relient une image à une page, une langue ou un ordre d’affichage.

Une même image ou vidéo peut servir sur plusieurs surfaces. Il faut donc séparer le fichier de son usage : l’image constitue une ressource, tandis que son emplacement exprime où et comment elle doit apparaître. Un ancien ensemble de captures ne doit pas être traité comme l’équivalent automatique d’un nouvel emplacement. La documentation d’Apple sur le placement des ressources sur les surfaces de l’App Store décrit les relations à contrôler.

Pour la migration, construisez une table de correspondance interne dont chaque ligne décrit une relation métier : application, surface, localisation, type de média, ordre et identifiants source et cible. Conservez cette correspondance avec les journaux de déploiement. Si votre automatisation se contente de reprendre une liste d’anciens identifiants, elle peut réussir l’envoi tout en associant les fichiers à la mauvaise langue ou à une page inattendue.

Le réemploi mérite un contrôle distinct. Avant de remplacer ou supprimer une ressource, recherchez toutes ses associations actives dans les pages de version, les pages personnalisées, les expérimentations et les événements que vous gérez. La suppression d’un fichier supposé « ancien » peut affecter plusieurs surfaces si votre processus partage une ressource. Enregistrez donc l’état des associations avant toute modification destructive, puis comparez-le à l’état obtenu après migration.

Les exigences visuelles évoluent. Les notes de version de l’API 4.5.1 mentionnent notamment une nouvelle catégorie de présentation associée à iPhone Duo. Il ne faut pas en déduire une dimension ou une limite permanente à partir d’une valeur codée en dur. L’API expose des données de référence destinées à découvrir les spécifications applicables ; consultez la documentation officielle sur la découverte des spécifications des ressources et les spécifications de captures publiées par Apple.

Votre générateur doit lire les types de présentation, dimensions et restrictions que renvoie la source actuelle, puis les appliquer au média avant l’envoi. Stocker ces contraintes comme constantes définitives dans un script de longue durée crée un décalage possible entre le contrôle local et les attentes d’App Store Connect. Gardez les valeurs observées avec la trace de validation, mais faites de la réponse de référence la donnée utilisée pour le contrôle au moment de l’exécution.

Cette règle vaut aussi pour les équipes créatives qui produisent captures, vidéos de démonstration ou autres médias. Séparez la création du fichier et son admissibilité pour une surface donnée. Un export valide pour un usage ne devient pas automatiquement admissible pour un autre type de présentation. Si la vérification locale échoue, arrêtez le flux avant la réservation ou l’envoi : vous éviterez de diagnostiquer plus tard un refus attribué à tort au traitement ou au placement.

Les événements intégrés à l’application combinent un contexte éditorial, une localisation et des médias. La migration de leurs ressources ne se réduit pas au remplacement des anciennes références par une image ou une vidéo de la bibliothèque. Pour chaque événement, vérifiez la localisation, le type de média attendu et l’emplacement cible. Établissez également si un fichier est réutilisé sur une autre page avant de le remplacer.

Traitez les événements comme une branche de migration distincte, même s’ils partagent le mécanisme d’envoi avec les captures de pages produit. Cela rend les erreurs plus faciles à isoler : une association erronée à une page de version ne sera pas confondue avec une publication d’événement incomplète. Dans les journaux, associez chaque opération à l’identifiant de l’événement, à sa localisation et à la ressource concernée. Si une modification échoue, vous pourrez revenir à l’association précédente sans reconstruire l’ensemble de la bibliothèque.

Avant le déploiement, testez aussi le remplacement d’un média déjà référencé. Le contrôle doit confirmer que le nouveau fichier est traité et que l’événement pointe vers la bonne ressource, sans détacher par erreur les autres usages. Une réussite de l’appel de création n’est pas une preuve que l’événement présente le média attendu.

Pour une chaîne de [Mac CI screenshot upload], ou d’envoi de captures depuis la CI Mac, distinguez les étapes qui sont souvent regroupées sous un statut vague de « publication réussie ». La documentation d’Apple sur le processus d’envoi des ressources décrit le flux d’envoi ; votre propre automatisation doit en conserver les résultats séparément.

L’API peut accepter une opération sans que le média soit déjà traité ou visible sur la page cible. Votre pipeline ne doit donc pas transformer une réponse favorable à l’envoi en succès final de publication. Attendez l’état de traitement requis, vérifiez l’association à l’emplacement, puis contrôlez réellement la page dans l’application de test ou le parcours isolé choisi. Gardez une trace de chaque état : elle permettra de savoir si un incident provient du transfert, du traitement, de l’association ou de l’affichage.

Pour l’authentification, séparez les secrets des journaux et accordez aux tâches uniquement les autorisations nécessaires à leurs opérations. Ne consignez pas de jetons dans les artefacts de diagnostic. Cette précaution est particulièrement importante lorsque plusieurs personnes peuvent relancer une tâche ou consulter les journaux de publication : elles ont besoin des identifiants de ressources et des états de traitement, pas des secrets qui autorisent l’accès.

Un changement de ressource ne signifie pas automatiquement qu’il faut reconstruire le nœud de compilation. Si les captures sont produites par un simulateur, un outil graphique ou une étape qui s’exécute sur macOS, gardez cet environnement pour la génération et remplacez seulement les étapes d’envoi et de placement. Si les fichiers sont déjà créés ailleurs et que le pipeline ne fait que transmettre des médias à l’API, vérifiez la compatibilité de cette étape sans supposer qu’un nouveau Mac est nécessaire.

Déployez d’abord la migration sur un parcours isolé, une application de validation ou une voie de publication non destinée aux utilisateurs. Exécutez-y le flux complet et comparez l’ancien résultat attendu avec les nouvelles associations. Pour la vérification visuelle, contrôlez la page réellement concernée et non seulement la présence des fichiers dans la bibliothèque.

La décision peut se prendre à partir des conditions suivantes :

• Si chaque média est correctement associé à la surface, à la localisation et à l’ordre attendus, et si le traitement comme l’affichage sont vérifiés, choisissez une bascule progressive par type de média ou par surface.
• Si l’envoi réussit mais que l’état de traitement ou l’affichage reste inconnu, maintenez l’ancien parcours et bloquez la promotion en production jusqu’à obtention des preuves manquantes.
• Si plusieurs pages utilisent une même ressource et que votre inventaire ne permet pas d’en retrouver les références, reportez les suppressions et complétez la cartographie avant le remplacement.
• Si la validation révèle une différence de format ou de placement, corrigez la génération ou les associations, puis rejouez le test sur le même parcours isolé.
• Si l’ancienne voie échoue pendant la transition, réactivez-la selon votre procédure documentée et conservez les identifiants et journaux de la tentative ; ne supprimez pas les ressources de référence avant d’avoir confirmé le retour arrière.

La fiche de validation doit contenir les appels effectués, les identifiants des ressources et emplacements, les états de traitement observés et les résultats du contrôle de page. Conservez également la version des spécifications consultée et l’artefact source. Ces éléments permettent de reproduire l’échec au lieu de conclure, sans preuve, que l’API a accepté une image parce qu’une tâche de transfert s’est terminée sans erreur.

• [ ] Vous avez recensé les appels et identifiants liés aux anciens ensembles de captures, d’aperçus et aux médias d’événements concernés.
• [ ] Votre table de correspondance distingue chaque surface, localisation, type de média et ordre attendu.
• [ ] Vous utilisez les spécifications retournées au moment du contrôle, plutôt qu’une dimension supposée immuable.
• [ ] Les médias d’événements ont été vérifiés séparément des captures de page produit.
• [ ] Le flux distingue la réservation, le transfert, la confirmation, le traitement et le placement.
• [ ] Vous avez contrôlé la page réelle dans un environnement isolé.
• [ ] Les journaux conservent les preuves de migration sans exposer les secrets d’authentification.
• [ ] La procédure de retour arrière conserve les ressources encore utilisées et leurs associations.

La migration touche d’abord les relations entre ressources et placements, pas nécessairement l’infrastructure de compilation. Si votre pipeline génère les captures ou traite les médias avec des outils disponibles uniquement dans votre environnement macOS, il faut préserver une capacité Mac pour cette étape. En revanche, si les médias sont déjà produits et que seule l’intégration à App Store Connect change, une modification de nœud ne se justifie pas par l’API elle-même.

Un Mac acheté peut convenir à une charge durable, prévisible et administrée directement par votre équipe. Il implique cependant l’achat du matériel, son entretien, sa capacité disponible et la gestion des périodes de faible utilisation. Une capacité distante évite d’immobiliser un poste pour une migration ou une charge ponctuelle, mais ne remplace pas les contrôles d’accès, la validation des médias ni une procédure de publication. Évaluez le besoin à partir des tâches macOS effectivement exécutées, et non du seul fait que l’API concerne l’App Store.

Si une capacité temporaire est à l’étude, vous pouvez consulter les formules de CALMVPS et les comparer à vos contraintes d’accès, de sécurité et de continuité. Cette comparaison n’est utile que si le travail nécessite réellement un Mac ; elle ne corrige ni une mauvaise association de placement ni l’absence de validation de l’affichage.

Pour une équipe qui produit ses captures sur un Mac interne et ne modifie que l’intégration API, le choix le plus prudent est donc de migrer les appels et les associations sans remplacer le nœud. Si la génération ou le traitement de médias exige une capacité macOS temporaire, une location peut éviter de mobiliser un nouvel achat pour une charge transitoire, tandis qu’un besoin permanent et fortement utilisé peut mieux justifier une machine dédiée. Si vous souhaitez examiner cette option pour votre flux de publication, consultez les possibilités de location Mac auprès de CALMVPS après avoir identifié les tâches qui doivent effectivement s’exécuter sur macOS.