Caricare screenshot dell'App Store con l'API di App Store Connect
appScreenshotSet per la lingua e il dispositivo giusti, riservare un appScreenshot (Apple fornisce URL pre-firmati per i blocchi), fare il PUT dei byte, poi eseguire il PATCH della prenotazione con uploaded: true e l'MD5 del file. L'autenticazione è un JWT di 20 minuti firmato con la tua chiave .p8. Nessun passaggio è difficile di per sé, ma tutti sono macchinosi. Ecco la sequenza reale — e la scorciatoia se preferisci non costruirla.La documentazione di Apple su questo tema è accurata e quasi illeggibile — il flusso è distribuito su una dozzina di pagine di riferimento senza un unico esempio completo. Questo articolo è la guida in ordine, con gli endpoint e i nomi dei campi esatti. È pensata per chi deve decidere se costruire l'integrazione o affidarsi a uno strumento che l'ha già fatto.
Il modello a oggetti in cui stai caricando
Gli screenshot non si agganciano direttamente alla tua app. Dipendono da una catena di oggetti, che devi percorrere dall'alto verso il basso:
- appStoreVersion — la versione specifica che stai modificando (deve essere in uno stato modificabile).
- appStoreVersionLocalization — una per ogni lingua dell'App Store (en-US, de-DE, ja, e così via).
- appScreenshotSet — una per ogni tipo di display all'interno di una localizzazione (iPhone 6,7", iPad 13", ecc.).
- appScreenshot — l'immagine singola, fino a 10 per set.
Quindi una scheda completamente localizzata in 50 lingue su due dimensioni di iPhone e una di iPad significa 50 × 3 set, ciascuno con fino a 10 screenshot. Questa moltiplicazione è il motivo per cui si automatizza il processo invece di procedere a clic nell'interfaccia web.
Passo 0 — il JWT di 20 minuti
Ogni richiesta, tranne i caricamenti dei byte veri e propri, richiede un'intestazione Authorization: Bearer con un JSON Web Token che firmi tu stesso. Ti servono tre cose da App Store Connect: il tuo issuer ID, un key ID e il file di chiave privata .p8 che scarichi una sola volta quando crei la chiave (Apple non lo mostra mai più).
Il token viene firmato con ES256 — ECDSA sulla curva P-256 con SHA-256 — usando quella chiave .p8. L'header contiene il kid; il payload contiene l'issuer come iss, l'audience come la stringa letterale appstoreconnect-v1, e un exp non oltre 20 minuti dopo iat. Apple rifiuta qualsiasi token con durata maggiore, quindi lo rigeneri spesso — conviene generare un token nuovo per ogni batch invece di provare a tenerne uno aperto.
Firma tutto questo con una qualsiasi libreria JWT compatibile con ES256 (jsonwebtoken, PyJWT, o quella del tuo stack), passa il contenuto del file .p8 come chiave, e inserisci il risultato nell'header Authorization di ogni chiamata qui sotto.
Passo 1 — creare il set di screenshot
Un set è definito per una localizzazione e un tipo di display. Fai una POST a /v1/appScreenshotSets con screenshotDisplayType negli attributes e una relationship che punta all'appStoreVersionLocalization che vuoi popolare.
Tipi di display comuni: APP_IPHONE_67 (6,7", 1290 × 2796), l'attuale dimensione per iPhone grandi, e APP_IPAD_PRO_3GEN_129 (12,9", 2048 × 2732). Una cosa utile che Apple fa ora: gli screenshot per la dimensione di iPhone più grande vengono riutilizzati per le classi di iPhone più piccole, e quelli per l'iPad più grande per gli iPad più piccoli — quindi in pratica spesso serve un solo set iPhone e un solo set iPad per lingua, non uno per ogni dispositivo fisico. La risposta fornisce un id del set da usare nella chiamata successiva. Se un set esiste già per quella lingua/tipo, riutilizzalo invece di crearne uno duplicato.
Passo 2 — riservare lo screenshot
Non carichi il file in un'unica soluzione. Prima lo riservi: comunichi ad Apple il nome del file e la dimensione esatta in byte, e ricevi un piano di caricamento. Fai una POST a /v1/appScreenshots con gli attributi fileName e fileSize e una relationship verso il set del passo 1.
La risposta è la parte interessante. Negli attributes del nuovo screenshot trovi uploadOperations — un array che descrive esattamente come inviare i byte. Per un file piccolo è un'unica operazione; per uno grande Apple lo divide in più parti. Ogni voce fornisce un method (PUT), un url pre-firmato, l'offset e la length in byte da inviare, e i requestHeaders da allegare.
Passo 3 — il PUT dei byte
Per ogni operazione, leggi la porzione del tuo file a partire da offset per length byte, e fai il PUT all'url indicato con esattamente i requestHeaders forniti da Apple. Questi URL sono pre-firmati, quindi non invii il tuo JWT qui — aggiungere l'header Authorization può in effetti rompere la richiesta firmata. Più operazioni possono girare in parallelo, ma Apple limita i caricamenti aggressivi, quindi conviene avvolgerle in un retry con backoff invece di lanciarle tutte insieme.
Passo 4 — commit con uploaded: true e l'MD5
Caricare i byte non serve a nulla finché non comunichi ad Apple che la prenotazione è completa. Fai il PATCH dello screenshot con uploaded: true e un sourceFileChecksum — l'MD5 dell'intero file come stringa esadecimale minuscola. Questo è il controllo di integrità di Apple: se il checksum non corrisponde a ciò che è arrivato, l'elaborazione fallisce.
Dopo il PATCH, l'asset entra in elaborazione lato Apple. Effettua polling sull'assetDeliveryState dello screenshot finché non raggiunge uno stato completato — e leggi i suoi errors se fallisce, perché è lì che emergono i problemi di dimensioni sbagliate e canale alfa. Il PUT e il PATCH possono entrambi riuscire e lo screenshot può comunque venire respinto minuti dopo, durante l'elaborazione. Non dare per scontato che un 2xx sul commit significhi che hai finito; monitora lo stato di consegna.
Passo 5 — impostare l'ordine di visualizzazione
Gli screenshot vengono restituiti nell'ordine in cui sono stati creati, che raramente è l'ordine che vuoi mostrare. L'ordine del set è una relationship separata. Fai il PATCH di /v1/appScreenshotSets/{id}/relationships/appScreenshots con un array di ID di screenshot — l'ordine dell'array è l'ordine di visualizzazione sullo store.
I vincoli che Apple applica davvero
- Solo PNG o JPEG. Niente HEIC, niente WebP. Se il tuo renderer produce altro, converti prima.
- Nessun canale alfa. Appiattisci la trasparenza su uno sfondo pieno ed esporta in RGB. Un canale alfa residuo è una delle cause più comuni di rifiuto silenzioso in fase di elaborazione.
- Dimensioni esatte per ogni tipo di display. L'immagine deve corrispondere con precisione alle dimensioni in pixel del tipo di display — niente scostamenti minimi, niente upscaling. Un file da 1290 × 2796 va in un set
APP_IPHONE_67e in nessun altro. - Fino a 10 per set. Dieci screenshot al massimo per localizzazione e tipo di display.
- Solo versione modificabile. Puoi modificare i set solo su una versione in stato modificabile; una versione già in revisione è bloccata.
Perché è più laborioso di quanto sembri
Ogni singola chiamata è semplice. Il costo sta in tutto ciò che le circonda: firmare e rinnovare un token di 20 minuti, calcolare gli MD5, suddividere i file secondo uploadOperations, gestire i retry dei caricamenti parziali, monitorare lo stato di consegna, mappare le tue lingue sui codici locale di Apple, e fare tutto questo oltre 150 volte per una scheda correttamente localizzata. Renderlo affidabile richiede un weekend tra autenticazione, caricamenti a blocchi e gestione errori — e poi resta a tuo carico ogni volta che Apple aggiunge un tipo di display.
Se vuoi la sequenza senza scriverla, il deliver di Fastlane avvolge questa stessa API ed è il percorso open source standard. Risolve il caricamento; non disegna il carosello né scrive le didascalie.
…oppure salta tutto questo
L'API sposta solo immagini già finite. Qualcosa deve comunque progettare il carosello, scrivere le didascalie e tradurle per ogni lingua — ed è questa la parte che richiede davvero tempo. Mokbi lo fa già oggi: progetta gli screenshot, redige i testi della scheda e traduce tutto in 50 lingue, poi esporta ogni immagine esattamente nelle dimensioni per tipo di display richieste da questa API — PNG, RGB, senza alfa, dimensione giusta — così un caricamento non rimbalza al passaggio dello stato di consegna.
Poi pubblica. Per l'App Store, Mokbi esegue esattamente questa sequenza reserve-and-commit sotto il cofano — caricando i tuoi screenshot e i metadati e preparando la versione pronta per l'invio, così non tocchi mai un JWT o un PUT a blocchi. Apple richiede comunque l'invio finale (Submit) e la relativa revisione; tutto ciò che precede è gestito per te. Per Google Play, invece, pubblica direttamente sullo store. In entrambi i casi ottieni il risultato dell'API senza scrivere codice, con il design, i testi e la traduzione in 50 lingue già pronti.