App Store Connect API 4.5.1 스크린샷 인터페이스는 어떻게 마이그레이션할까? 2026

릴리스 노트는 App Screenshot Sets, App Screenshots, App Preview Sets, App Previews 네 가지 기존 리소스 계열과 일부 앱 내 이벤트 미디어 리소스를 사용 중단 예정으로 표시합니다. 새 경로는 App Asset Library의 이미지와 비디오, 그리고 이를 스토어 화면에 배치하는 관계를 사용합니다. 라이브러리 API 개요를 기준으로 새 리소스 구조를 확인하세요.

중요한 차이는 소재와 노출 위치가 같은 대상이 아니라는 점입니다. 이미지나 동영상을 라이브러리에 보관한 뒤, 어느 앱 버전의 어떤 현지화나 사용자 지정 제품 페이지 등에 표시할지를 placement로 연결해야 합니다. 기존 스크린샷 세트를 새 placement 하나로 치환하면 페이지와 언어 간 연결이 누락될 수 있습니다. 스토어 화면에 소재를 배치하는 공식 설명을 기준으로 관계를 다시 설계하세요.

기존 자동화가 버전별 스크린샷 세트를 관리한다면, 먼저 API 호출과 저장된 식별자를 조사하세요. 목록 조회만 하는 작업과 소재를 만들거나 수정하는 작업을 구분해야 합니다. 읽기 작업은 당장 운영에 미치는 영향이 작을 수 있지만, 쓰기 작업은 새로운 리소스와 placement 관계를 만들기 전까지 전환 준비가 끝난 것이 아닙니다.

소재 하나가 여러 스토어 표면에서 쓰이는 경우에는 원본 파일을 복제하는 것보다 관계를 명확히 하는 것이 중요합니다. 다음 항목을 기존 데이터베이스나 배포 산출물에 보존하세요.

• 앱 버전 또는 대상 페이지 식별자
• 현지화 코드와 미디어 종류
• 라이브러리 소재 식별자
• placement 식별자와 표시 순서
• 업로드 요청, 처리 상태, 페이지 확인 결과

마이그레이션 안내는 기존 리소스에서 새 라이브러리로 옮기는 기준을 설명합니다. 운영 중인 앱의 데이터 관계를 문서 예시와 동일하다고 가정하지 말고, 실제 응답의 관계와 현재 API 규격을 함께 대조하세요.

앱 내 이벤트의 이미지와 동영상도 기존 이벤트 리소스만 바꾸면 완료되는 작업은 아닙니다. 이벤트별 현지화, 미디어 종류, 목표 위치를 새 라이브러리의 소재와 배치 관계로 다시 연결해야 합니다. 기존 파일이 다른 페이지에서도 쓰이는지 먼저 추적하세요. 소재 삭제와 노출 위치 제거를 같은 작업으로 묶으면 의도하지 않은 페이지까지 영향을 받을 수 있습니다.

운영 자동화에서는 파일의 소유와 노출 관계를 분리해 저장하는 편이 안전합니다. 예를 들어 소재 식별자는 공용 레코드로 관리하고, 페이지별 placement는 별도 관계로 기록합니다. 삭제 요청 전에는 참조 중인 placement를 조회하고, 남은 참조가 있으면 소재를 지우지 않도록 보호 조건을 두세요. 이 방식은 소재 재사용과 페이지 전환을 서로 독립적으로 검증하게 해 줍니다.

Mac CI에서 만든 파일이 업로드 API에 전달되는 작업은 소재 생성과 API 마이그레이션을 별도 단계로 나누세요. Apple의 소재 업로드 흐름은 업로드 작업을 다루지만, API 응답 성공만으로 스토어 페이지에서 표시가 끝났다고 판단할 수는 없습니다.

Apple 문서는 업로드와 소재 처리를 위한 API 흐름을 설명합니다. 배포 시스템에서는 요청 성공, 소재 처리 완료, 페이지 표시 확인을 서로 다른 상태로 저장하세요. 마지막 상태가 확인되기 전에는 작업 전체를 성공으로 표시하지 마세요.

iPhone Duo 같은 새 표시 유형을 다룰 때도 화면 크기나 허용 조건을 상수로 고정하지 마세요. 소재 규격 탐색 API는 유효한 표시 유형과 규격 정보를 확인하는 경로입니다. 현재 반환되는 표시 유형, 크기, 제약을 읽고, Apple의 스크린샷 규격 안내와 대조해 산출물을 검사하세요. 새로운 규격이 추가될 때 코드 수정을 기다리지 않도록 반환값을 검증 기준에 반영하는 편이 낫습니다.

기존 스크린샷 리소스는 전부 같은 날 중단되나요?
아닙니다. 사용 중단 표시는 즉시 중단 날짜를 뜻하지 않습니다. Apple이 제공한 문서에 별도 중단 날짜가 있는지 확인하고, 그 전까지 새 경로를 시험하세요.

App Screenshot Sets는 무엇으로 대체하나요?
세트 자체를 일대일로 바꾸기보다 이미지 소재와 각 페이지 placement를 분리해 연결합니다. 앱 버전, 현지화, 순서도 보존하세요.

앱 내 이벤트 미디어도 점검 대상인가요?
기존 앱 내 이벤트 미디어 리소스 중 일부가 사용 중단 대상으로 안내됩니다. 실제 사용 중인 리소스를 조회해 새 이미지·비디오 관계로 매핑하세요.

업로드 응답이 성공이면 페이지 표시도 완료된 것인가요?
아닙니다. 업로드, 처리 상태, placement 연결, 실제 화면 확인을 별도 검증해야 합니다.

Mac CI 노드를 다시 만들어야 하나요?
API 변경만으로 노드를 바꿀 필요는 없습니다. Mac에서 스크린샷을 생성하거나 관련 도구를 실행하는지 확인하고, 해당 생성 작업과 API 업로드 단계를 분리하세요.

격리된 앱이나 비운영 배포 경로에서 기존 자동화와 새 흐름을 병행하세요. 같은 파일을 사용해 소재 연결, 처리 상태, 표시 순서를 대조하면 파일 생성 변화와 API 관계 변화가 섞이는 일을 줄일 수 있습니다. Apple 문서는 구형 리소스의 즉시 중단 날짜를 제시하지 않으므로, 날짜를 임의로 정해 전체 전환을 서두르지 마세요. 릴리스 노트와 마이그레이션 문서의 변경 여부를 운영 계획에서 다시 확인하세요.

다음 조건으로 전환 여부를 결정하세요.

• 새 이미지와 비디오를 만들고 처리 상태까지 확인할 수 있으면 새 업로드 경로를 시험 운영합니다. 확인할 수 없으면 기존 경로를 유지하면서 응답과 실패 로그를 수집합니다.
• 현지화와 페이지별 placement가 기존 표시 순서와 일치하면 해당 앱 범위를 전환합니다. 하나라도 빠졌으면 운영 배포를 보류하고 관계 매핑을 수정합니다.
• 격리 경로에서 실제 페이지 노출까지 확인되면 배포 범위를 늘립니다. API 응답만 성공하고 페이지를 확인하지 못했다면 성공 판정을 내리지 않습니다.
• 실패 시 구형 호출 경로와 식별자, 요청 로그가 보존되어 있으면 해당 범위를 되돌립니다. 복구에 필요한 증거가 없으면 다음 범위로 확장하지 않습니다.

승인 기록에는 호출 로그, 소재와 placement 식별자, 처리 상태, 페이지 확인 결과를 함께 남기세요. Mac에서 생성되는 스크린샷 작업이 있다면 API 전환과 별개로 해당 생성 작업이 macOS에서 정상 실행되는지도 확인하면 됩니다.

이 변경만으로 전체 Mac CI를 다시 구성할 필요는 없습니다. 다만 스크린샷 생성이나 미디어 처리가 실제로 macOS 도구에 의존한다면, 기존 환경의 노드 유지와 새 용량 마련에는 관리 부담과 유휴 용량 비용이 따릅니다. 반대로 이미 만들어진 파일을 API로 올리는 작업만 있다면 Mac 노드 추가는 불필요할 수 있습니다. 필요한 기간에만 Mac 환경을 시험하려는 팀은 CALMVPS 요금 안내와 한국 주문 경로를 검토하고, API 마이그레이션 자체와 Mac 생성 환경의 필요성을 따로 결정하세요.