ITMS-90717: risolvere «Invalid large app icon» con Expo

ITMS-90717 è un controllo automatico di Apple sul tuo build. Ti dice che l'icona grande dell'app, quella da 1024 x 1024 pixel mostrata dall'App Store, contiene trasparenza o un canale alfa. La soluzione: un'icona quadrata e opaca, esportata senza canale alfa, e poi un nuovo build.

Con Expo il tuo file PNG è raramente il colpevole: il prebuild lo appoggia già su uno sfondo bianco. Ho letto questo codice nell'SDK 57 e ho controllato le icone di Solys, TradaZen e Nolera. In quel caso l'errore arriva quasi sempre da una cartella ios versionata o da un file Icon Composer. Ecco come capire quale dei due, e come sistemarlo.

Cosa significa l'errore ITMS-90717?

Il messaggio si intitola «ITMS-90717: Invalid large app icon». Specifica che l'icona grande nel catalogo immagini della tua app «can't be transparent or contain an alpha channel»: non può essere trasparente né contenere un canale alfa. I messaggi più vecchi parlavano di «Invalid App Store Icon». La regola è la stessa.

Questa icona grande è quella dell'App Store. La documentazione di Xcode sulle icone lo spiega: un'app distribuita sull'App Store deve fornire la sua icona da 1024 punti nel catalogo immagini.

Il canale alfa è il quarto livello di un PNG, accanto a rosso, verde e blu. Memorizza la trasparenza di ogni pixel. Un'icona può sembrare piena e avere comunque questo canale: è la trappola che torna in tutti i thread dei forum.

Come gli altri errori ITMS, non è il rifiuto di un reviewer. Apple ha analizzato il binario alla consegna. A seconda dello strumento di invio, l'errore compare come un fallimento della validazione, per esempio con il codice 409.

Controllare l'icona con sips

Su Mac sips è già installato. Basta una riga:

sips -g hasAlpha assets/icon.png

Vuoi leggere hasAlpha: no. Il 15 ottobre 2026 ho lanciato questo comando sulle icone dichiarate negli app.json di Solys, TradaZen e Nolera: tutte rispondono no, in 1024 x 1024.

Ho anche creato un'icona di prova: un quadrato blu completamente opaco, ma salvato con un canale alfa. sips risponde yes. Nessun pixel è trasparente, eppure il canale c'è. Ecco perché tanti sviluppatori scrivono «la mia icona non ha nessuna trasparenza» sotto questo messaggio.

In Anteprima, anche l'inspector (Tools, Show Inspector) elenca le proprietà dell'immagine, compreso il canale alfa.

Correggere: esportare l'icona senza canale alfa

Tre metodi, dal più semplice al più preciso.

1. Anteprima. File, Export, formato PNG, poi togli la spunta da Alpha. Il file esportato non ha più il canale alfa.

2. sips, senza installare niente. sips non rimuove il canale alfa da un PNG. Devi passare da un JPEG, che non ce l'ha:

sips -s format jpeg -s formatOptions 100 icon.png --out icon.jpg
sips -s format png icon.jpg --out icon-opaque.png
sips -g hasAlpha icon-opaque.png

Sulla mia icona di prova con gli angoli trasparenti, gli angoli sono diventati bianchi e l'ultima riga risponde no. Il passaggio dal JPEG comprime un po' l'immagine, anche alla qualità massima: guarda il risultato da vicino.

3. ImageMagick. Se ce l'hai installato, scegli tu il colore di sfondo:

magick icon.png -background white -alpha remove -alpha off icon-opaque.png

Secondo la documentazione di ImageMagick, -alpha remove appoggia l'immagine sul colore di sfondo e -alpha off disattiva il canale.

Tutti e tre i metodi riempiono la trasparenza con un colore pieno. Se il tuo logo galleggiava su uno sfondo trasparente, la cosa più pulita è riprendere il file sorgente e disegnarci uno sfondo vero. Expo lo chiede nella sua guida all'icona dell'app: l'icona deve riempire tutto il quadrato, senza angoli arrotondati né pixel trasparenti. La maschera la applica iOS.

Dove Expo prende la tua icona, e cosa ne fa

Expo legge prima ios.icon, poi il campo icon alla radice della configurazione. Secondo il riferimento della configurazione di Expo, ios.icon accetta tre forme: un PNG, un oggetto con le varianti light, dark e tinted, oppure una cartella .icon creata con Icon Composer.

La tabella qui sotto viene dal codice che genera l'icona iOS al prebuild, @expo/prebuild-config 57.0.16 (SDK 57), letto il 15 ottobre 2026:

Cosa dichiari	Cosa fa il prebuild	Rischio ITMS-90717
icon in PNG	Appiattita su sfondo bianco	Basso
ios.icon.light	Appiattita su sfondo bianco	Basso
ios.icon.tinted	Appiattita su sfondo bianco	Basso
ios.icon.dark	Trasparenza mantenuta	Voluto da Apple
ios.icon in .icon	Copiata così com'è	Reale
Cartella ios versionata	Prebuild non rilanciato	Reale

Con un PNG, Expo rimuove da solo la trasparenza e la sostituisce con il bianco. Un logo scontornato finisce quindi su un quadrato bianco: nessun errore, ma un risultato che forse non volevi. La variante scura mantiene la trasparenza, ed è voluto: Apple chiede uno sfondo trasparente per l'icona scura, così si vede lo sfondo fornito dal sistema.

Su Nolera, che dichiara le tre varianti, sips risponde no per l'icona chiara e per quella tinted generate, yes per quella scura. Dalla data del commit di queste varianti, la versione 1.0.2, già pubblicata, le include. Non l'ho verificato nel suo IPA.

Il caso della cartella ios versionata

È la causa più probabile con Expo. La pagina di Expo sulla generazione nativa continua lo dice: se il tuo progetto contiene le cartelle android e ios, EAS Build non lancia il prebuild. A quel punto il tuo app.json non tocca più l'icona: ad Apple arriva il PNG della cartella ios.

Controllalo dalla radice del progetto:

sips -g hasAlpha ios/*/Images.xcassets/AppIcon.appiconset/*.png

Se il comando risponde yes per l'icona 1024, sostituisci quel file con la tua versione opaca, con lo stesso nome. Se non hai fatto nessuna modifica nativa a mano, puoi anche eliminare la cartella ios e aggiungerla al .gitignore: EAS la rigenererà a ogni build. Su Solys, TradaZen e Nolera questa cartella è ignorata da git.

Il formato di iOS 26: Icon Composer

Icon Composer è lo strumento di Apple per le icone Liquid Glass di iOS 26. Produce un unico file .icon a più livelli. Secondo la guida di Apple su Icon Composer, Xcode ne ricava anche le immagini per le versioni di iOS più vecchie.

Expo lo supporta dall'SDK 54. Dichiari la cartella come stringa, mai nell'oggetto delle varianti:

{
  "expo": {
    "ios": {
      "icon": "./assets/app.icon"
    }
  }
}

In questo caso il prebuild copia la cartella senza toccarla, ed è Xcode a creare l'icona finale. Serve quindi Xcode 26 o successivo, quello delle immagini EAS recenti, come spiego nella guida su ITMS-90725.

Da agosto 2025, sul forum degli sviluppatori Apple, alcuni thread segnalano ITMS-90717 con file .icon. Le ipotesi riportate: un livello PNG trasparente, un livello più grande della tela, un gruppo con l'effetto Blur vicino al bordo. I workaround citati: togliere il Blur, tenere uno sfondo pieno o tornare a un PNG. Questi thread non riportano nessuna correzione ufficiale di Apple, e l'errore veniva ancora segnalato ad agosto 2026.

Le regole di Apple sulle icone vanno nella stessa direzione: se importi un livello di sfondo, deve coprire tutta la superficie ed essere opaco. Le mie app usano ancora un PNG, quindi non ho testato Icon Composer in produzione. Se un file .icon blocca il tuo invio, rimetti ios.icon su un PNG: Expo lo appiattirà e la tua icona passerà questo controllo.

Controllare l'icona nel build finale

Nell'IPA l'icona 1024 non è un file PNG: Xcode la compila dentro Assets.car. Scarica l'IPA dalla pagina del build su expo.dev, poi lancia:

unzip -q MyApp.ipa -d ipa
xcrun assetutil --info ipa/Payload/*.app/Assets.car | grep -B3 '"RenditionName" : "App-Icon'

Ogni icona mostra un campo Opaque. Il 15 ottobre 2026 ho compilato con actool, lo strumento di Xcode, l'icona di Solys e la mia icona di prova con gli angoli trasparenti. La prima esce con "Opaque" : true, la seconda con "Opaque" : false. Apple non documenta questo campo: prendilo come un indizio, non come il controllo di Apple.

Una trappola da conoscere: non testare con sips i piccoli PNG messi nella radice dell'app. Xcode li scrive con un canale alfa, anche quando la sorgente è opaca. Nel mio test con l'icona di Solys, sips risponde yes per quei file.

Gli altri errori sulle icone

Codice	Cosa segnala Apple	Pista con Expo
ITMS-90717	Icona 1024 trasparente	Esportare senza alfa
ITMS-90704	Icona 1024 assente	Voce 1024 mancante
ITMS-90022	Icona iPhone assente	Catalogo incompleto
ITMS-90023	Icona iPad assente	Catalogo incompleto

Gli ultimi tre messaggi risalgono soprattutto al 2017 e al 2018, quando Xcode 9 ha cambiato le regole delle icone.

Con Expo sono diventati rari. Il prebuild scrive un'unica icona universale da 1024 e Xcode genera le altre dimensioni. Se non dichiari nessuna icona, Expo crea perfino un quadrato bianco, per evitare un fallimento all'invio. Se ti capita uno di questi errori, guarda la cartella ios versionata: il file Contents.json di AppIcon.appiconset deve contenere una voce di dimensione 1024x1024, e il PNG a cui rimanda deve esistere.

Prima del tuo prossimo invio

Un'icona si sistema in dieci minuti, ma ogni errore ti costa un build. Gli altri controlli automatici richiedono la stessa attenzione, come ITMS-90683 per le frasi di autorizzazione o ITMS-91053 per il privacy manifest. Una volta accettato il build, installalo con TestFlight per vedere la tua icona sulla schermata Home.

I rifiuti di un reviewer richiedono più distacco: il procedimento è nella pagina app rifiutata da Apple, e i motivi più frequenti sono in perché Apple rifiuta un'app.

Per controllare il tuo progetto prima dell'invio, il Review Kit riunisce la mia checklist e delle skill di Claude Code che rileggono il tuo progetto. Se il tuo invio è bloccato e vuoi uno sguardo umano, prenota un'ora con me: riprendiamo il tuo progetto in videochiamata, sul tuo schermo. E se stai preparando la tua prima uscita, fai la tua diagnosi gratuita: rimette in ordine i passaggi e ti manda la mia checklist anti-rifiuto Apple.

Domande frequenti

Perché Apple vede un canale alfa se la mia icona non ha nessuna trasparenza?

Perché un PNG può avere un canale alfa anche quando tutti i suoi pixel sono opachi. Molti strumenti lo aggiungono di default in esportazione. Controlla con sips -g hasAlpha, poi riesporta l'icona senza quel canale.

Si può correggere ITMS-90717 con un aggiornamento da remoto?

No. L'icona è compilata nel binario, dentro Assets.car. Un aggiornamento da remoto cambia solo il JavaScript e le risorse dell'app. Correggi l'icona, rifai il build e rinvialo.

L'icona scura può essere trasparente?

Sì. Apple chiede uno sfondo trasparente per la variante scura, ed Expo ne mantiene la trasparenza. Ne deduco che il controllo riguardi l'icona principale, quella dell'App Store: è lei che deve essere opaca.

Bisogna arrotondare gli angoli dell'icona iOS?

No. Fornisci un quadrato pieno: la maschera la applica iOS. Gli angoli arrotondati lasciano pixel trasparenti negli spigoli, esattamente quello che questo controllo rifiuta.

Expo supporta le icone Icon Composer di iOS 26?

Sì, dall'SDK 54: dichiara il percorso della cartella .icon in ios.icon, come stringa. Il prebuild la copia così com'è e Xcode 26 la compila. In caso di ITMS-90717 con questo formato, controlla i livelli trasparenti e l'effetto Blur, oppure torna temporaneamente a un PNG.