Supporto di diversi APK

Se pubblichi la tua app su Google Play, devi creare e caricare un Android App Bundle. Se lo fai, Google Play genera e pubblica automaticamente APK ottimizzati per la configurazione del dispositivo di ogni utente, in modo che gli utenti scarichino solo il codice e le risorse necessarie per eseguire la tua app. La pubblicazione di più APK è utile se non pubblichi su Google Play, ma devi creare, firmare e gestire personalmente ogni APK.

Il supporto di più APK è una funzionalità di Google Play che ti consente di pubblicare diversi APK per la tua applicazione, ciascuno indirizzato a configurazioni dispositivo diverse. Ogni APK è una versione completa e indipendente della tua applicazione, ma condivide la stessa scheda dell'applicazione su Google Play, deve avere lo stesso nome di pacchetto ed essere firmato con la stessa chiave di release. Questa funzionalità è utile nei casi in cui l'applicazione non possa raggiungere tutti i dispositivi desiderati con un singolo APK.

I dispositivi con piattaforma Android possono differire in diversi modi ed è importante per il successo della tua applicazione renderla disponibile per il maggior numero possibile di dispositivi. Le app Android in genere vengono eseguite sulla maggior parte dei dispositivi compatibili con un singolo APK, fornendo risorse alternative per diverse configurazioni (ad esempio, layout diversi per dimensioni dello schermo diverse) e il sistema Android seleziona le risorse appropriate per il dispositivo in fase di esecuzione. Tuttavia, in alcuni casi un singolo APK non è in grado di supportare tutte le configurazioni dei dispositivi, perché le risorse alternative rendono il file APK troppo grande o altre difficoltà tecniche impediscono il funzionamento di un singolo APK su tutti i dispositivi.

Per aiutarti a pubblicare la tua applicazione per il maggior numero possibile di dispositivi, Google Play ti consente di pubblicare più APK nella stessa scheda dell'applicazione. Google Play fornisce quindi ogni APK ai dispositivi appropriati in base al supporto della configurazione dichiarato nel file manifest di ogni APK.

Se pubblichi la tua app con più APK, puoi:

• Supporta diversi formati di compressione delle texture OpenGL per ogni APK.
• Supporta diverse dimensioni e densità dello schermo con ogni APK.
• Supporta diversi set di funzionalità del dispositivo per ogni APK.
• Supportano versioni di diverse piattaforme con ogni APK.
• Supporta architetture di CPU diverse per ogni APK (ad esempio ARM o x86, quando la tua app utilizza l'NDK Android).
• Ottimizza per i dispositivi di livello base come quelli con Android Go.

Attualmente, queste sono le uniche caratteristiche del dispositivo che Google Play supporta per la pubblicazione di più APK per la stessa applicazione.

Nota:per ulteriori informazioni su come preparare e pubblicare APK su Google Play, consulta l'articolo di assistenza Preparare e implementare le release.

Come funzionano più APK

L'utilizzo di più APK su Google Play prevede che sia disponibile una sola voce per l'applicazione in Google Play, ma dispositivi diversi potrebbero scaricare un APK diverso. Ciò significa che:

• Puoi gestire un solo insieme di dettagli del prodotto (descrizione dell'app, icone, screenshot e così via). Ciò significa anche che non puoi applicare un prezzo diverso per APK diversi.
• Tutti gli utenti vedono solo una versione della tua applicazione su Google Play, pertanto non sono confusi dalle diverse versioni che potresti aver pubblicato, "per tablet" o "per telefoni".
• Tutte le recensioni degli utenti vengono applicate alla stessa scheda dell'applicazione, anche se gli utenti su dispositivi diversi potrebbero avere APK diversi.
• Se pubblichi APK diversi per versioni diverse di Android (per livelli API diversi), quando il dispositivo di un utente riceve un aggiornamento di sistema che lo rende idoneo per un altro APK che hai pubblicato, Google Play aggiorna l'applicazione dell'utente all'APK progettato per la versione superiore di Android. Tutti i dati di sistema associati all'applicazione vengono conservati (come per i normali aggiornamenti dell'applicazione quando si utilizza un singolo APK).

Filtri supportati

I dispositivi che riceveranno ciascun APK dipendono dai filtri di Google Play specificati dagli elementi nel file manifest di ogni APK. Tuttavia, Google Play ti consente di pubblicare più APK solo quando ogni APK utilizza filtri per supportare una variante delle seguenti caratteristiche del dispositivo:

• Formati di compressione delle texture OpenID

  Il valore è basato sugli elementi <supports-gl-texture> del file manifest.

  Ad esempio, durante lo sviluppo di un gioco che utilizza OpenGL ES, puoi fornire un APK per i dispositivi che supportano la compressione delle texture ATI e un APK separato per i dispositivi che supportano la compressione PowerVR (tra molti altri).

• Dimensioni dello schermo (e, facoltativamente, densità dello schermo)

  Questo valore è basato sull'elemento <supports-screens> o <compatible-screens> del file manifest. Non devi mai utilizzare entrambi gli elementi e devi usare solo <supports-screens> quando possibile.

  Ad esempio, puoi fornire un APK che supporta schermi di piccole dimensioni e di dimensioni normali e un altro APK che supporta schermi di grandi dimensioni e xlarge. Per scoprire di più sulla generazione di APK separati in base alle dimensioni o alla densità dello schermo, consulta l'articolo Creare più APK.

  Tieni in considerazione le seguenti best practice per supportare schermi di tutte le dimensioni:

  • Il sistema Android fornisce un solido supporto per le applicazioni per il supporto di tutte le configurazioni dello schermo con un singolo APK. Dovresti evitare di creare più APK per supportare schermi diversi, a meno che non sia assolutamente necessario, e seguire invece la guida al supporto di più schermi, in modo che la tua applicazione sia flessibile e possa adattarsi a tutte le configurazioni dello schermo con un singolo APK.
  • Per impostazione predefinita, tutti gli attributi relativi alle dimensioni dello schermo nell'elemento <supports-screens> sono "true" se non li dichiari in altro modo. Tuttavia, poiché l'attributo android:xlargeScreens è stato aggiunto in Android 2.3 (livello API 9), Google Play presumerà che sia "false" se per l'applicazione non viene impostato android:minSdkVersion o android:targetSdkVersion su "9" o versioni successive.
  • Non devi combinare entrambi gli elementi <supports-screens> e <compatible-screens> nel file manifest. L'utilizzo di entrambi aumenta le possibilità di introdurre un errore a causa di conflitti tra loro. Per informazioni su come scegliere, leggi l'articolo Distribuzione a schermate specifiche. Se non puoi evitare di utilizzare entrambi, tieni presente che in caso di conflitti nell'accordo tra una determinata dimensione, prevale il valore "false".
• Set di funzionalità del dispositivo

  Il valore si basa sugli elementi <uses-feature> del tuo file manifest.

  Ad esempio, puoi fornire un APK per i dispositivi che supportano il multitouch e un altro APK per i dispositivi che non lo supportano. Consulta il riferimento sulle funzionalità per un elenco delle funzionalità supportate dalla piattaforma.

• Android Go

  Per scegliere come target dispositivi con Android Go, l'APK deve dichiarare <uses-feature android:name="android.hardware.ram.low" android:required="true">, scegliere come target almeno il livello API 26 e avere un codice versione superiore rispetto all'APK della versione non Go.

• Livello API

  Questo valore si basa sull'elemento <uses-sdk> del file manifest. Puoi utilizzare entrambi gli attributi android:minSdkVersion e android:maxSdkVersion per specificare il supporto di diversi livelli API.

  Ad esempio, puoi pubblicare la tua applicazione con un APK che supporta i livelli API 16-19 (Android 4.1.x-4.4.4), utilizzando solo le API disponibili a partire dal livello API 16 o precedente, e un altro APK che supporta i livelli API 21 e successivi (Android 5.0 e versioni successive), utilizzando le API disponibili a partire dal livello API 21 o precedente. Per scoprire come creare APK separati che hanno come target una gamma diversa di API, vai a Configurare i gusti dei prodotti.

  Se utilizzi questa caratteristica come fattore per distinguere più APK, l'APK con un valore android:minSdkVersion più elevato deve avere un valore android:versionCode più alto. Questo vale anche se due APK si sovrappongono al supporto dei dispositivi in base a un altro filtro supportato. In questo modo, quando un dispositivo riceve un aggiornamento di sistema, Google Play può offrire all'utente un aggiornamento per la tua applicazione (perché gli aggiornamenti sono basati su un aumento del codice versione dell'app). Questo requisito è descritto ulteriormente nella sezione che segue sulle regole per più APK.

  In generale, dovresti evitare di utilizzare android:maxSdkVersion poiché, se hai sviluppato correttamente la tua applicazione con API pubbliche, questa sarà sempre compatibile con le versioni future di Android. Se vuoi pubblicare un APK diverso per livelli API superiori, non devi comunque specificare la versione massima perché, se android:minSdkVersion è "16" in un APK e "21" in un altro, i dispositivi che supportano il livello API 21 o successivo riceveranno sempre il secondo APK (perché il suo codice di versione è superiore, come indicato nella nota precedente).



• Architettura CPU (ABI)

  Alcune librerie native forniscono pacchetti separati per architetture CPU specifiche, o Application Binary Interfaces (ABI). Anziché pacchettizzare tutte le librerie disponibili in un unico APK, puoi creare un APK separato per ogni ABI e includere solo le librerie necessarie per quell'ABI. Per scoprire di più sulla generazione di APK separati in base all'ABI di destinazione, consulta l'articolo Creare più APK.

Gli altri elementi del file manifest che attivano i filtri di Google Play, ma non elencati sopra, vengono comunque applicati a ogni APK come di consueto. Tuttavia, Google Play non consente di pubblicare APK separati in base alle varianti di queste caratteristiche del dispositivo. Di conseguenza, non puoi pubblicare più APK se i filtri elencati in precedenza sono gli stessi per ogni APK (ma gli APK differiscono in base ad altre caratteristiche nel file manifest o APK). Ad esempio, non puoi fornire APK diversi che differiscono esclusivamente per le caratteristiche di <uses-configuration>.

Regole per più APK

Prima di pubblicare più APK per la tua applicazione, devi comprendere le seguenti regole:

• Tutti gli APK pubblicati per la stessa applicazione devono avere lo stesso nome di pacchetto ed essere firmati con la stessa chiave di certificato.
• Ogni APK deve avere un codice di versione diverso, specificato dall'attributo android:versionCode.
• Ogni APK non deve corrispondere esattamente al supporto della configurazione di un altro APK.

  In altre parole, ogni APK deve dichiarare un supporto leggermente diverso per almeno uno dei filtri supportati di Google Play (elencati in precedenza).

  In genere, gli APK si differenziano in base a una caratteristica specifica (ad esempio i formati di compressione delle texture supportati). Pertanto, ogni APK dichiarerà il supporto per dispositivi diversi. Tuttavia, puoi pubblicare più APK che si sovrappongono leggermente al relativo supporto. Quando due APK si sovrappongono (supportano alcune delle stesse configurazioni dispositivo), un dispositivo che rientra nell'intervallo di sovrapposizione riceverà l'APK con un codice versione più recente (definito da android:versionCode).

• Non puoi attivare un nuovo APK con un codice di versione inferiore a quello dell'APK che viene sostituito. Ad esempio, supponiamo che tu abbia un APK attivo per schermi di dimensioni ridotte (normale) con codice di versione 0400, quindi prova a sostituirlo con un APK per le stesse dimensioni dello schermo con il codice di versione 0300. Questo genera un errore, perché significa che gli utenti dell'APK precedente non potranno aggiornare l'applicazione.
• Un APK che richiede un livello API superiore deve avere un codice di versione superiore.

  Questo vale solo nei seguenti casi: gli APK differiscono solo in base ai livelli API supportati (non ci sono altri filtri supportati che distinguono gli APK l'uno dall'altro) oppure quando gli APK utilizzano un altro filtro supportato, ma esiste una sovrapposizione tra gli APK all'interno di quel filtro.

  Questo è importante perché il dispositivo di un utente riceve un aggiornamento dell'applicazione da Google Play soltanto se il codice di versione dell'APK su Google Play è successivo al codice di versione dell'APK attualmente sul dispositivo. In questo modo, se un dispositivo riceve un aggiornamento di sistema che lo rende idoneo all'installazione dell'APK per livelli API superiori, riceva un aggiornamento dell'applicazione perché il codice di versione aumenta.

  Nota: la dimensione dell'aumento del codice versione non è pertinente; deve semplicemente essere superiore nella versione che supporta livelli API più elevati.

  Ecco alcuni esempi:

  • Se un APK che hai caricato per i livelli API 16 e successivi (Android 4.1.x e versioni successive) ha un codice di versione 0400, un APK per i livelli API 21 e successivi (Android 5.0 e versioni successive) deve essere 0401 o superiore. In questo caso, il livello API è l'unico filtro supportato utilizzato, pertanto i codici di versione devono aumentare in correlazione con il supporto del livello API per ogni APK, in modo che gli utenti ricevano un aggiornamento quando ricevono un aggiornamento di sistema.
  • Se hai un APK per il livello API 16 (e versioni successive) e per schermi di piccole dimensioni e grandi e un altro APK per gli schermi di livello API 21 e versioni successive e per schermi grandi - xlarge, i codici di versione devono aumentare in relazione ai livelli API. In questo caso, per distinguere ogni APK viene utilizzato il filtro a livello di API, così come le dimensioni dello schermo. Poiché le dimensioni degli schermi si sovrappongono (entrambi gli APK supportano schermi di grandi dimensioni), i codici di versione devono essere ancora in ordine. In questo modo, un dispositivo con schermi di grandi dimensioni che riceve un aggiornamento di sistema al livello API 21 riceverà un aggiornamento per il secondo APK.
  • Se disponi di un APK per il livello API 16 (e versioni successive) e di schermi normali di piccole dimensioni e un altro APK per schermi di livello API 21 e versioni successive e per schermi di livello API xlarge, i codici di versione non devono aumentare in relazione ai livelli API. Poiché non esiste una sovrapposizione all'interno del filtro delle dimensioni dello schermo, non ci sono dispositivi che potrebbero potenzialmente spostarsi tra questi due APK, quindi non è necessario che i codici di versione passino dal livello API inferiore a quello superiore.
  • Se hai un APK per le CPU di livello API 16 (e versioni successive) e CPU ARMv7 e un altro APK per le CPU di livello API 21 e successivi e ARMv5TE, i codici di versione devono aumentare in relazione ai livelli API. In questo caso, per distinguere ogni APK viene utilizzato il filtro a livello di API, così come l'architettura della CPU. Poiché un APK con librerie ARMv5TE è compatibile con dispositivi dotati di CPU ARMv7, gli APK si sovrappongono a questa caratteristica. Di conseguenza, il codice di versione dell'APK che supporta il livello API 21 e versioni successive deve essere superiore. In questo modo, un dispositivo con una CPU ARMv7 che riceve un aggiornamento di sistema al livello API 21 riceverà un aggiornamento per il secondo APK progettato per il livello API 21. Tuttavia, poiché questo tipo di aggiornamento fa sì che il dispositivo ARMv7 utilizzi un APK non completamente ottimizzato per la CPU del dispositivo, devi fornire un APK sia per l'architettura ARMv5TE che per l'architettura ARMv7 a ogni livello API al fine di ottimizzare le prestazioni dell'app su ogni CPU. Nota: questo vale solo per il confronto di APK con le librerie ARMv5TE e ARMv7, non per il confronto con altre librerie native.

Se le regole non vengono rispettate, viene visualizzato un errore in Google Play Console al momento dell'attivazione degli APK. Non potrai pubblicare l'applicazione finché non avrai risolto l'errore.

Potrebbero verificarsi altri conflitti che potrebbero verificarsi quando attivi gli APK, ma che genereranno avvisi anziché errori. Gli avvisi possono essere causati da:

• Quando modifichi un APK per "restringere" il supporto delle caratteristiche di un dispositivo e nessun altro APK supporta i dispositivi che non rientrano nell'intervallo supportato. Ad esempio, se al momento un APK supporta schermi di piccole dimensioni e di dimensioni normali e decidi di farlo in modo che supporti solo schermi di piccole dimensioni, hai ridotto il pool di dispositivi supportati e alcuni dispositivi non vedranno più la tua applicazione su Google Play. Per risolvere il problema, aggiungi un altro APK che supporta schermi di dimensioni normali, in modo che tutti i dispositivi supportati in precedenza siano ancora supportati.
• Quando sono presenti "sovrapposizioni" tra due o più APK. Ad esempio, se un APK supporta schermi di dimensioni ridotte, normali e grandi, mentre un altro APK supporta dimensioni di grandi dimensioni e xlarge, viene applicata una sovrapposizione, poiché entrambi gli APK supportano schermi di grandi dimensioni. Se non risolvi il problema, i dispositivi idonei per entrambi gli APK (nell'esempio i dispositivi con schermi grandi) riceveranno l'APK con il codice di versione più elevato.

  Nota: se crei APK separati per architetture CPU diverse, tieni presente che un APK per ARMv5TE si sovrapporrà a un APK per ARMv7. In altre parole, un APK progettato per ARMv5TE è compatibile con un dispositivo ARMv7, ma il contrario non è vero (un APK con solo le librerie ARMv7 non è compatibile con un dispositivo ARMv5TE).

Quando si verificano questi conflitti, viene visualizzato un messaggio di avviso, ma puoi comunque pubblicare l'applicazione.

Creazione di più APK

Dopo avere deciso di pubblicare più APK, probabilmente dovrai creare progetti Android separati per ogni APK che intendi pubblicare, in modo da poterli sviluppare separatamente in modo appropriato. Puoi farlo semplicemente duplicando il progetto esistente e assegnandogli un nuovo nome. In alternativa, puoi utilizzare un sistema di compilazione in grado di generare risorse diverse, ad esempio texture, in base alla configurazione della build.

Suggerimento: un modo per evitare la duplicazione di grandi porzioni del codice dell'applicazione è utilizzare un progetto di libreria. Un progetto di libreria contiene risorse e codice condivisi, che puoi includere nei progetti di applicazioni reali.

Quando crei più progetti per la stessa applicazione, è buona norma identificare ognuno di essi con un nome che indichi le limitazioni relative ai dispositivi da applicare all'APK, in modo da poterle identificare facilmente. Ad esempio, "HelloWorld_21" potrebbe essere un nome appropriato per un'applicazione progettata per il livello API 21 e versioni successive.

Nota: tutti gli APK che pubblichi per la stessa applicazione devono avere lo stesso nome di pacchetto ed essere firmati con la stessa chiave di certificato. Assicurati di comprendere anche ciascuna delle regole per più APK.

Assegnazione dei codici di versione

Ogni APK per la stessa applicazione deve avere un codice di versione univoco, specificato dall'attributo android:versionCode. Devi prestare attenzione all'assegnazione dei codici di versione quando pubblichi più APK, perché ognuno deve essere diverso ma, in alcuni casi, deve o deve essere definito in un ordine specifico, in base alle configurazioni supportate da ogni APK.

Ordine dei codici versione

Un APK che richiede un livello API superiore deve in genere avere un codice versione superiore. Ad esempio, se crei due APK per supportare livelli API diversi, l'APK dei livelli API superiori deve avere il codice versione superiore. In questo modo, se un dispositivo riceve un aggiornamento di sistema che lo rende idoneo all'installazione dell'APK per livelli API superiori, l'utente riceva una notifica che invita l'utente ad aggiornare l'app. Per ulteriori informazioni sull'applicazione di questo requisito, consulta la sezione precedente sulle regole per più APK.

Dovresti anche valutare in che modo l'ordine dei codici di versione potrebbe influire sugli APK ricevuti dagli utenti a causa della sovrapposizione tra la copertura di diversi APK o che potresti apportare modifiche future agli APK.

Ad esempio, se hai APK diversi in base alle dimensioni dello schermo, ad esempio uno per l'APK piccolo - normale e uno per l'APK grande - xlarge, ma prevedi un momento in cui cambierai gli APK in uno per gli APK piccoli e uno per gli APK normali - xlarge, dovresti aumentare il codice di versione per l'APK grande - xlarge. In questo modo, un dispositivo di dimensioni normali riceverà l'aggiornamento appropriato quando apporti la modifica, perché il codice di versione aumenta dall'APK esistente al nuovo APK che ora supporta il dispositivo.

Inoltre, quando crei più APK che differiscono in base al supporto di diversi formati di compressione delle texture OpenGL, tieni presente che molti dispositivi supportano diversi formati. Poiché un dispositivo riceve l'APK con il codice di versione più elevato quando c'è una sovrapposizione di copertura tra due APK, devi ordinare i codici di versione tra gli APK in modo che l'APK con il formato di compressione preferito abbia il codice di versione più elevato. Ad esempio, potresti voler eseguire build separate per la tua app utilizzando i formati di compressione PVRTC, ATITC ed ETC1. Se preferisci questi formati nell'ordine esatto, l'APK che utilizza PVRTC dovrebbe avere il codice di versione più recente, l'APK che utilizza ATITC ha un codice di versione inferiore e la versione con ETC1 ha il codice più basso. Pertanto, se un dispositivo supporta sia PVRTC che ETC1, riceve l'APK con PVRTC, perché ha il codice di versione più elevato.

Nel caso in cui Google Play Store non riesca a identificare l'APK corretto da installare per un dispositivo di destinazione, potresti voler creare anche un APK universale che includa risorse per tutte le diverse varianti dei dispositivi che vuoi supportare. Se invece fornisci un APK universale, dovresti assegnargli il valore versionCode più basso. Poiché Google Play Store installa la versione della tua app che è compatibile con il dispositivo di destinazione e ha il valore versionCode più elevato, l'assegnazione di un valore versionCode inferiore all'APK universale garantisce che il Google Play Store provi a installare uno degli altri APK prima di ricorrere all'APK universale più grande.

Utilizzo di uno schema di codice di versione

Per consentire a diversi APK di aggiornare i rispettivi codici di versione indipendentemente da altri (ad esempio, quando correggi un bug in un solo APK, quindi non devi aggiornare tutti gli APK), devi utilizzare uno schema per i codici di versione che preveda spazio sufficiente tra un APK e l'altro, in modo da poter aumentare il codice in uno solo senza richiedere un aumento degli altri. Devi anche includere nel codice il nome effettivo della versione (ovvero la versione visibile all'utente assegnata a android:versionName), in modo da poter associare facilmente il codice e il nome di versione.

Nota: quando aumenti il codice di versione di un APK, Google Play chiede agli utenti della versione precedente di aggiornare l'applicazione. Di conseguenza, per evitare aggiornamenti non necessari, non dovresti aumentare il codice di versione per gli APK che non includono effettivamente le modifiche.

Ti consigliamo di utilizzare un codice di versione di almeno sette cifre: i numeri interi che rappresentano le configurazioni supportate sono composti dai bit di ordine più elevato e il nome della versione (da android:versionName) è composto dai bit di ordine inferiore. Ad esempio, quando il nome di versione dell'applicazione è 3.1.0, i codici di versione per un APK di livello API 4 e un APK di livello API 11 sarebbero rispettivamente 0400310 e 1100310. Le prime due cifre sono riservate al livello API (rispettivamente 4 e 11), le due cifre centrali indicano le dimensioni dello schermo o i formati di texture GL (non utilizzati in questi esempi) e le ultime tre cifre riguardano il nome della versione dell'applicazione (3.1.0). La Figura 1 mostra due esempi suddivisi in base alla versione della piattaforma (livello API) e alle dimensioni dello schermo.

Figura 1. Uno schema suggerito per i codici di versione, utilizzando le prime due cifre per il livello API, la seconda e la terza cifra per le dimensioni minime e massime dello schermo (da 1 a 4 per ciascuna delle quattro dimensioni) o per indicare i formati delle texture e le ultime tre cifre per la versione dell'app.

Questo schema per i codici di versione è solo un suggerimento su come stabilire un pattern scalabile man mano che l'applicazione si evolve. In particolare, questo schema non dimostra una soluzione per identificare diversi formati di compressione delle texture. Un'opzione potrebbe essere definire una tabella personalizzata che specifichi un numero intero diverso per ciascuno dei diversi formati di compressione supportati dall'applicazione (ad esempio, 1 potrebbe corrispondere a ETC1 e 2 è ATITC e così via).

Puoi utilizzare lo schema che preferisci, ma devi valutare attentamente in che modo le versioni future della tua applicazione dovranno aumentare i codici di versione e in che modo i dispositivi possono ricevere aggiornamenti quando la configurazione del dispositivo cambia (ad esempio a causa di un aggiornamento di sistema) o quando modifichi il supporto della configurazione per uno o più APK.