Как перенести интерфейс снимков App Store Connect API 4.5.1? 2026

В примечаниях Apple к выпуску App Store Connect API 4.5.1 перечислены новые ресурсы App Asset Library и помечены как устаревшие прежние ресурсы наборов снимков, отдельных снимков, наборов видеопревью и отдельных превью. Там же часть ресурсов медиа приложений отмечена как устаревшая. Apple рекомендует переходить к изображениям и видео из библиотеки активов и связывать их с поверхностями магазина через placements. В примечаниях к версии 4.5.1 не указана дата немедленного отключения перечисленных старых ресурсов.

Разделяйте три понятия, которые в старом конвейере могли казаться одной операцией:

• Файл — изображение или видео, которое система загрузила в App Store Connect.
• Актив библиотеки — объект App Asset Library, с которым связаны данные о медиафайле и его использовании.
• Placement — связь актива с конкретной поверхностью магазина, локализацией или страницей, где он должен применяться.

Поэтому перенос прежнего набора снимков нельзя свести к переименованию типа ресурса. Старый набор мог одновременно служить контейнером, отражать порядок показа и соответствовать конкретной локализации. В новой модели проверьте, каким активом представлен каждый файл и к какой поверхности он прикреплён. В обзоре ресурсов App Asset Library описаны ресурсы новой модели; отношения и назначение поверхностей уточняйте также по руководству Apple по размещению активов.

Таблица — карта инвентаризации, а не автоматическое правило преобразования API-объектов один к одному. Точные связи проверяйте по актуальной документации и схеме используемой версии API. В частности, не переносите прежнее имя набора в новое поле placement без проверки: идентификатор контейнера и назначение актива — разные части модели.

Если одна и та же картинка или видеозапись нужна для нескольких страниц, сначала выясните, допускает ли нужная поверхность магазина такое размещение и как API выражает соответствующую связь. App Asset Library меняет способ организации медиа, но не отменяет необходимости учитывать контекст показа. Актив может быть подготовлен один раз, а его использование в версии приложения, локализованной странице или Custom Product Page должно быть отражено отдельно в данных placement.

Поддерживайте явное соответствие между четырьмя атрибутами: страницей, локализацией, типом медиа и порядком показа. Не храните их только в имени файла или в неформальном соглашении внутри скрипта. Если у вас есть записи вроде screen-1, имя файла не сообщает, для какой локали и поверхности он предназначен. После переноса такой сценарий может завершиться успешной загрузкой, но актив окажется связан не с тем размещением или не в том порядке.

Для сопоставления используйте проверяемый манифест, который хранится рядом с исходниками релиза. Для каждого объекта запишите исходный старый идентификатор, новый идентификатор актива, целевую страницу, локализацию, тип медиа, предполагаемый порядок и состояние проверки. Если один актив используется повторно, фиксируйте каждую связь отдельно. Так вы сможете заменить placement, не удаляя общий актив, который ещё нужен другой странице.

Решение по повторному использованию:

• Если файл нужен нескольким поверхностям и API допускает требуемые связи, храните его как отдельный актив и создавайте проверяемые placements для каждого назначения.
• Если для страниц нужны разные локализованные материалы, не объединяйте их в один универсальный актив только ради сокращения количества файлов.
• Если команда не может подтвердить, какое назначение использует актив, не удаляйте и не перезаписывайте его в производственном контуре до проверки ссылок.
• Если схема не позволяет однозначно сопоставить старое назначение с новым placement, оставьте старый путь на время пилота и разберите случай отдельно, а не угадывайте соответствие.

Спецификации снимков нельзя надёжно хранить как вечные константы в коде загрузчика. В API 4.5.1 добавлены данные для обнаружения применимых спецификаций, а в новых категориях показа фигурирует iPhone Duo. Вместо жёстко заданного списка типов, размеров и ограничений загрузчик должен получать актуальные справочные данные и выбирать параметры по текущему ответу API. Наличие категории в справочнике не означает, что любое изображение подходит для любой страницы или локализации.

Apple отдельно публикует справочные данные для обнаружения спецификаций активов и требования к снимкам экрана. Используйте эти источники, чтобы сверять формат, размеры и ограничения. Если спецификация изменилась, устаревшее значение в конфигурации CI может приводить к отказу загрузки ещё до того, как команда проверит placement.

Разделите в коде две функции: обнаружение требований и подготовку изображения. Первая получает действующие спецификации и выбирает подходящий набор для типа устройства и назначения. Вторая использует выбранные параметры для валидации или преобразования исходного изображения. Так ошибка в новой категории не будет замаскирована повторным использованием старого пресета.

В журнал сборки записывайте версию ответа или сами параметры, на основании которых валидировалось медиа, если это допустимо политикой хранения данных. Это упростит разбор расхождений между результатом генерации и тем, что API принимает сейчас. Не выводите размеры из названия файла и не переносите старое ограничение на новую категорию без сверки с актуальным справочником.

При миграции медиа событий приложения не смешивайте три действия: перенос файла в библиотеку, создание или обновление его связи и назначение размещения. Для каждой локализации события установите, какие изображения и видео используются, к какому месту показа они относятся и сохраняется ли эта связь после изменения актива.

Проверьте также поведение при замене и удалении. Если один актив уже используется на нескольких страницах, удаление файла по признаку «больше не нужен этому событию» может затронуть другой сценарий, если ваша система не проверяет связанные placements. Сначала получите и сохраните список связей, затем меняйте конкретное назначение. Удаляйте актив только после того, как подтверждено отсутствие других зависимостей или создана безопасная замена.

У части старых ресурсов медиа событий в выпуске 4.5.1 есть статус устаревания; конкретное соответствие проверяйте по примечаниям Apple к версии и документации миграции. Не переносите на все ресурсы событий общее предположение, будто каждый старый объект заменяется одним и тем же типом нового актива. В манифесте фиксируйте локализацию события, тип файла, прежнюю связь и новый placement.

Важное различие: актив, прошедший загрузку, ещё не подтверждает корректное размещение на странице события. Приёмка должна включать проверку статуса обработки и отдельный осмотр фактического представления в App Store Connect или доступном тестовом контексте.

Миграция API не означает автоматически, что нужно перестраивать весь узел Mac CI. Сначала установите, где именно рождается файл. Если снимки формируются на macOS, например в задаче, которая запускает нужные инструменты Apple или получает изображение из симулятора, этот шаг остаётся привязанным к Mac-среде. Если файлы создаются другим процессом и уже доступны конвейеру как готовые артефакты, перенос API-слоя можно проверить отдельно от сборочного узла.

Разбейте Mac CI screenshot upload на независимо диагностируемые этапы. Так станет видно, где произошёл сбой: при генерации, загрузке файла, обработке, создании placement или визуальной проверке. В документации Apple по загрузке активов в App Store Connect описан процесс загрузки; реализуйте его с учётом фактических требований к этапам и ответам API, а не как единственный вызов «отправить снимок».

Сохраняйте идентификаторы ресурсов и состояния отдельно от обычного сообщения «задача успешна». Ответ без ошибки при подготовке загрузки не равен завершённой передаче файла. Завершённая передача не равна подтверждённой обработке. И обработанный файл не доказывает, что корректно создан placement или что ожидаемая страница показывает именно этот актив. Эти различия — основа расследования, а не формальность для отчётности.

Пошаговая приёмка новой цепочки

1. Инвентаризируйте вызовы. Найдите используемые ресурсы наборов снимков, отдельных изображений, видеопревью и медиа событий. Сопоставьте каждый вызов с репозиторием, job и владельцем процесса.
2. Опишите назначения. Для каждого файла зафиксируйте страницу или событие, локализацию, тип медиа и порядок. Добавьте прежние идентификаторы, чтобы результаты старого и нового пути можно было сравнить.
3. Получите актуальные требования. Используйте справочные ресурсы спецификаций, а не неизменяемые константы из старой конфигурации. Проверьте, что выбранный тип подходит целевой поверхности.
4. Подготовьте изолированный контур. Используйте тестовое приложение, непроизводительную публикацию или другой безопасный путь, который не меняет материалы текущего релиза. Секреты API и доступы проверьте отдельно от логики ресурсов.
5. Выполните всю цепочку. Создайте актив, передайте файл, дождитесь состояния обработки, создайте placement и проверьте результат. Записывайте идентификатор и результат каждого этапа.
6. Сравните представление. Проверьте локализацию, вид страницы, порядок, тип медиа и отсутствие подмены активов. Не принимайте API-ответ за визуальную приёмку.
7. Проверьте восстановление. Смоделируйте сбой до завершения передачи и после неё. Убедитесь, что повторный запуск не создаёт лишних ресурсов и не удаляет актив, который используется другой страницей.
8. Разрешите переключение по критериям. Переводите одну группу публикаций за раз. Оставьте старый путь доступным для отката, пока новый не подтвердил все контрольные пункты.

Не переводите все приложения команды одновременно. На первом этапе запускайте новый маршрут в изолированной публикации или для ограниченного набора материалов. Сравнивайте не только число успешных запросов, но и итоговые связи: соответствует ли каждый актив нужной локализации, совпадает ли порядок и видна ли ожидаемая версия медиа.

При параллельной работе два пути могут создавать дубли. Поэтому задайте правило идентификации артефакта и повторного запуска. До отправки решите, как система определит уже созданный актив и как она обновит placement при повторной публикации. Если API не предоставляет безопасную идемпотентность для конкретной операции, храните локальное соответствие и не повторяйте запрос вслепую после сетевого тайм-аута.

Критерии переключения должны быть доказуемыми: набор медиа сопоставлен; обработка завершена; placements проверены; порядок отображения подтверждён; повторный запуск и восстановление испытаны; в журнале остались идентификаторы и результаты. Если любой пункт не подтверждён, остановите расширение пилота. Устаревание прежнего ресурса — повод запланировать миграцию, но не повод отключить работающий путь без проверенного нового маршрута и плана возврата.

Решение по миграции и узлу CI

• Если сборка создаёт снимки на macOS, оставьте Mac-этап генерации и отдельно замените API-часть после приёмки.
• Если готовые файлы поступают из другого процесса, тестируйте новую модель активов независимо от замены или переоснащения Mac-узла.
• Если после загрузки нет подтверждения обработки или проверки показа, не допускайте автоматический выпуск на основании одного успешного ответа API.
• Если новый placement не прошёл сверку с локализацией и порядком, возвращайтесь к прежнему пути для этой группы материалов и сохраняйте диагностические данные.
• Если старый и новый пути параллельно меняют один и тот же контент, остановите конкурирующую запись и назначьте одному конвейеру роль владельца публикации.

Для управления выпуском сохраняйте журнал вызовов, идентификаторы активов, состояния обработки и запись визуальной проверки. Не записывайте секреты авторизации в логи. Доступы и полномочия автоматизации проверяйте по применяемой политике команды; изменение типа ресурса не должно незаметно расширять права CI.

Если команда отдельно оценивает, где выполнять генерацию снимков или тесты на macOS, выбор среды решайте по требованиям к самим задачам, а не по факту перехода на App Asset Library. Сведения о вариантах CALMVPS можно начать изучать на странице сервиса; для коммерческого сравнения используйте условия и тарифы. Удалённый Mac имеет смысл оценивать, если ваш конвейер действительно запускает macOS-инструменты или нуждается в отдельной Mac-среде. Если артефакты готовятся вне macOS, API-миграция сама по себе не обосновывает аренду узла.

До переключения зафиксируйте один ответственный за активы, один источник истины для манифеста и один проверяемый критерий «показ подтверждён». Это уменьшит риск, что старый скрипт перезапишет новый placement или что оператор примет состояние загрузки за результат релиза. Для миграции App Store Connect API 4.5.1 безопасный маршрут — перенести модель связей, доказать обработку и фактический показ в пилоте, а затем расширять переход по приложениям и публикациям.