Play for On-Device AI (Beta)

Einführung

Play for On-device AI bietet die Vorteile von Android App Bundles und der Google Play-Bereitstellung für die Verteilung benutzerdefinierter ML-Modelle. So können Sie die Modellleistung ohne zusätzliche Kosten und mit weniger Komplexität im Geräte-Ökosystem verbessern. Sie können ein einzelnes Artefakt mit Ihrem Code, Ihren Assets und Ihren ML-Modellen bei Google Play veröffentlichen und aus einer Reihe von Bereitstellungsmodi und Targeting-Optionen auswählen.

Vorteile

• Sie können ein einzelnes Veröffentlichungsartefakt in Google Play hochladen und das Hosting, die Bereitstellung, die Aktualisierung und das Targeting ohne zusätzliche Kosten an Play delegieren.
• Sie können Ihre ML-Modelle bei der Installation, als Fast-Follow oder auf Abruf bereitstellen.
  • Durch die Bereitstellung zur Installationszeit kann sichergestellt werden, dass ein sehr großes Modell vorhanden ist, wenn Ihre App geöffnet wird. Ihr Modell wird als APK installiert.
  • Die schnelle nachträgliche Auslieferung erfolgt automatisch im Hintergrund, nachdem Ihre App installiert wurde. Nutzer können Ihre App öffnen, bevor Ihr Modell vollständig heruntergeladen wurde. Ihr Modell wird in den internen Speicher Ihrer App heruntergeladen.
  • Bei der On-Demand-Bereitstellung können Sie das Modell zur Laufzeit anfordern. Das ist nützlich, wenn das Modell nur für bestimmte Nutzerabläufe erforderlich ist. Ihr Modell wird in den internen Speicherplatz Ihrer App heruntergeladen.
• Sie können Varianten Ihrer ML-Modelle bereitstellen, die auf bestimmte Geräte ausgerichtet sind, basierend auf Gerätemodell, Systemeigenschaften oder RAM.
• Mit dem automatischen Patchen von Play können Sie App-Updates klein und optimiert halten, da nur die Unterschiede in den Dateien heruntergeladen werden müssen.

Wissenswertes

• Wenn Sie Play für On-Device-KI verwenden, stimmen Sie den Bedingungen der Vertriebsvereinbarung für Entwickler bei Google Play und den Nutzungsbedingungen für das Play Core SDK zu.
• Von Play für On-Device-KI heruntergeladene Modelle dürfen nur von Ihren Apps verwendet werden. Modelle dürfen nicht für andere Apps angeboten werden.
• Einzelne KI-Pakete können je nach komprimierter Downloadgröße bis zu 1, 5 GB groß sein. Die maximale kumulative App-Größe einer beliebigen Version Ihrer App, die aus Ihrem App-Bundle generiert wird, beträgt 4 GB.
• Bei Apps, die größer als 1 GB sind, muss das SDK-Mindestlevel auf 21 oder höher festgelegt werden.

Play for On‑Device AI verwenden

Bei Play for On-Device AI werden KI-Pakete verwendet. Sie verpacken benutzerdefinierte Modelle, die für die Verteilung in KI-Paketen bereit sind, in Ihrem App-Bundle. Sie können auswählen, ob das KI-Paket während der Installation, als Fast-Follow-Modul oder auf Anfrage bereitgestellt werden soll.

Wenn Sie KI-Packs mit Ihrem App Bundle verpacken, können Sie alle vorhandenen Test- und Release-Tools von Google Play verwenden, z. B. Test-Tracks und stufenweise Einführung, um die Verteilung Ihrer App mit Ihren benutzerdefinierten Modellen zu verwalten.

KI-Pakete werden zusammen mit dem App-Binärprogramm aktualisiert. Wenn in Ihrem neuen App-Release keine Änderungen an einem KI-Paket vorgenommen werden, sorgt der automatische Patching-Prozess von Google Play dafür, dass der Nutzer es nicht noch einmal herunterladen muss. Bei der Aktualisierung der App lädt Google Play nur die Änderungen herunter.

KI-Pakete enthalten nur Modelle. Java-/Kotlin- und native Bibliotheken sind nicht zulässig. Wenn Sie Bibliotheken oder Code zum Ausführen Ihres ML-Modells bereitstellen müssen, verschieben Sie sie in das Basismodul oder ein Funktionsmodul. Sie können Ihr Funktionsmodul so konfigurieren, dass es dieselben Download- und Targeting-Einstellungen wie das KI-Paket hat.

Hinweis: KI-Pakete enthalten keine Java-/Kotlin- oder nativen Bibliotheken. Sie können Bibliotheken oder Code zum Ausführen Ihrer ML-Modelle in Funktionsmodulen bereitstellen.

LiteRT und MediaPipe mit KI-Packs verwenden

Sie können LiteRT und MediaPipe mit KI-Paketen verwenden. Verpacken Sie Ihr Modell in einem KI-Paket und greifen Sie dann gemäß der Anleitung für Install-time-Pakete oder für Fast-follow- und On-demand-Pakete darauf zu.

Weitere Informationen:

• Erste Schritte mit LiteRT
  • In der Beispiel-App wird gezeigt, wie Sie ein LiteRT-Modell in einem KI-Paket verpacken und zur Laufzeit laden.
  • Es gibt viele vortrainierte LiteRT-Modelle, die Sie in KI-Paketen verwenden können.
• Erste Schritte mit MediaPipe
  • Für Fast-Follow- und On-Demand-Packs können Sie AssetCache.java verwenden, um Ihre Assets zu laden (z. B. .binarypb-Dateien) anhand ihrer Dateipfade.
  • Für Installationszeit-Pakete können Sie AndroidAssetUtil.java verwenden.

Erste Schritte mit KI-Paketen

So können Sie Play for On-Device AI verwenden:

1. Verpacken Sie Ihre Modelle in KI-Pakete in Ihrem Android App Bundle und geben Sie an, wie die KI-Pakete bereitgestellt werden sollen.
2. [Optional] Wenn Sie verschiedene Modelle für verschiedene Geräte bereitstellen möchten, können Sie die Ausrichtung auf Geräte für Ihre KI-Pakete konfigurieren. Sie könnten beispielsweise KI-Paket A auf einem bestimmten Gerätemodell bereitstellen, KI-Paket B auf Geräten mit mindestens 6 GB RAM und auf allen anderen Geräten kein Modell.
3. [Optional] Wenn Sie die On-Demand- oder Fast-Follow-Bereitstellung verwenden, binden Sie die Play AI Delivery Library in Ihre App ein, um Ihre KI-Pakete nach Bedarf herunterzuladen.
4. Testen Sie Ihr App-Bundle und stellen Sie es bei Google Play bereit.

Version des Android-Gradle-Plug-ins prüfen

Damit Sie KI-Pakete verwenden können, muss die Version Ihres Android Gradle-Plug-ins (AGP) mindestens 8.8 sein. Diese Version ist in Android Studio Ladybug 2 enthalten.

Modell in ein KI-Paket extrahieren

Für die folgenden Schritte ist Android Studio nicht erforderlich.

1. Erstellen Sie im Verzeichnis der obersten Ebene Ihres Projekts ein Verzeichnis für das KI-Paket. Dieser Verzeichnisname wird als Name des KI-Pakets verwendet. Namen von KI-Paketen müssen mit einem Buchstaben beginnen und dürfen nur Buchstaben, Zahlen und Unterstriche enthalten.

2. Erstellen Sie im Verzeichnis des KI-Pakets eine build.gradle-Datei und fügen Sie den folgenden Code hinzu. Geben Sie den Namen des KI-Packs und nur einen Bereitstellungstyp an:

   // 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. Fügen Sie in der Datei build.gradle der App des Projekts den Namen jedes KI-Pakets in Ihrem Projekt ein, wie unten gezeigt:

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

4. Fügen Sie in die Datei settings.gradle des Projekts alle KI-Pakete in Ihrem Projekt ein, wie unten gezeigt:

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

5. Erstellen Sie in Ihrem KI-Paket ein src/main/assets/-Verzeichnis.

6. Platzieren Sie Ihre Modelle im Verzeichnis src/main/assets. Sie können hier auch Unterverzeichnisse erstellen. Die Verzeichnisstruktur für Ihre App sollte jetzt so aussehen:

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

7. Fügen Sie Code hinzu, um Ihre Modelle zu laden und auszuführen. Die Vorgehensweise hängt vom Übermittlungsmodus Ihrer KI-Pakete ab. Unten finden Sie eine Anleitung für install-time und fast-follow/on-demand.

8. [Optional] Geräte-Targeting konfigurieren, um verschiedene Modelle für verschiedene Geräte bereitzustellen.

9. Android App Bundle mit Gradle erstellen Im generierten App-Bundle enthält das Verzeichnis auf Stammebene jetzt Folgendes:

   • ai-pack-name/manifest/AndroidManifest.xml: Konfiguriert die Kennung und den Bereitstellungsmodus des KI‑Pakets.
   • ai-pack-name/assets/your-model-directories: Verzeichnis, das alle Assets enthält, die als Teil des KI-Pakets bereitgestellt werden

   Gradle generiert das Manifest für jedes KI-Paket und gibt das Verzeichnis assets/ aus.

Bereitstellung bei der Installation konfigurieren

Als „Install-time“ konfigurierte KI-Pakete sind beim Start der App sofort verfügbar. Verwenden Sie die Java AssetManager API, um auf KI-Pakete zuzugreifen, die in diesem Modus bereitgestellt werden:

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

Fast-Follow- und On-Demand-Bereitstellung konfigurieren

Wenn Sie KI-Pakete mit Fast-Follow- oder On-Demand-Bereitstellung herunterladen möchten, verwenden Sie die Play AI Delivery Library.

Abhängigkeit von der Play AI Delivery Library deklarieren

Deklarieren Sie in der build.gradle-Datei Ihrer App eine Abhängigkeit von der Play AI Delivery Library:

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

Status prüfen

Jedes KI-Paket wird im internen Speicher der App in einem separaten Ordner gespeichert. Verwenden Sie die Methode getPackLocation(), um den Stammordner eines KI-Pakets zu ermitteln. Diese Methode gibt die folgenden Werte zurück:

Rückgabewert	Status
Ein gültiges AiPackLocation-Objekt	Der Stammordner des KI-Pakets ist unter assetsPath() verfügbar.
null	Unbekanntes KI‑Paket oder KI‑Pakete nicht verfügbar

Hinweis :Verlassen Sie sich nicht auf zwischen App-Starts im Cache gespeicherte KI-Paketstandorte. Die App sollte bei jedem Start immer prüfen, ob KI-Pakete vorhanden sind. KI-Pakete können durch App-Updates oder wenn der Nutzer die App-Daten löscht ungültig werden.

Downloadinformationen zu KI-Paketen abrufen

Mit der Methode
getPackStates() können Sie die Größe des Downloads ermitteln und feststellen, ob das Paket bereits heruntergeladen wird.

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

getPackStates() ist eine asynchrone Methode, die eine Task<AiPackStates> zurückgibt. Die Methode packStates() eines AiPackStates-Objekts gibt einen Map<String, AiPackState> zurück. Diese Map enthält den Status jedes angeforderten KI-Pakets, das nach seinem Namen indexiert wird:

Map<String, AiPackState> AiPackStates#packStates()

Die endgültige Anfrage sieht so aus:

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;
            });

Die folgenden AiPackState-Methoden geben die Größe des KI-Pakets, die bisher heruntergeladene Menge (falls angefordert) und die bereits an die App übertragene Menge zurück:

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

Wenn Sie den Status eines KI‑Pakets abrufen möchten, verwenden Sie die Methode status(). Der Status wird als Ganzzahl zurückgegeben, die einem konstanten Feld in der Klasse AiPackStatus entspricht. Ein KI-Paket, das noch nicht installiert ist, hat den Status AiPackStatus.NOT_INSTALLED.

Wenn eine Anfrage fehlschlägt, verwenden Sie die Methode errorCode(), deren Rückgabewert einem konstanten Feld in der Klasse AiPackErrorCode entspricht.

Installieren

Verwenden Sie die Methode fetch(), um ein KI-Paket zum ersten Mal herunterzuladen oder ein Update eines KI-Pakets anzufordern:

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

Diese Methode gibt ein AiPackStates-Objekt mit einer Liste von Packs und ihren anfänglichen Downloadstatus und -größen zurück. Wenn ein über fetch() angefordertes KI‑Paket bereits heruntergeladen wird, wird der Downloadstatus zurückgegeben und kein zusätzlicher Download gestartet.

Hinweis :In den meisten Fällen implementieren Sie ein listener, um den Download- und Installationsprozess zu erfassen. Das wird im nächsten Abschnitt beschrieben.

Downloadstatus überwachen

Sie sollten ein AiPackStateUpdateListener implementieren, um den Installationsfortschritt von KI-Paketen zu erfassen. Die Statusaktualisierungen sind nach Paket aufgeschlüsselt, damit Sie den Status einzelner KI-Pakete verfolgen können. Sie können verfügbare KI‑Pakete verwenden, bevor alle anderen Downloads für Ihre Anfrage abgeschlossen sind.

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

Hinweis :Der Play Store löst den Download von fast-follow-Paketen automatisch aus, nachdem der Nutzer die App installiert oder aktualisiert hat. Diese Pakete sind jedoch möglicherweise nicht sofort einsatzbereit. Sie müssen den Status der fast-follow-Pakete bei jedem Start der App prüfen. Wenn der Download läuft, können Sie ihn mit einem Listener überwachen. Wenn der Download abgebrochen oder pausiert wird, können Sie ihn mit der Methode fetch() fortsetzen, wie im Abschnitt Installieren beschrieben.

Große Downloads

Wenn der Download größer als 200 MB ist und der Nutzer nicht mit einem WLAN verbunden ist, wird der Download erst gestartet, wenn der Nutzer ausdrücklich seine Einwilligung dazu gibt, den Download über eine mobile Datenverbindung fortzusetzen. Wenn der Download groß ist und der Nutzer die WLAN-Verbindung verliert, wird der Download pausiert. Für die Fortsetzung über eine mobile Datenverbindung ist eine ausdrückliche Einwilligung erforderlich. Ein pausiertes Paket hat den Status WAITING_FOR_WIFI. Verwenden Sie die Methode showConfirmationDialog(), um den UI-Ablauf auszulösen, in dem der Nutzer um Einwilligung gebeten wird.

Wenn die App diese Methode nicht aufruft, wird der Download pausiert und erst dann automatisch fortgesetzt, wenn der Nutzer wieder mit einem WLAN verbunden ist.

Erforderliche Nutzerbestätigung

Wenn ein Paket den Status REQUIRES_USER_CONFIRMATION hat, wird der Download erst fortgesetzt, wenn der Nutzer das Dialogfeld mit showConfirmationDialog() akzeptiert. Dieser Status kann auftreten, wenn die App von Google Play nicht erkannt wird, z. B. wenn sie per Sideload installiert wurde. Wenn Sie in diesem Fall showConfirmationDialog() aufrufen, wird die App aktualisiert. Nach dem Update müssen Sie die KI-Pakete noch einmal anfordern.

Im Folgenden finden Sie ein Beispiel für die Implementierung eines Listeners:

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;
      }
    }
}

Alternativ können Sie mit der Methode getPackStates() den Status aktueller Downloads abrufen. AiPackStates enthält den Downloadfortschritt, den Downloadstatus und alle Fehlercodes für Fehler.

Auf KI‑Pakete zugreifen

Sie können nach dem Herunterladen über Dateisystemaufrufe auf ein KI-Paket zugreifen, sobald der Downloadstatus COMPLETED erreicht ist. Mit der Methode getPackLocation() können Sie den Stammordner des KI-Pakets abrufen.

AI-Packs werden im Verzeichnis assets im Stammverzeichnis des AI-Packs gespeichert. Sie können den Pfad zum assets-Verzeichnis mit der Convenience-Methode assetsPath() abrufen. Verwenden Sie die folgende Methode, um den Pfad zu einem bestimmten Asset abzurufen:

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;
}

Ausrichtung auf Geräte konfigurieren

Folgen Sie der Anleitung zum Ausrichten auf Geräte, um Geräte oder Gerätegruppen anzugeben, die Ihre KI-Pakete erhalten sollen.

Weitere Play AI Delivery API-Methoden

Im Folgenden finden Sie einige zusätzliche API-Methoden, die Sie in Ihrer App verwenden können.

Anfrage abbrechen

Verwenden Sie cancel(), um eine aktive KI-Paketanfrage abzubrechen. Beachten Sie, dass diese Anfrage auf Best-Effort-Basis erfolgt.

AI Pack entfernen

Verwenden Sie removePack(), um das Entfernen eines KI-Pakets zu planen.

Standorte mehrerer KI‑Packs abrufen

Verwenden Sie getPackLocations(), um den Status mehrerer KI-Pakete gleichzeitig abzufragen. Dadurch wird eine Karte mit KI-Paketen und ihren Standorten zurückgegeben. Die von getPackLocations() zurückgegebene Karte enthält einen Eintrag für jedes Paket, das derzeit heruntergeladen und auf dem neuesten Stand ist.

Ausrichtung auf Geräte

Mit der Ausrichtung auf Geräte können Sie genauer steuern, welche Teile Ihres App-Bundles auf bestimmten Geräten bereitgestellt werden. So können Sie beispielsweise dafür sorgen, dass ein großes Modell nur auf Geräten mit viel RAM bereitgestellt wird, oder verschiedene Versionen eines Modells auf verschiedenen Geräten bereitstellen.

Sie können die Ausrichtung auf Geräteattribute wie die folgenden vornehmen:

• System-on-a-Chip
• Gerätemodell
• Geräte-RAM
• Systemfunktionen

Erforderliche Schritte

So aktivieren Sie die Geräteausrichtung:

1. Definieren Sie Ihre Gerätegruppen in einer XML-Datei.
2. Geben Sie an, welche Teile Ihres Bundles an welche Gerätegruppen gesendet werden sollen.
3. [Optional] Konfiguration lokal testen
4. Laden Sie Ihr Bundle (mit der XML-Datei) bei Google Play hoch.

Version des Android-Gradle-Plug-ins prüfen

Wenn Sie die Geräteausrichtung verwenden möchten, muss die Version Ihres Android Gradle-Plug-ins (AGP) mindestens 8.10.0 sein. Es ist in Android Studio (Meerkat 2 und höher) enthalten. Laden Sie die aktuelle stabile Version von Android Studio herunter.

Funktion im Android-Gradle-Plug-in aktivieren

Das Gerätetargeting muss explizit in Ihrer gradle.properties-Datei aktiviert werden:

android.experimental.enableDeviceTargetingConfigApi=true

XML-Datei für die Geräteausrichtung erstellen

Die Konfigurationsdatei für die Geräteausrichtung ist eine XML-Datei, in der Sie Ihre benutzerdefinierten Gerätegruppen definieren. Sie könnten beispielsweise eine Gerätegruppe namens qti_v79 definieren, die alle Geräte mit dem Qualcomm SM8750-System-on-Chip enthält:

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

Eine Gerätegruppe besteht aus bis zu fünf Geräteauswahlen. Ein Gerät gehört zu einer Gerätegruppe, wenn es einen der Geräte-Selektoren erfüllt.

Eine Geräteauswahl kann eine oder mehrere Geräte-Properties haben. Ein Gerät wird ausgewählt, wenn es mit allen Geräteattributen des Selektors übereinstimmt.

Wenn ein Gerät mehreren Gruppen entspricht, werden die Inhalte für die Gruppe bereitgestellt, die in der XML-Datei zuerst definiert ist. Die Reihenfolge, in der Sie Gruppen in der XML-Datei definieren, ist die Prioritätsreihenfolge.

Wenn ein Gerät keiner Gruppe entspricht, wird es der Standardgruppe „Andere“ zugewiesen. Diese Gruppe wird automatisch generiert und sollte nicht explizit definiert werden.

Verfügbare Geräteeigenschaften

• device_ram: RAM-Anforderungen des Geräts
  • min_bytes (inklusiv): Mindestanforderung an den RAM (in Byte)
  • max_bytes (exklusiv): Maximal erforderlicher RAM (in Byte)
• included_device_ids: Geräte, die in diesen Selektor aufgenommen werden sollen (maximal 10.000 device_ids pro Gruppe). Diese Eigenschaft ist erfüllt, wenn das Gerät mit einer device_id in der Liste übereinstimmt.
  • build_brand: Gerätehersteller
  • build_device: Gerätemodellcode
• excluded_device_ids: Geräte-IDs, die in dieser Auswahl ausgeschlossen werden sollen (maximal 10.000 device_ids pro Gruppe). Diese Eigenschaft ist erfüllt, wenn das Gerät keiner device_id in der Liste entspricht.
  • build_brand: Gerätehersteller
  • build_device: Gerätemodellcode

• required_system_features: Funktionen, die ein Gerät haben muss, damit es von diesem Selektor berücksichtigt wird (maximal 100 Funktionen pro Gruppe). Ein Gerät muss alle Systemfunktionen in dieser Liste haben, um diese Eigenschaft zu erfüllen.

  Referenz zu Systemfunktionen

  • name: Eine Systemfunktion

• forbidden_system_features: Funktionen, die ein Gerät nicht haben darf, um von dieser Auswahl berücksichtigt zu werden (maximal 100 Funktionen pro Gruppe). Wenn ein Gerät eine der Systemfunktionen in dieser Liste hat, erfüllt es diese Eigenschaft nicht.

  Referenz zu Systemfunktionen

  • name: Eine Systemfunktion

• system-on-chip: Systems-on-a-Chip, die in diese Auswahl aufgenommen werden sollen. Ein Gerät muss einen Chip aus dieser Liste haben, um diese Property zu erfüllen.

  • manufacturer: Hersteller des System-on-a-Chip
  • model: System-on-a-Chip-Modell

Tipp:Wenn Sie mehrere Attribute in einen einzelnen Selektor einfügen, wird eine logische UND-Verknüpfung erstellt. Beispiel:

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

wird die Bedingung für alle Geräte mit mehr als 7 GB RAM UND für das Pixel 4 erstellt, also:

Wenn Sie eine OR-Bedingung verwenden möchten, erstellen Sie separate Selektoren in einer einzelnen Gerätegruppe, z. B.:

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

wird die Bedingung für alle Geräte mit > 7 GB RAM ODER für das Pixel 4 erstellt, was auch so geschrieben werden kann:

Hier ist ein Beispiel mit allen möglichen Geräte-Properties:

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

Offizielle Codes für Gerätehersteller und Gerätemodelle

Die richtige Formatierung für den Gerätehersteller und den Modellcode finden Sie im Gerätekatalog der Google Play Console. Dazu haben Sie folgende Möglichkeiten:

• Einzelne Geräte im Geräte-Katalog prüfen und den Hersteller- und Modellcode an den Stellen suchen, die im Beispiel unten gezeigt werden (bei einem Google Pixel 4a ist der Hersteller „Google“ und der Modellcode „sunfish“).

  

  

• Laden Sie eine CSV-Datei mit unterstützten Geräten herunter und verwenden Sie Manufacturer (Hersteller) und Model Code (Modellcode) für die Felder build_brand (build_brand) bzw. build_device (build_device).

Konfigurationsdatei für die Ausrichtung auf Geräte in Ihr App-Bundle aufnehmen

Fügen Sie der Datei build.gradle Ihres Hauptmoduls Folgendes hinzu:

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 ist der Pfad Ihrer Konfigurationsdatei relativ zum Hauptmodul. So wird sichergestellt, dass Ihre Konfigurationsdatei in Ihr App-Bundle aufgenommen wird.

Die deviceGroup-Klausel sorgt dafür, dass die aus Ihrem Bundle generierten APKs nach Gerätegruppen aufgeteilt werden.

Ausrichtung auf Geräte für KI-Pakete verwenden

Sie können die Größe auf Geräten optimieren, indem Sie Ihre großen Modelle nur auf Geräten bereitstellen, auf denen sie ausgeführt werden können.

Unterteilen Sie Ihre KI-Pakete nach Gerätegruppen, indem Sie die vorhandenen KI-Paketverzeichnisse aus dem letzten Schritt verwenden und die entsprechenden Ordner (wie unten beschrieben) mit #group_myCustomGroup1, #group_myCustomGroup2 usw. versehen. Wenn Sie die KI-Pakete in Ihrer App verwenden, müssen Sie Ordner nicht nach Postfix adressieren. Das Postfix wird also während des Build-Prozesses automatisch entfernt.

Nach dem vorherigen Schritt könnte das so aussehen:

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

In diesem Beispiel würden Sie ohne Postfixe auf ai-pack-name/assets/image-classifier/ verweisen.

Geräte in myCustomGroup1 erhalten alle Assets unter image-classifier#group_myCustomGroup1/, während Geräte in myCustomGroup2 alle Assets unter image-classifier#group_myCustomGroup2/ erhalten.

Geräte, die weder zu myCustomGroup1 noch zu myCustomGroup2 gehören, erhalten ein leeres ai-pack-name-Paket.

Das liegt daran, dass Geräte, die keiner Gerätegruppe entsprechen, die Standardvariante Ihres KI‑Pakets erhalten. Dazu gehört alles, was sich nicht in einem Verzeichnis mit einer #group_suffix befindet.

Nachdem Sie das KI-Paket heruntergeladen haben, können Sie mit dem AssetManager für Pakete, die bei der Installation heruntergeladen werden, oder mit dem AiPackManager für Fast-Follow- und On-Demand-Pakete prüfen, ob Ihr Modell vorhanden ist. Beispiele dafür finden Sie für alle Auslieferungsmodi in der Beispiel-App.

Wichtig :Es ist nicht möglich, die Auslieferung aller Varianten Ihres KI-Pakets an bestimmte Geräte zu verhindern. Auf nicht ausgerichteten Geräten wird immer die Standardvariante angezeigt.

Geräte-Targeting für Funktionsmodule verwenden

Sie können das Geräte-Targeting auch für Funktionsmodule verwenden. Anstatt Feature-Module nach Gerätegruppe zu unterteilen, geben Sie an, ob das gesamte Modul basierend auf der Gerätegruppenzugehörigkeit ausgeliefert werden soll.

Wenn Sie ein Funktionsmodul auf Geräten bereitstellen möchten, die entweder zu myCustomGroup1 oder myCustomGroup2 gehören, ändern Sie das zugehörige 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>

Hinweis :Geräte, die nicht als Zielgeräte festgelegt sind, erhalten das Funktionsmodul überhaupt nicht. Das unterscheidet sich vom Targeting für KI-Pakete, bei dem Geräte, die nicht als Zielgruppe festgelegt sind, eine leere Standardvariante des KI-Pakets erhalten.

Lokal testen

Bevor Sie ein Release für Ihr neues Bundle erstellen, können Sie es lokal mit der internen App-Freigabe oder mit Bundletool testen.

Interne App-Freigabe

Mit der internen App-Freigabe können Sie schnell eine URL aus einem App-Bundle generieren, die Sie auf einem lokalen Gerät antippen können, um genau das zu installieren, was Google Play für dieses Gerät installieren würde, wenn diese Version der App in einem Test- oder Produktions-Track verfügbar wäre.

Weitere Informationen zur internen App-Freigabe

Bundletool

Alternativ können Sie APKs mit bundletool (1.18.0 oder höher) generieren und auf Ihr Gerät sideloaden. So testen Sie Ihre App lokal mit Bundletool:

1. Erstellen Sie Ihr App Bundle mit Android Studio oder Bundletool.

2. Generieren Sie APKs mit dem Flag --local-testing:

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

3. Verbinden Sie ein Gerät und führen Sie bundletool aus, um die APKs per Sideloading zu installieren:

   # 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
   

Einschränkungen beim lokalen Testen mit Bundletool

Im Folgenden sind die Einschränkungen für lokale Tests mit Bundletool aufgeführt:

• fast-follow-Pakete verhalten sich wie on-demand-Pakete. Das bedeutet, dass sie nicht automatisch abgerufen werden, wenn die App per Sideloading installiert wird. Entwickler müssen sie beim Start der App manuell anfordern. Dazu sind keine Codeänderungen in Ihrer App erforderlich.
• Pakete werden aus dem externen Speicher anstatt von Play abgerufen. Sie können also nicht testen, wie sich Ihr Code bei Netzwerkfehlern verhält.
• Das Szenario „Auf WLAN warten“ wird bei lokalen Tests nicht abgedeckt.
• Aktualisierungen werden nicht unterstützt. Bevor Sie eine neue Version Ihres Builds installieren, müssen Sie die vorherige Version manuell deinstallieren.

Prüfen, ob die richtigen APKs installiert werden

Mit der folgenden Methode können Sie dafür sorgen, dass nur die richtigen APKs auf dem Gerät installiert werden.

adb shell pm path {packageName}

Die Ausgabe sollte etwa so aussehen:

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

In dieser Liste werden nur APKs angezeigt, die aus Funktionsmodulen und AI-Packs für die Zeit der Installation erstellt wurden. On-Demand- und Fast-Follow-KI-Pakete werden nicht als APKs installiert.

Bei Google Play testen und veröffentlichen

Wir empfehlen, Ihre App bei Google Play mit einem internen Testtrack zu testen.

Anschließend können Sie Ihr App-Update mit gestaffelten Roll-outs schrittweise in der Produktion veröffentlichen.

Beispiel-App mit Play for On-Device AI

Laden Sie die Beispielanwendung herunter.

Darin wird gezeigt, wie die einzelnen Bereitstellungsmodi und die Geräteausrichtungskonfiguration verwendet werden. Weitere Informationen finden Sie im Abschnitt Lokale Tests.

Weitere Informationen

Weitere Informationen zu Android App Bundles und Referenzen für das AI Delivery SDK