Compatibilità con le versioni precedenti dell'SDK Runtime

Questo documento propone una nuova libreria Jetpack per aiutare gli sviluppatori con la migrazione all'SDK Runtime. Spiega come verrà supportato SDK Runtime per le versioni precedenti della piattaforma Android (dalla build all'esecuzione) e quali differenze o limitazioni nell'ambiente di runtime possono aspettarsi gli sviluppatori. Questa libreria consente agli sviluppatori di creare una singola versione della propria app o del proprio SDK che includa la possibilità di essere eseguita su dispositivi con o senza supporto di SDK Runtime.

La compatibilità con le versioni precedenti viene ottenuta tramite i seguenti componenti:

  • Android Gradle Plugin (AGP) + Bundletool crea una variante dell'app per i dispositivi senza supporto di SDK Runtime raggruppando SDK Runtime nell'APK.

  • La libreria client SDK Runtime (androidx.privacysandbox.sdkruntime:sdkruntime-client) carica l'SDK in bundle dalle risorse dell'app ed emula SDK Runtime sui dispositivi senza supporto di SDK Runtime.

  • La libreria del fornitore di SDK Runtime (androidx.privacysandbox.sdkruntime:sdkruntime-provider) fornisce un'API per gli SDK per consentire il caricamento dalla libreria client SDK Runtime.

Distribuzione dell'SDK con Bundletool

Sui dispositivi che supportano SDK Runtime, gli SDK verranno pubblicati e installati come pacchetti separati.

Per supportare le versioni della piattaforma che non supportano SDK Runtime, Bundletool creerà una o più varianti del set di APK dell'app che includono tutti gli SDK da cui dipende l'app. Ogni SDK viene pacchettizzato come suddivisione APK separata. Inoltre, vengono eseguite le seguenti trasformazioni:

  1. Copia i file bytecode (DEX) dell'SDK nella suddivisione dell'SDK come asset.
  2. Copia le risorse Java dell'SDK nella suddivisione dell'SDK come asset.
  3. Rimappa le risorse dell'SDK e uniscile a quelle dell'app.
  4. Genera configurazioni per la libreria client SDK Runtime.

Carica gli SDK con la libreria client SDK Runtime

La libreria client SDK Runtime fornisce API simili alle API della piattaforma, ma supporta sia gli SDK nell'ambiente SDK Runtime sia gli SDK inclusi nell'app variante.

Per utilizzare la libreria client SDK Runtime, aggiungi la dipendenza androidx.privacysandbox.sdkruntime:sdkruntime-client e utilizza SdkSandboxManagerCompat anziché SdkSandboxManager.

Quando un'app tenta di caricare un SDK, la libreria controlla innanzitutto se l'SDK è stato raggruppato con l'app durante la build. Se è in bundle, la libreria estrae l'SDK dallo split dell'SDK e lo carica nel processo dell'app. Se l'SDK non è stato raggruppato con l'app, la libreria delega l'API della piattaforma per caricare l'SDK.

Estrarre un SDK dagli asset

Quando un'app tenta di caricare un SDK in bundle, la libreria client SDK Runtime verifica se i file DEX dell'SDK sono già stati estratti nella memoria del dispositivo (code_cache) e, in caso contrario, li estrae dagli asset.

La libreria estrae normalmente i file una sola volta dopo l'installazione o l'aggiornamento di un'app.

Se lo spazio di archiviazione disponibile è inferiore alla soglia consentita (attualmente 100 MB) e non vengono estratti file DEX, la libreria tenta di caricare l'SDK direttamente dagli asset sui dispositivi supportati (API 27+). Ciò comporta un maggiore utilizzo della memoria.

ClassLoader per le classi SDK

Per evitare conflitti tra gli SDK e le classi dell'app, tutte le classi dell'SDK vengono caricate utilizzando un class loader separato completamente indipendente dal class loader dell'app principale.

Nell'attuale progettazione di SDK Runtime, tutte le comunicazioni tra un'app e gli SDK avvengono tramite chiamate IPC Binder. Gli stessi oggetti Binder SDK vengono utilizzati per gli SDK in bundle e la serializzazione delle transazioni Binder consente agli sviluppatori di app di eseguire il cast degli oggetti Binder SDK nelle interfacce Binder SDK sul lato app.

Per altre interazioni interne (ad esempio l'inizializzazione di un SDK, la fornitura di un'API controller a un SDK e così via), la libreria utilizza la reflection e i proxy dinamici per funzionare con diversi class loader.

Ambiente SDK

La libreria del provider SDK Runtime fornisce API agli sviluppatori di SDK. Queste API sono simili alle API della piattaforma, ma consentono di caricare gli SDK sia dall'ambiente di runtime dell'SDK sia dalla libreria client SDK Runtime.

Per poter utilizzare l'SDK della libreria, devi aggiungere la dipendenza androidx.privacysandbox.sdkruntime:sdkruntime-provider ed estendere SandboxedSdkProviderCompat anziché SandboxedSdkProvider.

Devi anche utilizzare SandboxedSdkProviderAdapter come fornitore dell'SDK per consentire il caricamento del fornitore di compatibilità nell'ambiente di runtime dell'SDK.

SdkSandboxControllerCompat delega all'API della piattaforma quando l'SDK viene caricato in SDK Runtime o delega alla libreria client SDKRuntime quando l'SDK viene caricato come SDK in bundle.

Per gli SDK in bundle, la libreria modifica l'ambiente SDK in modo da emulare un comportamento simile a quello dell'ambiente SDK Runtime.

Le sezioni successive descrivono i comportamenti previsti quando l'SDK viene caricato dalla libreria client SDKRuntime.

Risorse SDK

Le risorse SDK (res/) sono supportate quando l'SDK viene caricato nel processo dell'app. Bundletool unisce tutte le risorse degli SDK con le risorse dell'app.

Per evitare conflitti, le risorse SDK vengono rimappate modificando il prefisso packageId in tutti gli ID risorsa.

Quando l'SDK viene caricato dalla libreria client SDKRuntime, packageId viene aggiornato nel runtime per consentire l'indirizzamento delle risorse rimappate utilizzando la classe R.

Risorse Java

Le risorse Java sono supportate quando l'SDK viene caricato nel processo dell'app. Bundletool copia tutte le risorse Java dell'SDK in una directory speciale negli asset dell'app. La libreria client SDKRuntime utilizza un class loader intermedio per reindirizzare tutte le chiamate relative alle risorse Java alla nuova directory principale.

Asset SDK

Gli asset SDK vengono uniti agli asset dell'app senza essere rimappati.

Archiviazione SDK

Per supportare l'archiviazione SDK, la libreria client SDK Runtime crea una directory radice dedicata per ogni SDK in bundle nell'archivio dell'app e fornisce un contesto speciale che utilizza questa directory come radice di archiviazione.

Questo contesto può essere recuperato da SandboxedSdkProviderCompat#getContext.

Metodi supportati relativi allo spazio di archiviazione:

  • getDataDir
  • getCacheDir
  • getCodeCacheDir
  • getNoBackupFilesDir
  • getDir
  • getFilesDir
  • openFileInput
  • openFileOutput
  • deleteFile
  • getFileStreamPath
  • fileList
  • getDatabasePath
  • openOrCreateDatabase
  • moveDatabaseFrom - solo tra i contesti SDK
  • deleteDatabase
  • databaseList
  • getSharedPreferences
  • moveSharedPreferencesFrom - solo tra i contesti SDK
  • deleteSharedPreferences

È possibile creare un contesto di archiviazione protetto dal dispositivo chiamando createDeviceProtectedStorageContext() in quel contesto.

SdkSandboxControllerCompat

La libreria client SDKRuntime fornisce l'implementazione SdkSandboxControllerCompat per gli SDK in bundle caricati nel processo dell'app.

Se le API non sono supportate dalla libreria client (ad esempio con un SDK creato con una versione della libreria più recente della versione dell'app), verrà utilizzato il fallback più adatto (no-op o eccezione).

Controllo delle versioni

Quando la libreria client SDKRuntime carica un SDK in bundle, esegue un handshake con la libreria del provider SDKRuntime all'interno dell'SDK. Durante l'handshake, le librerie scambiano le proprie versioni e modificano il comportamento per sostituire le API non disponibili con il fallback più adatto (no-op o eccezione).

L'utilizzo della versione più recente della libreria è vivamente consigliato sia per gli sviluppatori di app che per quelli di SDK, altrimenti la funzionalità che richiede il supporto in entrambe le parti potrebbe non essere disponibile.

Qualsiasi versione della libreria client SDKRuntime può caricare un SDK con qualsiasi versione della libreria del provider SDKRuntime e viceversa.

In futuro, questo valore verrà modificato in modo da corrispondere alla versione minima della libreria client necessaria per caricare l'SDK con una determinata versione della libreria del fornitore.

In questo modo, la frammentazione verrà ridotta al minimo e la maggior parte delle API verrà supportata se l'SDK in bundle è stato caricato correttamente.