Supporto di diversi APK

Se pubblichi la tua app su Google Play, devi creare e caricare un Android App Bundle. In questo modo, Google Play genera e pubblica automaticamente APK ottimizzati per la configurazione del dispositivo di ogni utente, in modo che scarichi solo il codice e le risorse di cui ha bisogno per eseguire la tua app. La pubblicazione di più APK è utile se non pubblichi su Google Play, ma devi creare, firmare e gestire ogni APK autonomamente.

Il supporto di più APK è una funzionalità di Google Play che ti consente di pubblicare APK diversi per la tua applicazione, ciascuno destinato a configurazioni di dispositivi diverse. Ogni APK è una versione completa e indipendente della tua applicazione, ma condividono la stessa scheda dell'applicazione su Google Play e devono condividere lo stesso nome del pacchetto e essere firmati con la stessa chiave di release. Questa funzionalità è utile nei casi in cui l'applicazione non può raggiungere tutti i dispositivi desiderati con un unico APK.

I dispositivi Android possono differire in diversi modi ed è importante per il successo della tua applicazione renderla disponibile per il maggior numero possibile di dispositivi. Le applicazioni Android di solito vengono eseguite sulla maggior parte dei dispositivi compatibili con un singolo APK, fornendo risorse alternative per configurazioni diverse (ad esempio layout diversi per dimensioni dello schermo diverse) e il sistema Android seleziona le risorse appropriate per il dispositivo in fase di esecuzione. In alcuni casi, tuttavia, un singolo APK non è in grado di supportare tutte le configurazioni dei dispositivi perché le risorse alternative rendono il file APK troppo grande o altri problemi tecnici impediscono a un singolo APK di funzionare 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 applicazione con più APK, puoi:

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

Al momento, queste sono le uniche caratteristiche del dispositivo supportate da Google Play per la pubblicazione di più APK come stessa applicazione.

Nota:per scoprire come preparare e pubblicare gli APK su Google Play, consulta l'articolo dell'assistenza Preparare e implementare le release.

Come funzionano più APK

Il concetto alla base dell'utilizzo di più APK su Google Play è che hai una sola voce in Google Play per la tua applicazione, ma dispositivi diversi potrebbero scaricare un APK diverso. Ciò significa che:

• Gestisci un solo insieme di dettagli del prodotto (descrizione dell'app, icone, screenshot e così via). Ciò significa anche che non puoi addebitare un prezzo diverso per APK diversi.
• Tutti gli utenti vedono una sola versione della tua applicazione su Google Play, quindi non vengono confusi dalle diverse versioni che potresti aver pubblicato, ad esempio "per tablet" o "per smartphone".
• Tutte le recensioni degli utenti vengono applicate alla stessa scheda dell'applicazione, anche se gli utenti su dispositivi diversi possono 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 APK diverso che hai pubblicato, Google Play aggiorna l'applicazione dell'utente all'APK progettato per la versione più recente 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 ricevono ogni APK sono determinati dai filtri di Google Play specificati dagli elementi nel file manifest di ogni APK. Tuttavia, Google Play ti consente di pubblicare più APK solo se ogni APK utilizza filtri per supportare una variante delle seguenti caratteristiche del dispositivo:

• Formati di compressione delle texture OpenGL

  Questo valore si basa sugli elementi <supports-gl-texture> del file manifest.

  Ad esempio, quando sviluppi 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 (e molti altri).

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

  Questo valore si basa sull'elemento <supports-screens> o <compatible-screens>. Non devi mai utilizzare entrambi gli elementi e, se possibile, devi utilizzare solo <supports-screens>.

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

  Prendi in considerazione le seguenti best practice per supportare tutti i formati dello schermo:

  • Il sistema Android offre un'assistenza efficace per le applicazioni che supportano tutte le configurazioni dello schermo con un unico APK. Evita di creare più APK per supportare schermi diversi, a meno che non sia assolutamente necessario. Segui invece la guida al supporto di più screen per rendere la tua applicazione flessibile e adattabile a tutte le configurazioni dello schermo con un solo APK.
  • Per impostazione predefinita, tutti gli attributi relativi alle dimensioni dello schermo nell'elemento <supports-screens> sono "true" se non li dichiari diversamente. Tuttavia, poiché l'attributo android:xlargeScreens è stato aggiunto in Android 2.3 (livello API 9), Google Play presume che sia "false" se la tua applicazione non imposta android:minSdkVersion o android:targetSdkVersion su "9" o versioni successive.
  • Non devi combinare gli elementi <supports-screens> e <compatible-screens> nel file manifest. Se li utilizzi entrambi, aumenti le probabilità di introdurre un errore a causa di conflitti tra loro. Per decidere quale utilizzare, consulta Distribuzione su schermate specifiche. Se non puoi evitare di utilizzare entrambi, tieni presente che per eventuali conflitti di accordo tra una determinata dimensione, avrà la precedenza "false".

• Set di funzionalità del dispositivo

  Questo valore si basa sugli elementi <uses-feature> del 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 la documentazione di riferimento sulle funzionalità per un elenco delle funzionalità supportate dalla piattaforma.

• Android (versione Go)

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

• Livello API

  Questo valore si basa sull'elemento <uses-sdk> del file manifest. Puoi utilizzare sia gli attributi android:minSdkVersion che android:maxSdkVersion per specificare il supporto di diversi livelli di 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 dal livello API 16 o precedente e un altro APK che supporta i livelli API 21 e superiori (Android 5.0 e versioni successive) utilizzando le API disponibili dal livello API 21 o precedente. Per scoprire come creare APK distinti ciascuno con un target diverso per una gamma di API, vai a Configurare i flavor dei prodotti.

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

  In generale, dovresti evitare di utilizzare android:maxSdkVersion, perché se hai sviluppato correttamente la tua applicazione con API pubbliche, 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 il valore di android:minSdkVersion è "16" in un APK e "21" in un altro, i dispositivi che supportano il livello API 21 o superiore riceveranno sempre il secondo APK (in quanto il suo codice di versione è superiore, come indicato nella nota precedente).



• Architettura della CPU (ABI)

  Alcune librerie native forniscono pacchetti separati per architetture CPU o interfacce ABI (Application Binary Interface) specifiche. Invece di 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, vai a Creare più APK.

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

Regole per più APK

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

• Tutti gli APK che pubblichi per la stessa applicazione devono avere lo stesso nome di pacchetto e essere firmati con la stessa chiave del certificato.
• Ogni APK deve avere un codice 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 di Google Play supportati (elencati sopra).

  Di solito, dovresti differenziare gli APK in base a una caratteristica specifica (ad esempio i formati di compressione delle texture supportati) e, di conseguenza, ogni APK dichiarerà il supporto per dispositivi diversi. Tuttavia, è consentito pubblicare più APK con un supporto leggermente sovrapposto. Quando due APK si sovrappongono (supportano alcune delle stesse configurazioni del dispositivo), un dispositivo che rientra nell'intervallo di sovrapposizione riceverà l'APK con un codice versione più alto (definito da android:versionCode).

• Non puoi attivare un nuovo APK con un codice di versione inferiore a quello dell'APK che sta sostituendo. Ad esempio, supponiamo che tu abbia un APK attivo per dimensioni dello schermo piccole - normali con codice di versione 0400 e che tu tenti di sostituirlo con un APK per le stesse dimensioni dello schermo con codice di versione 0300. Viene generato un errore perché 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 è vero solo se: gli APK differiscono solo in base ai livelli API supportati (nessun altro filtro supportato distingue gli APK tra loro) o se gli APK utilizzano un altro filtro supportato, ma c'è 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 solo se il codice di versione dell'APK su Google Play è superiore al codice di versione dell'APK attualmente sul dispositivo. In questo modo, se un dispositivo riceve un aggiornamento di sistema che lo rende idoneo per l'installazione dell'APK per livelli API superiori, riceve un aggiornamento dell'applicazione perché il codice di versione aumenta.

  Nota: le dimensioni dell'aumento del codice di versione sono irrilevanti; deve essere semplicemente più grande nella versione che supporta livelli API più elevati.

  Ecco alcuni esempi:

  • Se un APK che hai caricato per i livelli API 16 e versioni successive (Android 4.1.x e versioni successive) ha un codice di versione 0400, un APK per i livelli API 21 e versioni successive (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 schermi piccoli-grandi e un altro APK per il livello API 21 (e versioni successive) e schermi grandi-molto grandi, i codici di versione devono aumentare in correlazione con i livelli API. In questo caso, il filtro a livello di API viene utilizzato per distinguere ogni APK, così come le dimensioni dello schermo. Poiché le dimensioni dello schermo 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 schermo grande che riceve un aggiornamento di sistema al livello API 21 riceverà un aggiornamento per il secondo APK.
  • Se hai un APK per il livello API 16 (e versioni successive) e per schermi piccoli e normali e un altro APK per il livello API 21 (e versioni successive) e per schermi grandi e molto grandi, i codici di versione non devono aumentare in correlazione con i livelli API. Poiché non vi è alcuna sovrapposizione all'interno del filtro delle dimensioni dello schermo, non esistono dispositivi che possano potenzialmente passare da un APK all'altro, pertanto non è necessario che i codici di versione aumentino dal livello API inferiore a quello superiore.
  • Se hai un APK per il livello API 16 (e versioni successive) e CPU ARMv7 e un altro APK per il livello API 21 (e versioni successive) e CPU ARMv5TE, i codici di versione devono aumentare in correlazione con i livelli API. In questo caso, il filtro a livello di API viene utilizzato per distinguere ogni APK, così come l'architettura della CPU. Poiché un APK con librerie ARMv5TE è compatibile con i dispositivi con CPU ARMv7, gli APK si sovrappongono su 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 per ottimizzare le prestazioni dell'app su ogni CPU. Nota: questo vale solo quando si confrontano gli APK con le librerie ARMv5TE e ARMv7 e non quando si confrontano altre librerie native.

Il mancato rispetto delle regole riportate sopra genera un errore in Google Play Console quando attivi gli APK. Non potrai pubblicare l'applicazione finché non avrai risolto l'errore.

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

• Quando modifichi un APK per "ridurre" il supporto delle caratteristiche di un dispositivo e nessun altro APK supporta i dispositivi che non rientrano nell'intervallo supportato. Ad esempio, se un APK supporta attualmente schermi di piccole e normali dimensioni e lo modifichi in modo da supportare solo schermi di piccole dimensioni, avrai ridotto il pool di dispositivi supportati e alcuni dispositivi non vedranno più la tua applicazione su Google Play. Puoi risolvere il problema aggiungendo un altro APK che supporti gli 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 le dimensioni dello schermo small, normal e large, mentre un altro APK supporta le dimensioni large e xlarge, si verifica una sovrapposizione, perché entrambi gli APK supportano schermi di grandi dimensioni. Se non risolvi il problema, i dispositivi idonei per entrambi gli APK (dispositivi con schermo grande nell'esempio) riceveranno l'APK con il codice di versione più alto.

  Nota: se crei APK separati per architetture della CPU diverse, tieni presente che un APK per ARMv5TE si sovrappone 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 la tua applicazione.

Creazione di più APK

Una volta deciso di pubblicare più APK, probabilmente dovrai creare progetti Android distinti per ogni APK che intendi pubblicare in modo da poterli sviluppare adeguatamente singolarmente. 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, come le texture, in base alla configurazione di compilazione.

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

Quando crei più progetti per la stessa applicazione, è buona prassi identificare ciascuno con un nome che indichi le limitazioni del dispositivo da applicare all'APK, in modo da poterli identificare facilmente. Ad esempio, "HelloWorld_21" potrebbe essere un buon nome per un'applicazione progettata per il livello API 21 e versioni successive.

Nota: tutti gli APK pubblicati per la stessa applicazione devono avere lo stesso nome del pacchetto e essere firmati con la stessa chiave del certificato. Assicurati inoltre di comprendere ciascuna delle regole per più APK.

Assegnazione dei codici versione

Ogni APK per la stessa applicazione deve avere un codice di versione univoco, specificato dall'attributo android:versionCode. Devi fare attenzione ad assegnare i codici di versione quando pubblichi più APK, perché devono essere tutti diversi, ma in alcuni casi devono o dovrebbero essere definiti in un ordine specifico, in base alle configurazioni supportate da ciascun APK.

Ordinamento dei codici versione

In genere, un APK che richiede un livello API superiore deve avere un codice di versione superiore. Ad esempio, se crei due APK per supportare livelli API diversi, l'APK per i livelli API più elevati deve avere il codice di versione più elevato. In questo modo, se un dispositivo riceve un aggiornamento di sistema che lo rende idoneo a installare l'APK per livelli API superiori, l'utente riceve una notifica per aggiornare l'app. Per maggiori informazioni su come si applica questo requisito, consulta la sezione precedente relativa alle regole per più APK.

Devi anche considerare in che modo l'ordine dei codici di versione potrebbe influire sull'APK che gli utenti ricevono a causa della sovrapposizione della copertura di diversi APK o di modifiche future che potresti apportare ai tuoi APK.

Ad esempio, se hai APK diversi in base alle dimensioni dello schermo, ad esempio uno per piccolo - normale e uno per grande - xlarge, ma prevedi di cambiare gli APK in modo da avere uno per piccolo e uno per normale - xlarge, devi impostare un codice di versione più alto per l'APK grande - xlarge. In questo modo, un dispositivo di dimensioni normali riceverà l'aggiornamento appropriato quando apporti la modifica, poiché 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 più formati. Poiché un dispositivo riceve l'APK con il codice di versione più alto quando c'è una sovrapposizione nella copertura tra due APK, devi ordinare i codici di versione tra i tuoi APK in modo che l'APK con il formato di compressione preferito abbia il codice di versione più alto. Ad esempio, potresti voler eseguire compilazioni separate per la tua app utilizzando i formati di compressione PVRTC, ATITC ed ETC1. Se preferisci questi formati in questo ordine esatto, l'APK che utilizza PVRTC deve avere il codice di versione più alto, 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ù alto.

Se il Google Play Store non è in grado di identificare l'APK corretto da installare per un dispositivo di destinazione, ti consigliamo di creare anche un APK universale che includa le risorse per tutte le diverse varianti di dispositivo che vuoi supportare. Se fornisci un APK universale, devi assegnargli il valore versionCode più basso. Poiché il Google Play Store installa la versione della tua app compatibile con il dispositivo di destinazione e con 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 dei tuoi altri APK prima di passare all'APK universale più grande.

Utilizzo di uno schema di codice di versione

Per consentire ad APK diversi di aggiornare i propri codici di versione indipendentemente dagli 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 fornisca spazio sufficiente tra ogni APK in modo da poter aumentare il codice in uno senza richiedere un aumento negli altri. Devi anche includere nel codice il nome effettivo della versione (ovvero la versione visibile all'utente assegnata a android:versionName), in modo da associare facilmente il codice e il nome della versione.

Nota:quando aumenti il codice di versione di un APK, Google Play chiederà agli utenti della versione precedente di aggiornare l'applicazione. Pertanto, per evitare aggiornamenti non necessari, non devi aumentare il codice di versione per gli APK che non includono effettivamente modifiche.

Ti consigliamo di utilizzare un codice versione con almeno 7 cifre: gli interi che rappresentano le configurazioni supportate si trovano nei bit di ordine superiore e il nome della versione (da android:versionName) si trova nei bit di ordine inferiore. Ad esempio, quando il nome della versione dell'applicazione è 3.1.0, i codici di versione per un APK con livello API 4 e un APK con livello API 11 saranno rispettivamente 0400310 e 1100310. Le prime due cifre sono riservate al livello API (rispettivamente 4 e 11), le due cifre centrali sono per le dimensioni dello schermo o per i formati delle texture GL (non utilizzati in questi esempi) e le ultime tre cifre sono per 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 (1-4 indicano 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 dalla tua 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 gli 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.