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 mit weniger Komplexität im Geräte-Ökosystem ohne zusätzliche Kosten verbessern. Damit kannst du ein einzelnes Artefakt mit deinem Code, deinen Assets und deinen ML-Modellen bei Google Play veröffentlichen und aus einer Reihe von Bereitstellungsmodi und Targeting-Optionen auswählen.

Vorteile

  • Lade ein einzelnes Veröffentlichungsartefakt in Google Play hoch und überlasse Hosting, Bereitstellung, Updates und Targeting Google Play – ohne zusätzliche Kosten.
  • Du kannst deine ML‑Modelle bei der Installation, als Fast-Follow-Download oder on demand bereitstellen.
    • Durch die Bereitstellung bei der Installation kann sichergestellt werden, dass ein sehr großes Modell vorhanden ist, wenn Ihre App geöffnet wird. Ihr Modell wird als APK installiert.
    • Die Fast-Follow-Bereitstellung erfolgt automatisch im Hintergrund, nachdem deine App installiert wurde. Nutzer können Ihre App öffnen, bevor Ihr Modell vollständig heruntergeladen wurde. Das Modell wird in den internen Speicherplatz Ihrer App heruntergeladen.
    • Mit der On-Demand-Bereitstellung können Sie das Modell zur Laufzeit anfordern. Das ist nützlich, wenn das Modell nur für bestimmte User-Flows erforderlich ist. Ihr Modell wird in den internen Speicher Ihrer App heruntergeladen.
  • Stelle Varianten deiner ML-Modelle bereit, die auf bestimmte Geräte ausgerichtet sind, basierend auf Gerätemodell, Systemeigenschaften oder RAM.
  • Mit dem automatischen Patching von Google Play kannst du App-Updates klein und optimiert halten. Das bedeutet, dass nur die Unterschiede in den Dateien heruntergeladen werden müssen.

Hinweise

  • Durch die Verwendung von Play für On-Device-KI stimmst du den Bedingungen der Google Play-Vertriebsvereinbarung für Entwickler und den Nutzungsbedingungen für das Play Core Software Development Kit zu.
  • Von Google Play für On-Device-KI heruntergeladene Modelle dürfen nur von Ihren Apps verwendet werden. Modelle sollten nicht für andere Apps angeboten werden.
  • Einzelne KI-Pakete können basierend auf ihrer komprimierten Downloadgröße bis zu 1, 5 GB groß sein. Die maximale kumulative App-Größe einer Version Ihrer App, die aus Ihrem App-Bundle generiert wird, beträgt 4 GB.
  • Bei Apps mit einer Größe von mehr als 1 GB muss das SDK-Mindestlevel auf 21 oder höher festgelegt werden.

Play for On‑Device AI verwenden

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

Wenn Sie KI-Pakete in Ihr App-Bundle packen, können Sie alle vorhandenen Test- und Release-Tools von Google Play wie Test-Tracks und gestaffelte Roll-outs verwenden, um die Bereitstellung Ihrer App mit Ihren benutzerdefinierten Modellen zu verwalten.

KI-Pakete werden zusammen mit der App-Binärdatei aktualisiert. Wenn Ihr neues App-Release keine Änderungen an einem KI-Paket vornimmt, sorgt der automatische Patchvorgang von Google Play dafür, dass der Nutzer es nicht noch einmal herunterladen muss. Google Play lädt nur die Änderungen herunter, wenn die App aktualisiert wird.

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

LiteRT und MediaPipe mit KI-Paketen verwenden

Sie können LiteRT und MediaPipe mit AI Packs verwenden. Verpacken Sie Ihr Modell in einem KI-Paket und greifen Sie dann darauf zu. Folgen Sie dazu der Anleitung für Installationszeitpakete oder für Fast-Follow- und On-Demand-Pakete.

Weitere Informationen:

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 das Geräte-Targeting für Ihre KI-Pakete konfigurieren. Sie können beispielsweise KI-Paket A an ein bestimmtes Gerätemodell und KI-Paket B an Geräte mit mindestens 6 GB RAM senden. Alle anderen Geräte erhalten 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 veröffentlichen Sie es bei Google Play.

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

Wenn Sie AI Packs verwenden möchten, 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 AI-Pack extrahieren

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

  1. Erstellen Sie im obersten Verzeichnis Ihres Projekts ein Verzeichnis für das AI Pack. Dieser Verzeichnisname wird als Name des KI-Pakets verwendet. Namen von KI-Paketen müssen mit einem Buchstaben beginnen und dürfen nur Buchstaben, Ziffern 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 Anwendung des Projekts den Namen jedes KI-Pakets in Ihrem Projekt hinzu, wie unten gezeigt:

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

  4. Fügen Sie in der Datei settings.gradle des Projekts alle KI-Pakete in Ihr 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 AI Pack ein src/main/assets/-Verzeichnis.

  6. Platzieren Sie Ihre Modelle im Verzeichnis src/main/assets. Sie können hier auch Unterverzeichnisse erstellen. Die Verzeichnisstruktur Ihrer Anwendung 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. Wie Sie das tun, hängt vom Bereitstellungsmodus Ihrer KI-Pakete ab. Eine Anleitung für Installationszeitpunkt und Fast-Follow/On-Demand finden Sie unten.

  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 im Rahmen des KI-Pakets bereitgestellt werden

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

Auslieferung bei der Installation konfigurieren

KI-Pakete, die für die Installation bei der Installation konfiguriert sind, sind sofort beim Start der App 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-Auslieferung 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 Datei build.gradle Ihrer App eine Abhängigkeit von der Play AI Delivery-Bibliothek:

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

Status prüfen

Jedes KI-Paket wird in einem separaten Ordner im internen Speicher der App 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() sofort verfügbar
null Unbekanntes KI‑Paket oder KI‑Pakete sind nicht verfügbar

Downloadinformationen zu KI-Paketen abrufen

Verwende die Methode
getPackStates(), um die Größe des Downloads zu ermitteln und festzustellen, ob das Paket bereits heruntergeladen wird.

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

getPackStates() ist eine asynchrone Methode, die ein Task<AiPackStates> zurückgibt. Die Methode packStates() eines AiPackStates-Objekts gibt ein Map<String, AiPackState> zurück. Diese Zuordnung enthält den Status jedes angeforderten KI-Pakets, sortiert nach Name:

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

Verwenden Sie die Methode status(), um den Status eines KI-Pakets abzurufen. Sie gibt den Status als Ganzzahl zurück, 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 die Aktualisierung eines KI-Pakets abzuschließen:

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

Diese Methode gibt ein AiPackStates-Objekt zurück, das eine Liste der Pakete und deren anfänglichen Downloadstatus und -größen enthält. Wenn ein über fetch() angefordertes KI-Paket bereits heruntergeladen wird, wird der Downloadstatus zurückgegeben und kein zusätzlicher Download gestartet.

Downloadstatus überwachen

Sie sollten einen AiPackStateUpdateListener implementieren, um den Installationsfortschritt von KI-Paketen zu verfolgen. Die Statusaktualisierungen werden pro Paket aufgeschlüsselt, um den Status einzelner KI-Pakete zu verfolgen. 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)
Große Downloads

Wenn der Download größer als 200 MB ist und der Nutzer nicht mit dem WLAN verbunden ist, wird der Download erst gestartet, wenn der Nutzer ausdrücklich zustimmt, den Download über eine mobile Datenverbindung fortzusetzen. Wenn der Download groß ist und der Nutzer die WLAN-Verbindung verliert, wird der Download ebenfalls pausiert. Es ist dann eine ausdrückliche Einwilligung erforderlich, um den Download über eine mobile Datenverbindung fortzusetzen. Ein pausiertes Paket hat den Status WAITING_FOR_WIFI. Verwenden Sie die Methode showConfirmationDialog(), um den UI-Ablauf auszulösen, über den der Nutzer zur Einwilligung aufgefordert 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 akzeptiert, das mit showConfirmationDialog() angezeigt wird. Dieser Status kann auftreten, wenn die App von Google Play nicht erkannt wird, z. B. wenn die App per Sideload installiert wurde. Wenn du in diesem Fall showConfirmationDialog() aufrufst, wird die App aktualisiert. Nach dem Update müssen Sie die KI-Pakete noch einmal anfordern.

Hier 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 die Methode getPackStates() verwenden, um den Status aktueller Downloads abzurufen. AiPackStates enthält den Downloadfortschritt, den Downloadstatus und alle Fehlercodes.

Auf KI‑Pakete zugreifen

Sie können über Dateisystemaufrufe auf ein KI-Paket zugreifen, nachdem die Downloadanfrage den Status COMPLETED erreicht hat. Verwenden Sie die Methode getPackLocation(), um den Stammordner des KI-Pakets abzurufen.

AI Packs werden im Verzeichnis assets im Stammverzeichnis des AI Packs gespeichert. Den Pfad zum Verzeichnis assets können Sie mit der praktischen 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;
}

Geräte-Targeting konfigurieren

Folge der Anleitung zum Geräte-Targeting, um Geräte oder Gerätegruppen anzugeben, die deine KI-Pakete erhalten sollen.

Weitere Methoden der Play AI Delivery API

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 Anfrage für ein KI-Paket abzubrechen. Beachten Sie, dass diese Anfrage ein Best-Effort-Vorgang ist.

KI-Pack entfernen

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

Standorte mehrerer AI-Packs abrufen

Mit getPackLocations() können Sie den Status mehrerer KI-Pakete gleichzeitig abfragen. Dadurch erhalten Sie eine Zuordnung der KI-Pakete und ihrer Standorte. Die von getPackLocations() zurückgegebene Zuordnung enthält einen Eintrag für jedes Paket, das derzeit heruntergeladen und auf dem neuesten Stand ist.

Ausrichtung auf Geräte

Mit dem Geräte-Targeting können Sie genauer steuern, welche Teile Ihres App-Bundles auf bestimmten Geräten bereitgestellt werden. Sie können 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äteeigenschaften wie die folgenden festlegen:

Übersicht über die erforderlichen Schritte

So aktivieren Sie das Geräte-Targeting:

  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] Testen Sie Ihre Konfiguration lokal.
  4. Laden Sie Ihr Bundle (mit der XML-Datei) bei Google Play hoch.

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

Wenn Sie das Geräte-Targeting verwenden möchten, muss die Version Ihres Android-Gradle-Plug-ins (AGP) mindestens 8.10.0 sein. Diese 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äte-Targeting muss explizit in der Datei gradle.properties aktiviert werden:

android.experimental.enableDeviceTargetingConfigApi=true

XML-Datei für die Geräte-Targeting-Konfiguration erstellen

Die Konfigurationsdatei für das Geräte-Targeting ist eine XML-Datei, in der Sie Ihre benutzerdefinierten Gerätegruppen definieren. Sie können beispielsweise eine Gerätegruppe mit dem Namen qti_v79 definieren, die alle Geräte mit dem Qualcomm SM8750-System-on-a-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 5 Geräteauswahlen. Ein Gerät wird in eine Gerätegruppe aufgenommen, wenn es eine der Geräteauswahlkriterien erfüllt.

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

Wenn ein Gerät mehreren Gruppen entspricht, werden ihm 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 zugeordnet werden kann, wird es der Standardgruppe „Sonstige“ 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 (einschließlich): Erforderlicher Mindest-RAM (in Byte)
    • max_bytes (exklusiv): Maximal erforderlicher RAM (in Byte)
  • included_device_ids: Gerätemodelle, die in diese Auswahl einbezogen werden sollen (maximal 10.000 device_ids pro Gruppe). Diese Eigenschaft ist erfüllt, wenn das Gerät mit einer beliebigen device_id in der Liste übereinstimmt.
    • build_brand: Gerätehersteller
    • build_device: Gerätemodellcode
  • excluded_device_ids: Gerätemodelle, die in dieser Auswahl ausgeschlossen werden sollen (maximal 10.000 device_ids pro Gruppe). Dieses Attribut ist erfüllt, wenn das Gerät mit keiner device_id in der Liste übereinstimmt.
    • build_brand: Gerätehersteller
    • build_device: Gerätemodellcode

  • required_system_features: Funktionen, die ein Gerät haben muss, um von dieser Auswahl berücksichtigt zu werden (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: System-on-a-Chips, die in diese Auswahl einbezogen werden sollen. Ein Gerät muss einen Chip aus dieser Liste haben, um diese Property zu erfüllen.

Hier ein Beispiel mit allen möglichen Geräteeigenschaften:

<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 in der Google Play Console. Gehen Sie dazu so vor:

  • Einzelne Geräte im Gerätekatalog prüfen und den Hersteller und Modellcode an den Stellen finden, die im Beispiel unten gezeigt werden (für ein Google Pixel 4a ist der Hersteller „Google“ und der Modellcode „sunfish“)

    Pixel 4a-Seite im Gerätekatalog

    Pixel 4a-Seite im Gerätekatalog

  • Lade eine CSV-Datei mit unterstützten Geräten herunter und verwende die Werte aus den Spalten Manufacturer und Model Code für die Felder build_brand und build_device.

Konfigurationsdatei für das Geräte-Targeting in Ihr App-Bundle einfügen

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 mit Ihrem App-Bundle verpackt wird.

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

Geräte-Targeting für KI-Pakete verwenden

Du kannst die Größe auf Geräten optimieren, indem du deine großen Modelle nur auf Geräten bereitstellst, auf denen sie ausgeführt werden können.

Unterteilen Sie Ihre KI-Pakete nach Gerätegruppen, indem Sie die im letzten Schritt erstellten vorhandenen KI-Paketverzeichnisse 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 die Ordner nicht mit einem Postfix versehen. Das Postfix wird 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 ai-pack-name/assets/image-classifier/ ohne Postfixe referenzieren.

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 hierfür finden Sie für alle Bereitstellungsmodi in der Beispiel-App.

Geräte-Targeting für Funktionsmodule verwenden

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

Wenn du ein Funktionsmodul auf Geräten bereitstellen möchtest, die entweder zu myCustomGroup1 oder myCustomGroup2 gehören, ändere die 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>

Lokal testen

Bevor Sie einen 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 kannst du mithilfe eines App-Bundles schnell eine URL generieren, die du auf einem lokalen Gerät antippen kannst, 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 live wäre.

Sehen Sie sich die Anleitung zur internen App-Freigabe an.

Bundletool

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

  1. Erstelle dein 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 Sideload 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 bei lokalen Tests mit bundletool

Für lokale Tests mit bundletool gelten die folgenden Einschränkungen:

  • 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 einem externen Speicher und nicht von Google Play abgerufen. Sie können also nicht testen, wie sich Ihr Code bei Netzwerkfehlern verhält.
  • Lokale Tests decken das Szenario „Auf WLAN warten“ nicht ab.
  • Aktualisierungen werden nicht unterstützt. Deinstallieren Sie die vorherige Version manuell, bevor Sie eine neue Version Ihres Builds installieren.

Prüfen, ob die richtigen APKs installiert werden

Verwenden Sie die folgende Methode, um sicherzustellen, dass nur die richtigen APKs auf dem Gerät installiert werden.

adb shell pm path {packageName}

Sie 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 KI-Paketen für die Installation erstellt wurden. On-Demand- und Fast-Follow-KI-Pakete werden nicht als APKs installiert.

Testen und veröffentlichen bei Google Play

Wir empfehlen, die App mit einem internen Test-Track umfassend bei Google Play 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 Beispiel-App herunter.

Es wird gezeigt, wie die einzelnen Übermittlungsmodi und die Geräte-Targeting-Konfiguration verwendet werden. Weitere Informationen finden Sie im Abschnitt Lokale Tests.

Weitere Informationen

Weitere Informationen zu Android App Bundles und Referenzen zum AI Delivery SDK