Play per l'AI on-device (beta)

Introduzione

Play per l'AI on-device offre i vantaggi degli Android App Bundle e della distribuzione di Google Play alla distribuzione di modelli di ML personalizzati, in modo da migliorare le prestazioni dei modelli con una minore complessità dell'ecosistema dei dispositivi senza costi aggiuntivi. Ti consente di pubblicare su Play un singolo artefatto contenente il codice, gli asset e i modelli di 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 l'hosting, la distribuzione, gli aggiornamenti e il targeting a Play senza costi aggiuntivi.
• Pubblica i tuoi modelli di ML al momento dell'installazione, in modalità fast-follow o on demand.
  • La distribuzione al momento dell'installazione può garantire che un modello molto grande sia presente quando l'app viene aperta. Il modello verrà installato come APK.
  • La distribuzione Fast-follow avviene automaticamente in background dopo l'installazione dell'app. Gli utenti potrebbero aprire la tua app prima che il download del modello sia stato completato. Il modello verrà scaricato nello spazio di archiviazione interno dell'app.
  • La pubblicazione on demand ti consente di richiedere il modello in fase di runtime, 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 destinate a dispositivi specifici in base al modello, alle proprietà di sistema o alla RAM.
• Mantieni gli aggiornamenti delle app di piccole dimensioni e ottimizzati con l'applicazione automatica di patch di Play, il che significa che devono essere scaricate solo le differenze nei file.

Considerazioni

• Utilizzando Play for On-device AI, accetti i termini del Contratto di distribuzione per gli sviluppatori di Google Play e dei Termini di servizio della libreria di base Play Software Development Kit.
• I modelli scaricati da Play per On-device AI devono essere utilizzati solo dalle tue app. I modelli non devono essere offerti ad altre app.
• I singoli AI Pack possono avere una dimensione massima di 1,5 GB, in base alle dimensioni del download compresso. Le dimensioni massime cumulative di qualsiasi versione della tua app generata dall'app bundle sono di 4 GB.
• Le app con dimensioni superiori a 1 GB devono impostare il livello SDK minimo su 21 o versioni successive.

Come utilizzare Play per l'AI on-device

Play per l'AI on-device utilizza AI Pack. Puoi pacchettizzare i modelli personalizzati pronti per la distribuzione in AI Pack nell'app bundle. Puoi scegliere se il pacchetto AI deve essere distribuito al momento dell'installazione, in modalità fast-follow o on demand.

Se pacchettizzi gli AI pack con l'app bundle, puoi utilizzare tutti gli strumenti di test e rilascio esistenti di Play, come i canali di test e i rilasci graduali, per gestire la distribuzione della tua app con i modelli personalizzati.

I pacchetti AI vengono aggiornati insieme al file binario dell'app. Se la nuova release dell'app non apporta modifiche a un AI Pack, il processo di applicazione automatica delle patch di Play garantirà che l'utente non debba scaricarlo di nuovo. Google Play scaricherà solo le modifiche quando aggiorna l'app.

Gli AI Pack contengono solo modelli. Le librerie Java/Kotlin e native non sono consentite. Se devi inviare librerie o codice per eseguire il modello di ML, spostalo nel modulo di base o in un modulo della funzionalità. Puoi configurare il modulo della funzionalità in modo che abbia le stesse impostazioni di download e targeting dell'AI Pack.

Nota: gli AI Pack non contengono librerie Java/Kotlin o native. Puoi distribuire librerie o codice per eseguire i tuoi modelli di ML nei moduli delle funzionalità.

Utilizza LiteRT e MediaPipe con i pacchetti AI

Puoi utilizzare LiteRT e MediaPipe con gli AI Pack. Pacchettizza il tuo modello in un AI Pack e poi accedi utilizzando le istruzioni per i pacchetti install-time o per i pacchetti fast-follow e on-demand.

Per approfondire:

• Inizia a utilizzare LiteRT
  • L'app di esempio mostra come pacchettizzare un modello LiteRT in un AI Pack e caricarlo in fase di runtime.
  • Esistono molti modelli LiteRT preaddestrati che puoi utilizzare negli AI Pack per iniziare.
• Inizia a utilizzare MediaPipe
  • Per i pacchetti fast-follow e on-demand, puoi utilizzare AssetCache.java per caricare gli asset (ad es. .binarypb file) in base ai relativi percorsi.
  • Per i pacchetti install-time, puoi utilizzare AndroidAssetUtil.java.

Inizia a utilizzare gli AI Pack

In generale, ecco come puoi iniziare a utilizzare Play per l'AI on-device:

1. Pacchettizza i tuoi modelli in AI Pack nel tuo Android App Bundle e specifica come devono essere distribuiti gli AI Pack.
2. [Facoltativo] Se vuoi pubblicare modelli diversi su dispositivi diversi, puoi configurare il targeting per dispositivo per i tuoi AI Pack. 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 nessun modello a tutti gli altri dispositivi.
3. [Facoltativo] Se utilizzi la distribuzione on demand o fast-follow, integra la libreria Play AI Delivery nella tua app per scaricare i pacchetti AI in base alle necessità.
4. Testa e rilascia l'app bundle su Google Play.

Controlla la versione del plug-in Android per Gradle

Per utilizzare gli AI Pack, 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 AI Pack

Android Studio non è necessario per i seguenti passaggi.

1. Nella directory di primo livello del progetto, crea una directory per l'AI Pack. Questo nome della 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 consegna:

   // 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 AI Pack nel 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 gli AI Pack nel progetto come mostrato di seguito:

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

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

6. Posiziona i modelli nella directory src/main/assets. Puoi anche creare sottodirectory qui. La struttura di directory dell'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 tuoi modelli. La modalità di esecuzione dipende dalla modalità di distribuzione degli AI pack. 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'Android App Bundle con Gradle. Nell'app bundle generato, la directory a livello di root ora include quanto segue:

   • ai-pack-name/manifest/AndroidManifest.xml: configura l'identificatore e la modalità di distribuzione dell'AI Pack
   • ai-pack-name/assets/your-model-directories: la directory che contiene tutti gli asset forniti nell'ambito dell'AI Pack

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

Configura la distribuzione al momento dell'installazione

I pacchetti AI configurati come install-time sono immediatamente disponibili al lancio dell'app. Utilizza l'API AssetManager di Java per accedere agli AI Pack 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");

Configura la distribuzione on demand e fast-follow

Per scaricare gli AI Pack con pubblicazione on demand o fast-follow, utilizza la libreria di pubblicazione di Google Play AI.

Dichiara la dipendenza dalla libreria Play AI Delivery

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

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

Verifica lo stato

Ogni AI Pack viene archiviato in una cartella separata nella memoria interna dell'app. Utilizza il metodo getPackLocation() per determinare la cartella principale di un AI Pack. 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

Nota: non fare affidamento sulle posizioni dei pacchetti AI memorizzati nella cache tra i lanci dell'app. L'app deve sempre verificare l'esistenza di AI Pack a ogni avvio. I pacchetti AI potrebbero diventare non validi a causa di aggiornamenti dell'app o se l'utente cancella i dati dell'app.

Recupera informazioni sul download dei AI Pack

Utilizza il metodo
getPackStates() per determinare le dimensioni del download e se il pacchetto è già in fase di 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 AI Pack richiesto, con chiave in base al nome:

Map<String, AiPackState> AiPackStates#packStates()

La richiesta finale è la seguente:

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 finora (se richiesta) e la quantità già trasferita all'app:

• totalBytesToDownload()
• bytesDownloaded()
• transferProgressPercentage()

Per ottenere lo stato di un AI Pack, utilizza il metodo status(), che restituisce lo stato come numero intero corrispondente a un campo costante nella classe AiPackStatus. Un AI Pack 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 AI Pack per la prima volta o chiama l'aggiornamento di un AI Pack per completare:

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

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

Nota: nella maggior parte dei casi, implementi un listener per monitorare il processo di download e installazione, come descritto nella sezione successiva.

Monitora gli stati dei download

Devi implementare un AiPackStateUpdateListener per monitorare l'avanzamento dell'installazione degli AI Pack. Gli aggiornamenti di stato sono suddivisi per pacchetto per supportare il monitoraggio dello stato dei singoli AI Pack. Puoi iniziare a utilizzare i AI Pack disponibili prima che tutti gli altri download per la tua richiesta siano stati completati.

void registerListener(AiPackStateUpdateListener listener)
void unregisterListener(AiPackStateUpdateListener listener)

Nota: il Play Store attiva automaticamente il download di tutti i pack fast-follow dopo che l'utente ha installato o aggiornato l'app. Tuttavia, questi pack potrebbero non essere pronti per l'uso immediato. Devi controllare lo stato dei pack fast-follow a ogni avvio dell'app. Se il download è in corso, monitoralo con un listener. Se il download viene annullato o messo in pausa, puoi riprenderlo utilizzando il metodo fetch(), come descritto nella sezione Install.

Download di grandi dimensioni

Se il download supera i 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 ed è necessario il consenso esplicito per procedere utilizzando una connessione dati mobili. Un pacchetto in pausa ha lo stato WAITING_FOR_WIFI. Per attivare il flusso della UI per chiedere il consenso all'utente, utilizza il metodo showConfirmationDialog().

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

Conferma utente obbligatoria

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

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 attuali. AiPackStates contiene l'avanzamento del download, lo stato del download e gli eventuali codici di errore.

Accedi ai pacchetti AI

Puoi accedere a un AI Pack 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 dell'AI Pack.

I pacchetti AI sono archiviati nella directory assets all'interno della directory root dei pacchetti AI. Puoi ottenere il percorso della directory assets utilizzando il metodo di convenienza 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;
}

Configura 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 AI Pack.

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 AI Pack attiva. Tieni presente che questa richiesta è un'operazione "best effort".

Rimuovi un pacchetto AI

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

Ottenere le posizioni di più AI Pack

Utilizza getPackLocations() per eseguire query collettive sullo stato di più AI Pack, che restituisce una mappa degli AI Pack 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 offre un controllo più preciso su quali parti dell'app bundle vengono distribuite a dispositivi specifici. Ad esempio, puoi assicurarti che un modello di grandi dimensioni venga distribuito solo ai dispositivi con RAM elevata o puoi distribuire versioni diverse di un modello a dispositivi diversi.

Puoi scegliere come target proprietà dei dispositivi come:

• System on chip
• Modello dispositivo
• RAM del dispositivo
• Funzionalità di sistema

Panoramica dei passaggi obbligatori

Per attivare il targeting per dispositivo, segui questi passaggi:

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

Controlla 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. Questo è incluso in Android Studio (Meerkat 2 e versioni successive). Scarica l'ultima versione stabile di Android Studio.

Attiva questa funzionalità nel plug-in Android per Gradle

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

android.experimental.enableDeviceTargetingConfigApi=true

Crea un file XML di configurazione del targeting per dispositivo

Il file di configurazione del targeting per dispositivo è un file XML in cui definisci i tuoi gruppi di dispositivi personalizzati. Ad esempio, puoi definire un gruppo di dispositivi denominato qti_v79 che contiene tutti i dispositivi con il system 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 è incluso in un gruppo di dispositivi se soddisfa uno dei selettori di dispositivi.

Un selettore di dispositivi può avere una o più proprietà del 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 del 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 di RAM del dispositivo
  • min_bytes (inclusivo): RAM minima richiesta (in byte)
  • max_bytes (esclusivo): RAM massima richiesta (in byte)
• included_device_ids: modelli di dispositivi da includere in questo selettore (massimo 10.000 device_id per gruppo). Questa proprietà è soddisfatta se il dispositivo corrisponde a un device_id nell'elenco.
  • build_brand: produttore del dispositivo
  • build_device: codice del modello di dispositivo
• excluded_device_ids: modelli di dispositivi da escludere in questo selettore (massimo 10.000 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à del 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 ha una delle funzionalità di sistema in questo elenco, non soddisfa questa proprietà.

  Riferimento alle funzionalità del sistema

  • name: una funzionalità di sistema

• system-on-chip: system on chip da includere in questo selettore. Un dispositivo deve avere un chip presente in questo elenco per soddisfare questa proprietà.

  • produttore: produttore del system on chip
  • model: modello di system on chip

Suggerimento:l'inclusione di più proprietà in un unico selettore crea un AND logico, ad esempio:

    <config:device-selector ram-min-bytes="7000000000">
        <config:included-device-id brand="google" device="flame"/>
    </config:device-selector>
  

creerà la condizione per tutti i dispositivi con più di 7 GB di RAM E che sono Pixel 4, come scritto di seguito:

Se vuoi una condizione OR, crea selettori separati in un unico gruppo di dispositivi, ad esempio:

    <config:device-selector ram-min-bytes="7000000000"/>
    <config:device-selector>
          <config:included-device-id brand="google" device="flame"/>
    </config:device-selector>
  

creerà la condizione per tutti i dispositivi con più di 7 GB di RAM OPPURE per Pixel 4, scritto anche come segue:

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 del modello del dispositivo utilizzando il catalogo dei dispositivi in Google Play Console:

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

  

  

• Scaricare un file CSV dei dispositivi supportati e utilizzare i campi Produttore e Codice modello rispettivamente per i campi build_brand e build_device.

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 relativo al modulo principale. In questo modo, il file di configurazione viene pacchettizzato con l'app bundle.

La clausola deviceGroup garantisce che gli APK generati dall'app bundle siano divisi per gruppi di dispositivi.

Utilizza il targeting per dispositivo per i tuoi AI Pack

Puoi mantenere le dimensioni ottimizzate sui dispositivi distribuendo i modelli di grandi dimensioni solo ai dispositivi che possono eseguirli.

Suddividi i tuoi AI Pack per gruppi di dispositivi prendendo le directory degli AI Pack esistenti create nell'ultimo passaggio e aggiungendo un suffisso alle cartelle appropriate (come descritto di seguito) con #group_myCustomGroup1, #group_myCustomGroup2 e così via. Quando utilizzi gli AI Pack nella tua app, non dovrai indirizzare le cartelle per suffisso (in altre parole, il suffisso viene rimosso automaticamente durante il processo di build).

Dopo il passaggio precedente, il risultato potrebbe essere il seguente:

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

In questo esempio, devi fare 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 né a myCustomGroup1 né a myCustomGroup2 riceveranno un pacchetto ai-pack-name vuoto.

Questo perché i dispositivi che non corrispondono a nessun gruppo di dispositivi riceveranno la variante predefinita del tuo AI Pack. Sono inclusi tutti i contenuti che non si trovano all'interno di una directory con un #group_suffix.

Una volta scaricato l'AI Pack, puoi verificare se il tuo modello è presente utilizzando AssetManager per i pacchetti install-time o AiPackManager per i pacchetti fast-follow e on-demand. Gli esempi per farlo sono mostrati per tutte le modalità di pubblicazione nell'app di esempio.

Importante: non è possibile impedire che qualsiasi variante del tuo AI Pack venga distribuita su determinati dispositivi. I dispositivi non scelti come target riceveranno sempre la variante predefinita.

Utilizza il targeting per dispositivo per i moduli delle funzionalità

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

Per distribuire un modulo della funzionalità ai 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>

Nota: i dispositivi non scelti come target non riceveranno affatto il modulo della funzionalità. Questo è diverso dal targeting per gli AI Pack, in cui i dispositivi non scelti come target ricevono una variante predefinita vuota dell'AI Pack.

Esegui test in locale

Prima di creare una release per il nuovo bundle, puoi eseguire test localmente con la condivisione interna delle app o con 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 quella versione dell'app fosse pubblicata in un canale di test o di produzione.

Consulta le istruzioni per la condivisione interna delle app.

Bundletool

In alternativa, puoi generare APK utilizzando bundletool (1.18.0 o versioni successive) e caricarli sul tuo dispositivo. Segui questi passaggi per testare la tua app localmente utilizzando bundletool:

1. Crea l'app bundle con Android Studio o bundletool.

2. Genera gli 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 trasferita localmente. Gli sviluppatori devono richiederle manualmente all'avvio dell'app. Non sono necessarie modifiche al codice dell'app.
• I pacchetti vengono recuperati dallo spazio di archiviazione esterno anziché da Google Play, quindi non puoi testare il comportamento del tuo codice in caso di errori di rete.
• I test locali non coprono lo scenario di attesa della connessione Wi-Fi.
• Gli aggiornamenti non sono supportati. Prima di installare una nuova versione della build, disinstalla manualmente la versione precedente.

Verifica 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:

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, che sono costituiti da moduli delle funzionalità e pacchetti AI al momento dell'installazione. I pacchetti AI on demand e fast-follow non vengono installati come APK.

Testa e rilascia su Google Play

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

Una volta fatto, puoi rilasciare in modo incrementale l'aggiornamento dell'app in produzione con i rilasci graduali.

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

Scarica l'app di esempio.

Mostra come utilizzare ciascuna delle modalità di pubblicazione e la configurazione del targeting per dispositivo. Per iniziare, consulta la sezione Test locali.

Contenuti correlati

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