Aggiornare la scheda Play Store con la Google Play Developer API
edits.insert), modifichi testi e immagini della scheda al suo interno (edits.listings.update, edits.images.upload), poi esegui edits.commit per validare e pubblicare — oppure edits.abandon per annullare tutto. Niente va online prima del commit. L'autenticazione avviene tramite un service account di Google Cloud, e il passaggio in cui quasi tutti inciampano: il service account va invitato in Play Console, non basta assegnargli un ruolo in Google Cloud IAM.La Google Play Developer API (il nome ufficiale è Android Publisher API) permette di modificare una scheda store — titolo, descrizioni, screenshot, feature graphic — senza aprire Play Console. È quello che ti serve se pubblichi testi localizzati da un CMS, sincronizzi screenshot da una pipeline di build, o aggiorni decine di schede in altre lingue tutte insieme. Ecco il flusso completo per farlo correttamente, comprese le parti che la documentazione ufficiale nasconde bene.
Una edit è una transazione, non un insieme di scritture live
Il modello mentale che ti risparmia più grattacapi: non modifichi mai direttamente la scheda live. Apri una edit, che è una copia privata di staging dello stato attualmente pubblicato dell'app — schede, immagini, track, tutto viene copiato dentro. Fai tutte le modifiche su quella copia. Poi fai il commit di tutto insieme, oppure abbandoni e non è successo nulla.
Le parole di Google sono chiare: "Changes made within an edit are not live until the edit is committed." Al commit, se non ci sono errori di validazione, tutte le modifiche della edit vengono pubblicate insieme, sostituendo lo stato attuale. Se la validazione fallisce, l'API restituisce un errore e la scheda live resta invariata. Il ciclo di vita è quindi esattamente quattro mosse:
edits.insert— crea la edit, ottieni uneditId.- modifica —
edits.listings.updateper il testo per ogni lingua,edits.images.upload/deleteallper screenshot e grafiche. edits.commit— valida tutto, poi pubblica in modo atomico.edits.abandon— scarta la bozza, la scheda live resta invariata.
Un vincolo rigido da tenere presente nella progettazione: un account può avere una sola edit aperta alla volta, e se qualcuno esegue il commit di una edit o modifica l'app tramite l'interfaccia di Play Console, ogni altra edit aperta per quell'app viene invalidata. Tratta una edit come qualcosa di effimero — aprila, scrivici, fai il commit. Non tenerla aperta per ore mentre un umano clicca in giro nella console.
Autenticazione: un service account, più l'invito che tutti dimenticano
Per un aggiornamento automatizzato ti serve un service account, non l'OAuth utente. Sono coinvolti due sistemi, e sono davvero separati:
- Google Cloud. Crea un service account, abilita la Google Play Android Developer API sul progetto e scarica una chiave JSON. L'unico scope necessario è
https://www.googleapis.com/auth/androidpublisher. - Play Console. Vai su Utenti e autorizzazioni, clicca su Invita nuovi utenti, incolla l'email del service account (l'indirizzo
...@...iam.gserviceaccount.com) e concedigli l'accesso all'app. Solo a quel punto quella chiave potrà toccare la tua scheda.
Un'altra precondizione: l'app deve già esistere e avere almeno una release (almeno un APK/AAB caricato tramite la console). Non puoi far partire da zero un'app nuova solo tramite API.
Le quattro chiamate, in REST
Aggiornare il testo della scheda
edits.listings.update è una PUT — una sostituzione completa della scheda per quella lingua. Qualsiasi cosa invii diventa la scheda; i campi che ometti vengono cancellati, non conservati. Quindi se vuoi cambiare solo la descrizione breve, devi comunque inviare anche titolo e descrizione completa insieme, altrimenti li cancelli. Quando vuoi davvero fare una modifica parziale, esiste un edits.listings.patch separato che unisce solo i campi che fornisci. Per la maggior parte delle pipeline la PUT completa è più pulita — stai comunque generando la scheda completa dalla tua fonte di verità, quindi sostituirla in blocco è la scelta giusta.
I tre campi di testo e i loro limiti: title fino a 30 caratteri, shortDescription fino a 80, fullDescription fino a 4000. Una risorsa listing per ogni lingua, indicizzata dal tag BCP-47 nell'URL (en-US, de-DE, ja-JP, e così via). Per aggiornare dieci lingue fai dieci chiamate listings.update all'interno della stessa edit — poi un solo commit le pubblica tutte insieme.
Caricare screenshot e feature graphic
Le immagini vengono associate per lingua e per tipo di immagine. Il tipo di immagine è un enum, e ogni slot di asset nella scheda corrisponde a uno di questi valori:
phoneScreenshots,sevenInchScreenshots,tenInchScreenshots— i set di screenshot per telefono e tablet.tvScreenshots,wearScreenshots— Android TV e Wear OS.featureGraphic— il banner 1024×500 mostrato in cima alla scheda.icon,tvBanner— l'icona dell'app e il banner TV.
edits.images.upload aggiunge un'immagine di una data lingua e tipo alla edit. Non esiste una chiamata "imposta l'intero array", quindi il pattern affidabile per sostituire gli screenshot è chiamare prima edits.images.deleteall per quella lingua e quel tipo di immagine, poi caricare il nuovo set nell'ordine in cui vuoi che venga mostrato. edits.images.list legge cosa c'è attualmente nella edit, e edits.images.delete rimuove una singola immagine per id se ti servono modifiche chirurgiche. Tutto resta dentro la edit finché non fai il commit.
Il commit — e cosa significa davvero "live"
Alcune cose su cui vale la pena essere precisi, perché sorprendono spesso:
- Non serve una nuova build. Fare il commit di una edit solo testi/immagini non richiede un nuovo APK/AAB. Testo e immagini sono metadati; puoi aggiornarli quante volte vuoi contro la release esistente. (L'app deve solo avere già quella release precedente.)
- Il commit valida, poi pubblica. Se uno screenshot ha dimensioni sbagliate o un campo è troppo lungo, il commit fallisce e la scheda live non cambia mai — correggi e rifai il commit.
- Non è istantaneo. Dopo un commit riuscito, le modifiche possono richiedere fino a diverse ore per apparire, esattamente come per le modifiche fatte a mano in Play Console. Non trattare un 200 sul commit come "già visibile agli utenti".
- Abbandonare non costa nulla. Se un test a secco sembra sbagliato,
edits.abandonscarta la bozza senza alcun effetto sulla scheda live. Utile per validare una pipeline senza rischi.
La via senza codice: progetta, traduci, pubblica
L'API descritta sopra è lo strumento giusto se hai tempo ingegneristico da dedicarci e una fonte di verità da sincronizzare. Quello che non fa è creare gli asset. Devi comunque progettare gli screenshot, scrivere il titolo e le due descrizioni, e produrre tutto questo per ogni lingua — l'API pubblica solo ciò che le fornisci.
È questa la parte di cui si occupa Mokbi. Progetti gli screenshot nel browser, scrivi la bozza di titolo, descrizione breve e descrizione completa insieme a essi, e traduci l'intera scheda in 50 lingue in un solo passaggio — così le dieci chiamate listings.update di prima hanno testi localizzati e reali da inviare, non testo segnaposto.
E la pubblicazione vera e propria? Se ne occupa Mokbi. Per Google Play esegue esattamente questo flusso sotto il cofano (edits.insert → listings.update → caricamento immagini → commit), così la tua scheda localizzata e i tuoi asset vanno online senza che tu scriva una riga del codice qui sopra. Per l'App Store prepara la versione in App Store Connect, compilata e pronta per l'invio, poiché Apple richiede che sia tu a premere il Submit finale e a superare la revisione. Progettare screenshot e feature graphic, scrivere la scheda, tradurla in 50 lingue e pubblicarla sono un unico passaggio continuo.