Early Access-Programm (EAP) für On-Device-KI

Einführung

Play for On-Device AI bietet die Vorteile von Android App Bundles und der Google Play-Bereitstellung für die Bereitstellung benutzerdefinierter ML-Modelle. So können Sie die Modellleistung bei weniger Komplexität des Systems ohne zusätzliche Kosten verbessern. Sie können damit 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 Hosting, Bereitstellung, Updates und Targeting kostenlos an Google Play delegieren.
  • Sie können Ihre ML-Modelle bei der Installation, per Fast-Follow oder On-Demand bereitstellen.
    • Wenn die Bereitstellung zur Installationszeit erfolgt, ist sichergestellt, dass ein sehr großes Modell vorhanden ist, wenn Ihre App geöffnet wird. Ihr Modell wird als APK installiert.
    • Die Fast-Follow-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-Auslieferung können Sie das Modell zur Laufzeit anfordern. Das ist nützlich, wenn das Modell nur für bestimmte Nutzerflüsse erforderlich ist. Ihr Modell wird in den internen Speicher 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 den automatischen Patches von Google Play können Sie App-Updates klein und optimiert halten. Das bedeutet, dass nur die Unterschiede zwischen den Dateien heruntergeladen werden müssen.

Wissenswertes

  • Wenn Sie Play for On-Device AI verwenden, stimmen Sie den Bestimmungen in der Vertriebsvereinbarung für Entwickler bei Google Play und den Nutzungsbedingungen für das Play Core Software Development Kit zu.
  • Entwickler, die am Early-Access-Programm teilnehmen, werden gebeten, Google Play für On-Device-KI zu bewerten und Feedback zu Google Play zu geben.
  • Von Google Play für On-Device-KI heruntergeladene Modelle können nur von der App verwendet werden, über die sie heruntergeladen wurden. Modelle dürfen nicht für andere Apps angeboten werden, z. B. über eine Dienstverbindung.
  • Einzelne KI-Modelle können je nach komprimierter Downloadgröße bis zu 1, 5 GB groß sein. Die maximale kumulative App-Größe jeder Version Ihrer App, die aus Ihrem App-Bundle generiert wird, beträgt 4 GB.
  • Für Apps mit einer Größe von mehr als 1 GB muss die Mindest-SDK-Version auf 21 oder höher festgelegt sein.
  • Während des Early-Access-Programms kann sich Play for On-Device AI ändern.

Play for On-Device AI verwenden

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

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

KI-Pakete werden zusammen mit dem App-Binärprogramm aktualisiert. Wenn mit der neuen App-Version keine Änderungen an einem KI-Paket vorgenommen werden, sorgt der automatische Patch-Prozess von Google Play dafür, dass der Nutzer es nicht noch einmal herunterladen muss. Google Play lädt beim Aktualisieren der App nur die geänderten Dateien 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 das 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 KI-Paketen verwenden. Verpacken Sie Ihr Modell in einem KI-Paket und greifen Sie dann mithilfe der Anleitung für Install-Time-Pakete oder Fast-Follow- und On-Demand-Pakete darauf zu.

Weitere Informationen:

Erste Schritte mit KI-Paketen

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

  1. Geben Sie Ihre Google Play-Entwicklerkonto-ID an, um am EAP teilzunehmen.
  2. Verpacken Sie Ihre Modelle in KI-Paketen in Ihrem Android App-Bundle und geben Sie an, wie die KI-Pakete bereitgestellt werden sollen.
  3. [Optional] Wenn Sie verschiedene Modelle auf verschiedenen Geräten bereitstellen möchten, können Sie das Geräte-Targeting für Ihre KI-Modelle konfigurieren. So können Sie beispielsweise KI-Paket A für ein bestimmtes Gerätemodell, KI-Paket B für Geräte mit mindestens 6 GB RAM und alle anderen Geräte ohne Modell bereitstellen.
  4. [Optional] Wenn Sie die On-Demand- oder Fast-Follow-Bereitstellung verwenden, integrieren Sie die Play AI Delivery Library in Ihre App, um Ihre KI-Pakete bei Bedarf herunterzuladen.
  5. Testen Sie Ihr App-Bundle und veröffentlichen Sie es bei Google Play.

Geben Sie die ID Ihres Google Play-Entwicklerkontos an.

Da sich diese Funktion noch im Early Access befindet, muss Ihr Entwicklerkonto auf die Zulassungsliste gesetzt werden, damit Sie auf Play für On-Device-KI zugreifen können. Bestätigen Sie die Google Play-Entwicklerkonto-IDs und App-Paketnamen gegenüber Ihrem Google Play-Partnermanager oder einem Mitglied des Google Play-Teams für On-Device-KI. Geben Sie an, ob Sie Ihre Modelle auf bestimmte Geräte ausrichten möchten (Schritt 3 aus dem vorherigen Abschnitt). Derzeit laden wir ausgewählte Play-Partner ein, diese Funktion zu testen.

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 Stammverzeichnis 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, 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-Pakets und nur einen Übermittlungstyp 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 build.gradle-Datei der App 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 im AI-Paket ein src/main/assets/-Verzeichnis.

  6. Platzieren Sie Ihre Modelle im Verzeichnis src/main/assets. Hier können Sie auch Unterverzeichnisse erstellen. Die Verzeichnisstruktur Ihrer 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. Wie Sie das tun, hängt vom Übermittlungsmodus Ihrer KI-Pakete ab. Eine Anleitung für Installationszeit und schnelles Folgen/On-Demand findest du unten.

  8. [Optional] Konfiguriere das Geräte-Targeting, um verschiedene Modelle auf verschiedenen Geräten auszuliefern.

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

    • ai-pack-name/manifest/AndroidManifest.xml: Konfiguriert die Kennung und den Übermittlungsmodus des KI-Pakets
    • ai-pack-name/assets/your-model-directories: Verzeichnis mit allen Assets, die im Rahmen des KI-Pakets bereitgestellt werden

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

Bereitstellung zur Installationszeit konfigurieren

KI-Pakete, die für die Installation konfiguriert sind, sind beim Start der App sofort verfügbar. Verwende 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 du KI-Pakete mit Fast-Follow- oder On-Demand-Bereitstellung herunterladen möchtest, verwende 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 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 zugänglich.
null Unbekanntes KI-Paket oder KI-Pakete nicht verfügbar

Informationen zum Herunterladen von KI-Paketen abrufen

Mit der Methode
getPackStates() kannst du die Größe des Downloads und ob das Paket bereits heruntergeladen wird, ermitteln.

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 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, den bisher heruntergeladenen Umfang (falls angefordert) und den bereits in die App übertragenen Umfang an:

Verwenden Sie die Methode status(), um den Status eines KI-Pakets abzurufen. Sie gibt den Status als Ganzzahl zurück, die einem Konstantenfeld in der Klasse AiPackStatus entspricht. Ein KI-Paket, das noch nicht installiert ist, hat den Status AiPackStatus.NOT_INSTALLED.

Wenn eine Anfrage fehlschlägt, verwende 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 das Aktualisieren eines KI-Pakets abzuschließen:

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

Diese Methode gibt ein AiPackStates-Objekt zurück, das eine Liste von Paketen und ihre ursprü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 beobachten

Sie sollten einen AiPackStateUpdateListener implementieren, um den Installationsfortschritt von KI-Paketen zu verfolgen. Die Statusaktualisierungen sind nach Paket aufgeschlüsselt, damit Sie den Status einzelner KI-Pakete verfolgen können. Sie können verfügbare KI-Modelle 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 keine WLAN-Verbindung hat, wird der Download erst gestartet, wenn der Nutzer ausdrücklich seine Einwilligung zum Fortsetzen des Downloads über eine mobile Datenverbindung erteilt. Wenn der Download groß ist und die WLAN-Verbindung des Nutzers unterbrochen wird, wird der Download pausiert und es ist eine ausdrückliche Einwilligung erforderlich, um mit einer mobilen Datenverbindung fortzufahren. Ein pausiertes Paket hat den Status WAITING_FOR_WIFI. Verwenden Sie die Methode showConfirmationDialog(), um den UI-Ablauf auszulösen, bei dem der Nutzer um seine Einwilligung gebeten wird.

Wenn die App diese Methode nicht aufruft, wird der Download pausiert und erst dann fortgesetzt, wenn der Nutzer wieder eine WLAN-Verbindung hat.

Erforderliche Nutzerbestätigung

Wenn ein Paket den Status REQUIRES_USER_CONFIRMATION hat, wird der Download erst fortgesetzt, wenn der Nutzer das Dialogfeld mit der showConfirmationDialog() akzeptiert. Dieser Status kann auftreten, wenn die App von Google Play nicht erkannt wird, z. B. wenn sie per Sideload installiert wurde. Hinweis: 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 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. Mit der Methode getPackLocation() können Sie den Stammordner des KI-Pakets abrufen.

AI-Pakete werden im Verzeichnis assets im Stammverzeichnis des AI-Pakets gespeichert. Sie können den Pfad zum assets-Verzeichnis mit der praktischen Methode assetsPath() abrufen. So rufen Sie den Pfad zu einem bestimmten Asset ab:

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 Geräte-Targeting, um Geräte oder Gerätegruppen anzugeben, die Ihre KI-Pakete erhalten sollen.

Weitere Play AI Delivery API-Methoden

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

Anfrage abbrechen

Mit cancel() können Sie eine aktive Anfrage für ein KI-Paket abbrechen. Beachten Sie, dass diese Anfrage auf Best-Effort-Basis bearbeitet wird.

KI-Paket entfernen

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

Standorte mehrerer KI-Pakete abrufen

Mit getPackLocations() können Sie den Status mehrerer KI-Pakete gleichzeitig abfragen. Es wird dann eine Karte mit den KI-Paketen und ihren Speicherorten 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 ausgeliefert wird, oder unterschiedliche Versionen eines Modells auf verschiedenen Geräten bereitstellen.

Sie können Anzeigen auf Geräteeigenschaften wie die folgenden ausrichten:

Übersicht über die erforderlichen 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 das Geräte-Targeting verwenden möchten, muss die Version Ihres Android Gradle-Plug-ins (AGP) mindestens 8.10.0-alpha01 sein. Diese Funktion ist in Android Studio Meerkat 2 enthalten, das in der Canary-Version verfügbar ist.

Diese Funktion im Android-Gradle-Plug-in aktivieren

Das Geräte-Targeting muss in Ihrer gradle.properties-Datei explizit aktiviert sein:

android.experimental.enableDeviceTargetingConfigApi=true

XML-Datei für die Gerätekonfiguration erstellen

Die Konfigurationsdatei für die Geräteausrichtung ist eine XML-Datei, in der Sie Ihre benutzerdefinierten Gerätegruppen definieren. Sie können 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äteselektoren. Ein Gerät wird in eine Gerätegruppe aufgenommen, wenn es mindestens eine der Geräteauswahlen erfüllt.

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

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

Wenn ein Gerät mit keiner Gruppe übereinstimmt, wird ihm die Standardgruppe „Sonstiges“ 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 (inclusive): Mindestens erforderlicher RAM (in Byte)
    • max_bytes (ausschließlich): Maximaler erforderlicher RAM (in Byte)
  • included_device_ids: Gerätemodelle, die in diese Auswahl eingeschlossen werden sollen (maximal 10.000 device_ids pro Gruppe). Diese Property 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ätemodelle, die in dieser Auswahl ausgeschlossen werden sollen (maximal 10.000 device_ids pro Gruppe). Diese Property 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 Property zu erfüllen.

    Referenz zu Systemfunktionen

    • name: Eine Systemfunktion

  • forbidden_system_features: Funktionen, die ein Gerät nicht haben darf, müssen in dieser Auswahl enthalten sein (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-a-Chip: Systems-on-a-Chip, die in diese Auswahl aufgenommen werden sollen. Ein Gerät muss einen Chip in dieser Liste haben, um diese Property zu erfüllen.

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

  • Prüfen Sie einzelne Geräte mit dem Gerätekatalog und suchen Sie den Hersteller und den Modellcode an den Stellen, die im folgenden Beispiel gezeigt werden. Bei Google Pixel 4a lautet der Hersteller „Google“ und der Modellcode „sunfish“.

    Seite für Google Pixel 4a im Gerätekatalog

    Seite für Google Pixel 4a im Gerätekatalog

  • Laden Sie eine CSV-Datei mit unterstützten Geräten herunter und verwenden Sie die Werte Hersteller und Modellcode für die Felder build_brand und build_device.

Konfigurationsdatei für die Geräteausrichtung in das 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 mit Ihrem App-Bundle verpackt wird.

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

Geräteausrichtung 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. Dazu fügen Sie den vorhandenen KI-Paketverzeichnissen, die Sie im letzten Schritt erstellt haben, wie unten beschrieben ein Postfix wie #group_myCustomGroup1 oder #group_myCustomGroup2 hinzu. Wenn Sie die KI-Pakete in Ihrer App verwenden, müssen Sie die Ordner nicht anhand des Postfixes ansteuern. Das Postfix wird nämlich 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 auf ai-pack-name/assets/image-classifier/ ohne Suffixe 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 zugeordnet werden können, die Standardvariante Ihres KI-Pakets erhalten. Dazu gehören alle Dateien, die sich nicht in einem Verzeichnis mit einem #group_suffix befinden.

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

Geräte-Targeting für Funktionsmodule verwenden

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

Wenn Sie ein Funktionsmodul auf Geräten bereitstellen möchten, die zu myCustomGroup1 oder myCustomGroup2 gehören, ändern Sie 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 dem Bundletool testen.

Interne App-Freigabe

Mit der internen App-Freigabe können Sie mit einem App-Bundle schnell eine URL generieren, auf die Sie auf einem lokalen Gerät tippen 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 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. 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 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

Die folgenden Einschränkungen gelten für lokale Tests mit bundletool:

  • fast-follow-Sets verhalten sich wie on-demand-Sets. Sie werden also nicht automatisch abgerufen, wenn die App per Sideload installiert wird. Entwickler müssen sie beim Starten der App manuell anfordern. Dazu sind keine Codeänderungen in Ihrer App erforderlich.
  • Pakete werden nicht von Google Play, sondern aus dem externen Speicher abgerufen. Sie können also nicht testen, wie sich Ihr Code bei Netzwerkfehlern verhält.
  • Lokale Tests decken das Szenario „Warten auf WLAN“ 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

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

adb shell pm path {packageName}

Sie sollten etwa Folgendes sehen:

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 Installationszeit 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 mit einem internen Test-Track End-to-End bei Google Play zu testen.

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

Beispiel-App mit Play for On-Device AI

Wenden Sie sich an Ihren Google Play-Partnermanager, um Zugriff auf unsere Beispiel-App zu erhalten.

Darin wird gezeigt, wie die einzelnen Auslieferungsmodi sowie die Gerätekonfiguration verwendet werden. Im Abschnitt Lokale Tests finden Sie eine Anleitung.

Feedback geben

Teilnehmer am Early Access-Programm sollten Probleme melden und Feedback geben. Wenden Sie sich dazu an Ihren Google Play-Partnermanager oder an das Play for On-Device AI-Team.

Weitere Informationen

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