Programma di accesso in anteprima (EAP) di Play for On-device AI

Introduzione

Play per l'AI on-device offre i vantaggi degli Android App Bundle e della pubblicazione su Google Play per la distribuzione di modelli di ML personalizzati, in modo da migliorare le prestazioni del modello con una complessità dell'ecosistema inferiore senza costi aggiuntivi. Ti consente di pubblicare su Play un singolo elemento contenente codice, asset e modelli ML e di scegliere tra una serie di modalità di pubblicazione e opzioni di targeting.

Vantaggi

  • Carica un singolo artefatto di pubblicazione su Google Play e delega a Play l'hosting, la pubblicazione, gli aggiornamenti e il targeting senza costi aggiuntivi.
  • Carica i modelli ML al momento dell'installazione, in modalità rapida successiva o on demand.
    • Il caricamento al momento dell'installazione può garantire la presenza di un modello molto grande quando l'app viene aperta. Il modello verrà installato come APK.
    • La pubblicazione rapida successiva avviene automaticamente in background dopo l'installazione dell'app. Gli utenti potrebbero aprire la tua app prima che il modello sia stato scaricato completamente. Il modello verrà scaricato nello spazio di archiviazione interno della tua app.
    • Il caricamento on demand ti consente di richiedere il modello in fase di esecuzione, il che è utile se il modello è richiesto solo per determinati flussi utente. Il modello verrà scaricato nello spazio di archiviazione interno dell'app.
  • Pubblica varianti dei tuoi modelli di ML che hanno come target dispositivi specifici in base al modello di dispositivo, alle proprietà di sistema o alla RAM.
  • Mantieni gli aggiornamenti delle app piccoli e ottimizzati con l'applicazione di patch automatica di Google Play, il che significa che devono essere scaricate solo le differenze tra i file.

Considerazioni

  • Se utilizzi Play per l'IA on-device, accetti i termini del Contratto di distribuzione per gli sviluppatori di Google Play e dei Termini di servizio del kit di sviluppo software Play Core.
  • Gli sviluppatori che partecipano al programma di accesso in anteprima devono valutare Play per l'IA on-device e fornire feedback a Google Play.
  • I modelli scaricati da Play per l'IA on-device possono essere utilizzati solo dall'app che li ha scaricati. I modelli non devono essere offerti ad altre app, ad esempio tramite una connessione di servizio.
  • I singoli pacchetti AI possono avere una dimensione massima di 1,5 GB, in base alle dimensioni di download compresse. Le dimensioni cumulative massime di qualsiasi versione dell'app generata dall'app bundle sono 4 GB.
  • Le app di dimensioni superiori a 1 GB devono impostare il livello SDK minimo su 21 o versioni successive.
  • Durante il programma di accesso in anteprima, Play per l'AI on-device è soggetto a modifiche.

Come utilizzare Play per l'AI on-device

Play per l'AI on-device utilizza i pacchetti AI. Nel tuo app bundle puoi pacchettizzare i modelli personalizzati pronti per la distribuzione nei pacchetti AI. Puoi scegliere se pubblicare il pacchetto di IA al momento dell'installazione, in modalità rapida successiva o on demand.

Se pacchettizzi i pacchetti di IA con il tuo app bundle, puoi utilizzare tutti gli strumenti di test e di rilascio esistenti di Google Play, come i canali di test e le implementazioni graduali, per gestire la distribuzione della tua app con i tuoi modelli personalizzati.

I pacchetti AI vengono aggiornati insieme al codice binario dell'app. Se la nuova release dell'app non apporta modifiche a un pacchetto AI, la procedura di applicazione automatica dei patch di Google Play assicurerà che l'utente non debba scaricarlo di nuovo. Google Play scaricherà solo le modifiche quando aggiorna l'app.

I pacchetti AI contengono solo modelli. Le librerie Java/Kotlin e native non sono consentite. Se devi spedire librerie o codice per eseguire il modello ML, spostali nel modulo di base o in un modulo di funzionalità. Puoi configurare il modulo di funzionalità in modo che abbia le stesse impostazioni di download e targeting del pacchetto AI.

Utilizzare LiteRT e MediaPipe con i pacchetti AI

Puoi utilizzare LiteRT e MediaPipe con i pacchetti AI. Impacchetta il modello in un pacchetto AI e poi accedivi utilizzando le istruzioni per i pacchetti al momento dell'installazione o per i pacchetti di aggiornamento rapido e on demand.

Per approfondire:

Inizia a utilizzare i pacchetti di IA

Ecco come iniziare a utilizzare Play per l'AI on-device:

  1. Fornisci a Google Play l'ID del tuo account sviluppatore Google Play per partecipare al programma EAP.
  2. Impacchetta i modelli in pacchetti AI nel tuo Android App Bundle e specifica come devono essere caricati.
  3. [Facoltativo] Se vuoi pubblicare modelli diversi su dispositivi diversi, puoi configurare il targeting per dispositivo per i tuoi pacchetti AI. Ad esempio, potresti fornire il pacchetto AI A a un modello di dispositivo specifico, il pacchetto AI B ai dispositivi con almeno 6 GB di RAM e tutti gli altri dispositivi non potrebbero ricevere alcun modello.
  4. [Facoltativo] Se utilizzi la pubblicazione on demand o la pubblicazione rapida, integra la libreria Play AI Delivery nella tua app per scaricare i pacchetti di IA in base alle esigenze.
  5. Testa e rilascia l'app bundle su Google Play.

Fornisci l'ID account sviluppatore Google Play

Poiché questa funzionalità è in accesso in anteprima, il tuo account sviluppatore deve essere inserito nella lista consentita per avere accesso a Play per l'AI on-device. Conferma gli ID account sviluppatore Google Play e i nomi dei pacchetti dell'app al tuo Partner Manager di Google Play o a un membro del team di Play per l'AI on-device. Specifica se scegli come target dei tuoi modelli dispositivi specifici (questo è il passaggio 3 della sezione precedente). Al momento, invitato alcuni partner di Google Play a testare questa funzionalità.

Controllare la versione del plug-in Android per Gradle

Per utilizzare i pacchetti AI, assicurati che la versione del plug-in Android per Gradle (AGP) sia almeno 8.8. Questa versione è inclusa in Android Studio Ladybug 2.

Estrai il modello in un pacchetto AI

Android Studio non è necessario per i passaggi che seguono.

  1. Nella directory di primo livello del progetto, crea una directory per il pacchetto AI. Questo nome di directory viene utilizzato come nome del pacchetto AI. I nomi dei pacchetti AI devono iniziare con una lettera e possono contenere solo lettere, numeri e trattini bassi.

  2. Nella directory del pacchetto AI, crea un file build.gradle e aggiungi il seguente codice. Assicurati di specificare il nome del pacchetto AI e un solo tipo di caricamento:

    // In the AI pack's build.gradle file:
plugins {
  id 'com.android.ai-pack'
}

aiPack {
    packName = "ai-pack-name" // Directory name for the AI pack
    dynamicDelivery {
        deliveryType = "[ install-time | fast-follow | on-demand ]"
    }
}

  3. Nel file build.gradle dell'app del progetto, aggiungi il nome di ogni pacchetto AI nel tuo progetto come mostrato di seguito:

    // In the app build.gradle file:
android {
    ...
    assetPacks = [":ai-pack-name", ":ai-pack2-name"]
}

  4. Nel file settings.gradle del progetto, includi tutti i pacchetti AI come mostrato di seguito:

    // In the settings.gradle file:
include ':app'
include ':ai-pack-name'
include ':ai-pack2-name'

  5. All'interno del pacchetto AI, crea una directory src/main/assets/.

  6. Inserisci i modelli nella directory src/main/assets. Puoi anche creare sottodirectory qui. La struttura di directory della tua app dovrebbe ora avere il seguente aspetto:

    • build.gradle
    • settings.gradle
    • app/
    • ai-pack-name/build.gradle
    • ai-pack-name/src/main/assets/your-model-directories

  7. Aggiungi il codice per caricare ed eseguire i modelli. La modalità di esecuzione dipende dalla modalità di invio dei pacchetti di IA. Consulta le istruzioni per install-time e fast-follow/on-demand di seguito.

  8. [Facoltativo] Configura il targeting per dispositivo per pubblicare modelli diversi su dispositivi diversi.

  9. Crea l'app bundle Android con Gradle. Nell'app bundle generato, la directory di primo livello ora include quanto segue:

    • ai-pack-name/manifest/AndroidManifest.xml: configura l'identificatore e la modalità di invio del pacchetto AI
    • ai-pack-name/assets/your-model-directories: directory che contiene tutti gli asset pubblicati nel pacchetto AI

    Gradle genera il manifest per ogni pacchetto AI e genera la directory assets/ per te.

Configurare il caricamento al momento dell'installazione

I pacchetti AI configurati come al momento dell'installazione sono disponibili immediatamente al momento del lancio dell'app. Utilizza l'API Java AssetManager per accedere ai pacchetti AI pubblicati in questa modalità:

import android.content.res.AssetManager;
...
Context context = createPackageContext("com.example.app", 0);
AssetManager assetManager = context.getAssets();
InputStream is = assetManager.open("model-name");

Configurare la pubblicazione rapida successiva e on demand

Per scaricare pacchetti di IA con distribuzione in tempo reale o on demand, utilizza la Libreria di distribuzione di IA di Google Play.

Dichiarare la dipendenza dalla libreria Play AI Delivery

Nel file build.gradle della tua app, dichiara una dipendenza dalla libreria di pubblicazione di Play AI:

dependencies {
  ...
  implementation "com.google.android.play:ai-delivery:0.1.1-alpha01"
}

Verifica lo stato

Ogni pacchetto AI viene archiviato in una cartella separata nello spazio di archiviazione interno dell'app. Utilizza il metodo getPackLocation() per determinare la cartella principale di un pacchetto AI. Questo metodo restituisce i seguenti valori:

Valore restituito Stato
Un oggetto AiPackLocation valido La cartella principale del pacchetto AI è pronta per l'accesso immediato all'indirizzo assetsPath()
null Pacchetto AI sconosciuto o pacchetti AI non disponibili

Visualizzare le informazioni di download dei pacchetti di IA

Utilizza il metodo
getPackStates() per determinare le dimensioni del download e se il pacchetto è già in download.

Task<AiPackStates> getPackStates(List<String> packNames)

getPackStates() è un metodo asincrono che restituisce un Task<AiPackStates>. Il metodo packStates() di un oggetto AiPackStates restituisce un Map<String, AiPackState>. Questa mappa contiene lo stato di ogni pacchetto AI richiesto, indicato dal nome:

Map<String, AiPackState> AiPackStates#packStates()

La richiesta finale è mostrata di seguito:

final String aiPackName = "myAiPackName";

aiPackManager
    .getPackStates(Collections.singletonList(aiPackName))
    .addOnCompleteListener(new OnCompleteListener<AiPackStates>() {
        @Override
        public void onComplete(Task<AiPackStates> task) {
            AiPackStates aiPackStates;
            try {
                aiPackStates = task.getResult();
                AiPackState aiPackState =
                    aiPackStates.packStates().get(aiPackName);
            } catch (RuntimeExecutionException e) {
                Log.d("MainActivity", e.getMessage());
                return;
            });

I seguenti metodi AiPackState forniscono le dimensioni del pacchetto AI, la quantità scaricata fino a quel momento (se richiesta) e la quantità già trasferita all'app:

Per ottenere lo stato di un pacchetto AI, utilizza il metodo status(), che restituisce lo stato come un intero corrispondente a un campo costante nella classe AiPackStatus. Un pacchetto AI non ancora installato ha lo stato AiPackStatus.NOT_INSTALLED.

Se una richiesta non va a buon fine, utilizza il metodo errorCode(), il cui valore restituito corrisponde a un campo costante nella classe AiPackErrorCode.

Installa

Utilizza il metodo fetch() per scaricare un pacchetto AI per la prima volta o per completare l'aggiornamento di un pacchetto AI:

Task<AiPackStates> fetch(List<String> packNames)

Questo metodo restituisce un oggetto AiPackStates contenente un elenco di pacchetti, i relativi stati di download iniziali e le dimensioni. Se un pacchetto AI richiesto tramite fetch() è già in fase di download, viene restituito lo stato del download e non viene avviato alcun download aggiuntivo.

Monitorare gli stati di download

Devi implementare un AiPackStateUpdateListener per monitorare l'avanzamento dell'installazione dei pacchetti IA. Gli aggiornamenti dello stato sono suddivisi per pacchetto per supportare il monitoraggio dello stato dei singoli pacchetti di IA. Puoi iniziare a utilizzare i pacchetti di IA disponibili prima del completamento di tutti gli altri download per la tua richiesta.

void registerListener(AiPackStateUpdateListener listener)
void unregisterListener(AiPackStateUpdateListener listener)
Download di grandi dimensioni

Se il download è superiore a 200 MB e l'utente non è connesso al Wi-Fi, il download non viene avviato finché l'utente non dà esplicitamente il consenso a procedere con il download utilizzando una connessione dati mobili. Analogamente, se il download è di grandi dimensioni e l'utente perde la connessione Wi-Fi, il download viene messo in pausa e per procedere utilizzando una connessione dati mobili è necessario il consenso esplicito. Un pacchetto in pausa ha lo stato WAITING_FOR_WIFI. Per attivare il flusso dell'interfaccia utente che richiede il consenso dell'utente, utilizza il metodo showConfirmationDialog().

Tieni presente che se l'app non chiama questo metodo, il download viene messo in pausa e riprende automaticamente solo quando l'utente torna a una connessione Wi-Fi.

Conferma dell'utente richiesta

Se un pacchetto ha lo stato REQUIRES_USER_CONFIRMATION, il download non procede finché l'utente non accetta la finestra di dialogo visualizzata con showConfirmationDialog(). Questo stato può verificarsi quando l'app non è riconosciuta da Google Play, ad esempio se è stata installata tramite sideload. Tieni presente che in questo caso l'attivazione di showConfirmationDialog() causerà l'aggiornamento dell'app. Dopo l'aggiornamento, dovrai nuovamente richiedere i pacchetti AI.

Di seguito è riportato un esempio di implementazione di un listener:

AiPackStateUpdateListener aiPackStateUpdateListener = new AiPackStateUpdateListener() {
    private final ActivityResultLauncher<IntentSenderRequest> activityResultLauncher =
      registerForActivityResult(
          new ActivityResultContracts.StartIntentSenderForResult(),
          new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
              if (result.getResultCode() == RESULT_OK) {
                Log.d(TAG, "Confirmation dialog has been accepted.");
              } else if (result.getResultCode() == RESULT_CANCELED) {
                Log.d(TAG, "Confirmation dialog has been denied by the user.");
              }
            }
          });

    @Override
    public void onStateUpdate(AiPackState aiPackState) {
      switch (aiPackState.status()) {
        case AiPackStatus.PENDING:
          Log.i(TAG, "Pending");
          break;

        case AiPackStatus.DOWNLOADING:
          long downloaded = aiPackState.bytesDownloaded();
          long totalSize = aiPackState.totalBytesToDownload();
          double percent = 100.0 * downloaded / totalSize;

          Log.i(TAG, "PercentDone=" + String.format("%.2f", percent));
          break;

        case AiPackStatus.TRANSFERRING:
          // 100% downloaded and assets are being transferred.
          // Notify user to wait until transfer is complete.
          break;

        case AiPackStatus.COMPLETED:
          // AI pack is ready to use. Run the model.
          break;

        case AiPackStatus.FAILED:
          // Request failed. Notify user.
          Log.e(TAG, aiPackState.errorCode());
          break;

        case AiPackStatus.CANCELED:
          // Request canceled. Notify user.
          break;

        case AiPackStatus.WAITING_FOR_WIFI:
        case AiPackStatus.REQUIRES_USER_CONFIRMATION:
          if (!confirmationDialogShown) {
            aiPackManager.showConfirmationDialog(activityResultLauncher);
            confirmationDialogShown = true;
          }
          break;

        case AiPackStatus.NOT_INSTALLED:
          // AI pack is not downloaded yet.
          break;
        case AiPackStatus.UNKNOWN:
          Log.wtf(TAG, "AI pack status unknown")
          break;
      }
    }
}

In alternativa, puoi utilizzare il metodo getPackStates() per ottenere lo stato dei download in corso. AiPackStates contiene l'avanzamento e lo stato del download, nonché eventuali codici di errore relativi a errori.

Accedere ai pacchetti AI

Puoi accedere a un pacchetto AI utilizzando le chiamate al file system dopo che la richiesta di download ha raggiunto lo stato COMPLETED. Utilizza il metodo getPackLocation() per ottenere la cartella principale del pacchetto AI.

I pacchetti AI sono archiviati nella directory assets all'interno della directory principale del pacchetto AI. Puoi ottenere il percorso della directory assets utilizzando il metodo di utilità assetsPath(). Utilizza il seguente metodo per ottenere il percorso di un asset specifico:

private String getAbsoluteAiAssetPath(String aiPack, String relativeAiAssetPath) {
    AiPackLocation aiPackPath = aiPackManager.getPackLocation(aiPack);

    if (aiPackPath == null) {
        // AI pack is not ready
        return null;
    }

    String aiAssetsFolderPath = aiPackPath.assetsPath();
    // equivalent to: FilenameUtils.concat(aiPackPath.path(), "assets");
    String aiAssetPath = FilenameUtils.concat(aiAssetsFolderPath, relativeAiAssetPath);
    return aiAssetPath;
}

Configurare il targeting per dispositivo

Puoi seguire le istruzioni per il targeting per dispositivo per specificare i dispositivi o i gruppi di dispositivi che devono ricevere i tuoi pacchetti AI.

Altri metodi dell'API Play AI Delivery

Di seguito sono riportati alcuni metodi API aggiuntivi che potresti voler utilizzare nella tua app.

Annulla richiesta

Utilizza cancel() per annullare una richiesta di pacchetto AI attiva. Tieni presente che questa richiesta è un'operazione di tipo "best effort".

Rimuovere un pacchetto AI

Utilizza removePack() per pianificare la rimozione di un pacchetto AI.

Ottenere le sedi di più pacchetti AI

Utilizza getPackLocations() per eseguire query collettive sullo stato di più pacchetti AI, in modo da visualizzare una mappa dei pacchetti AI e delle relative posizioni. La mappa restituita da getPackLocations() contiene una voce per ogni pacchetto attualmente scaricato e aggiornato.

Targeting per dispositivo

Il targeting per dispositivo ti consente di avere un controllo più preciso sulle parti del tuo app bundle che vengono caricate su dispositivi specifici. Ad esempio, puoi assicurarti che un modello di grandi dimensioni venga pubblicato solo su dispositivi con RAM elevata oppure puoi pubblicare versioni diverse di un modello su dispositivi diversi.

Puoi scegliere come target le proprietà del dispositivo, ad esempio:

Panoramica dei passaggi obbligatori

Per attivare il targeting per dispositivo, sono necessari i seguenti passaggi:

  1. Definisci i gruppi di dispositivi in un file XML.
  2. Specifica quali parti del bundle devono essere assegnate a quali gruppi di dispositivi.
  3. [Facoltativo] Testa la configurazione a livello locale.
  4. Carica il bundle (contenente il file XML) su Google Play.

Controllare la versione del plug-in Android per Gradle

Per utilizzare il targeting per dispositivo, assicurati che la versione del plug-in Android per Gradle (AGP) sia almeno 8.10.0-alpha01. È incluso in Android Studio Meerkat 2, che è in versione canary.

Attivare questa funzionalità nel plug-in Android per Gradle

Il targeting per dispositivo deve essere attivato esplicitamente nel file gradle.properties:

android.experimental.enableDeviceTargetingConfigApi=true

Creare un file XML di configurazione del targeting per dispositivo

Il file di configurazione del targeting per dispositivo è un file XML in cui definisci i gruppi di dispositivi personalizzati. Ad esempio, puoi definire un gruppo di dispositivi chiamato qti_v79 contenente tutti i dispositivi con il sistema on chip Qualcomm SM8750:

<config:device-targeting-config
    xmlns:config="http://schemas.android.com/apk/config">

    <config:device-group name="qti_v79">
        <config:device-selector>
            <config:system-on-chip manufacturer="QTI" model="SM8750"/>
        </config:device-selector>
    </config:device-group>

</config:device-targeting-config>

Un gruppo di dispositivi è composto da un massimo di 5 selettori di dispositivi. Un dispositivo viene incluso in un gruppo di dispositivi se soddisfa uno dei relativi selettori.

Un selettore di dispositivi può avere una o più proprietà di dispositivo. Un dispositivo viene selezionato se corrisponde a tutte le proprietà del dispositivo del selettore.

Se un dispositivo corrisponde a più gruppi, verranno pubblicati i contenuti per il gruppo definito per primo nel file XML. L'ordine in cui definisci i gruppi nel file XML è l'ordine di priorità.

Se un dispositivo non corrisponde a nessun gruppo, riceverà il gruppo predefinito "altro". Questo gruppo viene generato automaticamente e non deve essere definito esplicitamente.

Proprietà dei dispositivi disponibili

  • device_ram: requisiti della RAM del dispositivo
    • min_bytes (incluso): RAM minima richiesta (in byte)
    • max_bytes (esclusivo): RAM massima richiesta (in byte)
  • included_device_ids: i modelli di dispositivi da includere in questo selettore (massimo 10000 device_id per gruppo). Questa proprietà è soddisfatta se il dispositivo corrisponde a qualsiasi device_id nell'elenco.
    • build_brand: produttore del dispositivo
    • build_device: codice del modello di dispositivo
  • excluded_device_ids: i modelli di dispositivi da escludere in questo selettore (massimo 10000 device_id per gruppo). Questa proprietà è soddisfatta se il dispositivo non corrisponde a nessun device_id nell'elenco.
    • build_brand: produttore del dispositivo
    • build_device: codice del modello di dispositivo

  • required_system_features: funzionalità che un dispositivo deve avere per essere incluso da questo selettore (massimo 100 funzionalità per gruppo). Un dispositivo deve avere tutte le funzionalità di sistema in questo elenco per soddisfare questa proprietà.

    Riferimento alle funzionalità di sistema

    • name: una funzionalità di sistema

  • forbidden_system_features: funzionalità che un dispositivo non deve avere per essere incluso da questo selettore (massimo 100 funzionalità per gruppo). Se un dispositivo possiede una delle funzionalità di sistema in questo elenco, non soddisfa questa proprietà.

    Riferimento alle funzionalità di sistema

    • name: una funzionalità di sistema

  • system-on-chip: i system on chip da includere in questo selettore. Per soddisfare questa proprietà, un dispositivo deve avere uno dei chip in questo elenco.

Ecco un esempio che mostra tutte le possibili proprietà del dispositivo:

<config:device-targeting-config
    xmlns:config="http://schemas.android.com/apk/config">

    <config:device-group name="myCustomGroup1">
      <config:device-selector ram-min-bytes="8000000000">
        <config:included-device-id brand="google" device="redfin"/>
        <config:included-device-id brand="google" device="sailfish"/>
        <config:included-device-id brand="good-brand"/>
        <config:excluded-device-id brand="google" device="caiman"/>
        <config:system-on-chip manufacturer="Sinclair" model="ZX80"/>
        <config:system-on-chip manufacturer="Commodore" model="C64"/>
      </config:device-selector>
      <config:device-selector ram-min-bytes="16000000000"/>
    </config:device-group>

    <config:device-group name="myCustomGroup2">
      <config:device-selector ram-min-bytes="4000000000" ram-max-bytes="8000000000">
        <config:required-system-feature name="android.hardware.bluetooth"/>
        <config:required-system-feature name="android.hardware.location"/>
        <config:forbidden-system-feature name="android.hardware.camera"/>
        <config:forbidden-system-feature name="mindcontrol.laser"/>
      </config:device-selector>
    </config:device-group>

</config:device-targeting-config>

Codici ufficiali del produttore e del modello del dispositivo

Puoi trovare la formattazione corretta per il produttore e il codice modello del dispositivo utilizzando il Catalogo dei dispositivi su Google Play Console:

  • Ispezionare i singoli dispositivi utilizzando il Catalogo dei dispositivi e trovare il codice del produttore e del modello nelle posizioni mostrate nell'esempio seguente (per un Google Pixel 4a, il produttore è"Google" e il codice del modello è"sunfish").

    Pagina di Pixel 4a nel catalogo dei dispositivi

    Pagina di Pixel 4a nel catalogo dei dispositivi

  • Scaricare un file CSV dei dispositivi supportati e utilizzare Manufacturer e Model Code per i campi build_brand e build_device, rispettivamente.

Includi il file di configurazione del targeting per dispositivo nell'app bundle

Aggiungi quanto segue al file build.gradle del modulo principale:

android {
  ...
  bundle {
    deviceTargetingConfig = file('device_targeting_config.xml')
    deviceGroup {
      enableSplit = true   // split bundle by #group
      defaultGroup = "other"  // group used for standalone APKs
    }
  }
  ...
}

device_targeting_config.xml è il percorso del file di configurazione rispetto al modulo principale. In questo modo, il file di configurazione viene pacchettizzato con l'app bundle.

La clausola deviceGroup garantisce che gli APK generati dal tuo bundle vengano suddivisi in base ai gruppi di dispositivi.

Utilizzare il targeting per dispositivo per i pacchetti AI

Puoi mantenere le dimensioni ottimizzate sui dispositivi pubblicando i modelli di grandi dimensioni solo su quelli che possono eseguirli.

Suddividi i pacchetti di IA in base ai gruppi di dispositivi prendendo le directory dei pacchetti di IA esistenti create nell'ultimo passaggio e aggiungendo il suffisso alle cartelle appropriate (come descritto di seguito) con #group_myCustomGroup1, #group_myCustomGroup2 e così via. Quando utilizzi i pacchetti di IA nella tua app, non dovrai indirizzare le cartelle tramite il suffisso (in altre parole, il suffisso viene rimosso automaticamente durante il processo di compilazione).

Dopo il passaggio precedente, il codice potrebbe avere il seguente aspetto:

...
.../ai-pack-name/src/main/assets/image-classifier#group_myCustomGroup1/
.../ai-pack-name/src/main/assets/image-classifier#group_myCustomGroup2/
...

In questo esempio, faresti riferimento a ai-pack-name/assets/image-classifier/ senza suffissi.

I dispositivi in myCustomGroup1 riceveranno tutti gli asset in image-classifier#group_myCustomGroup1/, mentre i dispositivi in myCustomGroup2 riceveranno tutti gli asset in image-classifier#group_myCustomGroup2/.

I dispositivi che non appartengono a myCustomGroup1 o myCustomGroup2 riceveranno un pacchetto ai-pack-name vuoto.

Questo perché i dispositivi che non corrispondono a nessun gruppo riceveranno la variante predefinita del pacchetto AI. Sono inclusi tutti gli elementi non all'interno di una directory con un #group_suffix.

Dopo aver scaricato il pacchetto AI, puoi verificare se il tuo modello è presente utilizzando AssetManager per i pacchetti al momento dell'installazione o AiPackManager per i pacchetti di aggiornamento rapido e on demand. Gli esempi per farlo sono mostrati per tutte le modalità di importazione nell'app di esempio.

Utilizzare il targeting per dispositivo per i moduli di funzionalità

Puoi anche utilizzare il targeting per dispositivo per i moduli di funzionalità. Anziché suddividere i moduli di funzionalità in base al gruppo di dispositivi, specifica se l'intero modulo deve essere fornito in base all'appartenenza al gruppo di dispositivi.

Per pubblicare un modulo della funzionalità sui dispositivi che appartengono a myCustomGroup1 o myCustomGroup2, modifica il relativo AndroidManifest.xml:

<manifest ...>
  ...
  <dist:module dist:title="...">
    <dist:delivery>
      <dist:install-time>
        <dist:conditions>
          <dist:device-groups>
            <dist:device-group dist:name="myCustomGroup1"/>
            <dist:device-group dist:name="myCustomGroup2"/>
          </dist:device-groups>
          ...
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
  </dist:module>
  ...
</manifest>

Eseguire il test localmente

Prima di creare una release per il nuovo bundle, puoi eseguire il test localmente con la condivisione interna delle app o Bundletool.

Condivisione interna delle app

La condivisione interna delle app ti consente di utilizzare un app bundle per generare rapidamente un URL che puoi toccare su un dispositivo locale per installare esattamente ciò che Google Play installerebbe per quel dispositivo se la versione dell'app fosse pubblicata in un canale di produzione o di test.

Consulta le istruzioni sulla condivisione interna delle app.

Bundletool

In alternativa, puoi generare APK utilizzando bundletool (1.18.0 o versioni successive) e caricarli tramite sideload sul tuo dispositivo. Per testare la tua app a livello locale utilizzando bundletool:

  1. Crea il tuo app bundle con Android Studio o bundletool.

  2. Genera APK con il flag --local-testing:

    java -jar bundletool-all.jar build-apks --bundle=path/to/your/bundle.aab \
  --output=output.apks --local-testing

  3. Collega un dispositivo ed esegui bundletool per eseguire il sideload degli APK:

    # Example without Device Targeting Configuration
java -jar bundletool.jar install-apks --apks=output.apks

    # Example with Device Targeting Configuration (you must specify which groups the connected device belongs to)
java -jar bundletool.jar install-apks --apks=output.apks --device-groups=myCustomGroup1,myCustomGroup2

Limitazioni dei test locali con bundletool

Di seguito sono riportate le limitazioni dei test locali con bundletool:

  • I pacchetti fast-follow si comportano come i pacchetti on-demand. In altre parole, non verranno recuperati automaticamente quando l'app viene installata tramite sideload. Gli sviluppatori devono richiederle manualmente all'avvio dell'app. Questa operazione non richiede modifiche al codice dell'app.
  • I pacchetti vengono recuperati dallo spazio di archiviazione esterno anziché da Google Play, pertanto non puoi testare il comportamento del codice in caso di errori di rete.
  • I test locali non coprono lo scenario di attesa del Wi-Fi.
  • Gli aggiornamenti non sono supportati. Prima di installare una nuova versione della build, disinstalla manualmente la versione precedente.

Verificare che vengano installati gli APK corretti

Utilizza il seguente metodo per assicurarti che sul dispositivo siano installati solo gli APK corretti

adb shell pm path {packageName}

Dovresti vedere qualcosa di simile a quanto segue:

package:{...}/base.apk
package:{...}/split_config.en.apk
package:{...}/split_config.xxhdpi.apk
package:{...}/split_main_ai-pack-name.apk
package:{...}/split_main_ai-pack-name.config.group_myCustomGroup1.apk

Tieni presente che in questo elenco vedrai solo gli APK, costituiti da moduli di funzionalità e pacchetti AI al momento dell'installazione. I pacchetti di AI on demand e di aggiornamento rapido non vengono installati come APK.

Testare e rilasciare su Google Play

Ti consigliamo di testare l'app end-to-end su Google Play con un canale di test interno.

A questo punto, puoi rilasciare l'aggiornamento dell'app in modo incrementale in produzione con le implementazioni graduali.

App di esempio che utilizza Play per l'AI on-device

Contatta il tuo Partner Manager di Google Play per ottenere l'accesso alla nostra app di esempio.

Illustra come utilizzare ciascuna modalità di pubblicazione e la configurazione del targeting per dispositivo. Per iniziare, consulta la sezione relativa ai test locali.

Fornisci feedback

I partecipanti al programma di accesso in anteprima devono segnalare i problemi e fornire feedback. Puoi contattare il tuo Partner Manager di Google Play o il team di Play per l'AI on-device.

Contenuti correlati

Scopri di più sugli Android App Bundle e consulta i riferimenti per l'SDK AI Delivery.