Targeting auf Geräte für bedingte Module

Was ist Geräte-Targeting für bedingte Module?

Mit dem Geräte-Targeting können Sie Geräte mit bedingten Funktionsmodulen basierend auf deren Hardware bereitstellen. So können Sie beispielsweise festlegen, dass einige Funktionen nur für High-End-Geräte zur Verfügung gestellt werden und nicht für Geräte, die diese Funktion nicht verwenden können, d.h. um auf diesen Geräten Platz zu sparen. Dies baut auf dem Konzept der Featuremodule in Play Feature Delivery auf. Wie Sie unten sehen, können Sie die Targeting-Kriterien (vorerst basierend auf dem RAM, bestimmten Gerätemodellen oder verfügbaren Systemfunktionen) definieren und Module auf bestimmte Gerätegruppen ausrichten.

Vorgehensweise für Entwickler*innen

Führen Sie folgende Schritte aus, um die Ausrichtung auf Geräte in Ihre bestehende Anwendung zu integrieren:

  1. Entwickeln Sie eine Funktion, die Sie nur einer Gruppe von Geräten basierend auf deren Hardware zur Verfügung stellen möchten.
    • Implementieren Sie diese Funktion als Funktionsmodul.
    • Geben Sie im Abschnitt „Modulbedingungen“ der Datei „AndroidManifest.xml“ an, an welche Gerätegruppen es gesendet werden soll.
  2. Konfiguration für das Geräte-Targeting erstellen, damit Play weiß, wie die Funktionsmodule an die Nutzergeräte gesendet werden können
    • Richten Sie die Google Play Developer API ein (falls noch nicht abgeschlossen). Damit senden Sie die DT-Konfigurationen an Play.
    • Gehen Sie die Schritte zum Erstellen der DT-Konfiguration durch.
  3. Laden Sie Ihr AAB in Google Play hoch und testen Sie, ob alles richtig konfiguriert ist

In diesem Dokument wird beschrieben, wie Sie mit dem Android Gradle-Plug-in Geräte-Targeting für die bedingte Auslieferung hinzufügen.

Bedingtes Funktionsmodul mit Geräte-Targeting erstellen

Hinzufügen eines Funktionsmoduls zur App

Mit Play Feature Delivery können Sie bestimmte Funktionen Ihrer App bedingt bereitstellen oder bei Bedarf herunterladen. Eine Übersicht finden Sie hier. Mit Geräte-Targeting können Sie eine Funktion bedingt für Geräte bereitstellen, die den bereitgestellten Gruppen zugewiesen sind.

Wenn Sie DT für die bedingte Zustellung verwenden möchten, müssen Sie bundletool ab Version 1.7.0 verwenden. Dazu müssen Sie die Bundletool-Version für das Android-Gradle-Plug-in explizit angeben. Dies erreichen Sie im Buildscript-Abschnitt der build.gradle-Datei im Stammverzeichnis:

buildscript {
  dependencies {
    classpath "com.android.tools.build:bundletool:1.7.0"
    ...
  }
  ...
}

Informationen zum Erstellen eines Funktionsmoduls findest du in dieser Anleitung unter Android-Apps modularisieren.

Sobald die Entwicklung der Funktion abgeschlossen ist, können Sie Auslieferungsbedingungen basierend auf dem Geräte-Targeting in der AndroidManifest.xml Ihrer Funktion festlegen. Sie müssen eine Gerätegruppenbedingung innerhalb eines dist:conditions-Elements vom Typ dist:module angeben. Allgemeine Informationen zu Bedingungen finden Sie hier. Für Gerätegruppen sind neue Bedingungen verfügbar, mit denen Sie alle Gruppen angeben können, an die dieses Feature geliefert werden soll:

<dist:device-groups>
  <dist:device-group dist:name="..." />
  <dist:device-group dist:name="..." />
  ...
</dist:device-groups>

Angenommen, Sie haben eine Gerätegruppe namens _my_group1 definiert. Wie diese Gruppe definiert wird, wird im Abschnitt Konfiguration für die Ausrichtung auf Geräte erstellen unten beschrieben. Wenn das Funktionsmodul nur für Geräte bereitgestellt werden soll, die zu _my_group1-Geräten gehören, sollte AndroidManifest.xml so aussehen:

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

Für ein Feature, das sowohl auf _my_group1 als auch auf _my_group2 ausgerichtet ist, sieht seine AndroidManifest.xml so aus:

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

Anschließend können Sie Ihr Android App Bundle (AAB) erstellen.

Lokale Tests

Bevor du fortfährst, solltest du dein App Bundle lokal testen, um sicherzustellen, dass alles korrekt eingerichtet ist. Mit bundletool können Sie Ihre App lokal erstellen und testen und dabei explizit die richtige Gerätegruppe angeben. Zuerst verwenden Sie build-apks, um eine Reihe von APK-Dateien zu generieren, und stellen dann Ihre App mit install-apks auf einem verbundenen Gerät bereit. Mit dem Flag device-groups kannst du auch angeben, welche Gruppe(n) installiert werden soll(en). Weitere Informationen zu dieser Methode für lokale Tests finden Sie hier. Diese Seite wurde noch nicht für DT aktualisiert und enthält daher das Flag device-groups.

bundletool build-apks --bundle=/path/to/app.aab --output=/path/to/app.apks --local-testingbundletool install-apks --apks=/path/to/app.apks --device-groups=my_group_1,my_group_2

Alternativ: Sie können auch extract-apks verwenden, um eine Reihe von APKs für ein bestimmtes Gerät zu extrahieren. Verwenden Sie dazu get-device-spec und geben Sie die Gerätegruppen für dieses Gerät an.

bundletool get-device-spec --output=/path/to/device-spec.json --device-groups=my_group_1,my_group_2bundletool extract-apks --apks=/path/to/existing_APK_set.apks --output-dir=/path/to/device_specific_APK_set.apks --device-spec=/path/to/device-spec.json

Geräte-Targeting-Konfiguration über die Google Play Developer API erstellen

Erste Schritte mit der Google Play Developer API (falls noch nicht abgeschlossen)

Wenn Sie das Geräte-Targeting konfigurieren (Gerätegruppen definieren), müssen Sie die Android Publisher API verwenden, um die Konfiguration bei Google Play hochzuladen. Unter dem oben angegebenen Link können Sie mehr über die API erfahren. Für den Einstieg sind einige Schritte erforderlich:

  1. API-Projekt erstellen (falls erforderlich) und mit der Google Play Console verknüpfen
  2. API-Zugriffsclient einrichten

Die API-Referenz finden Sie hier. Wenn Sie später Ihren Build über die API hochladen, verwenden Sie die Edits-Methoden. Es empfiehlt sich außerdem, diese Seite zu lesen, bevor Sie die API verwenden.

Device Targeting Configuration API verwenden

Mit dem folgenden API-Aufruf können Sie Ihre Konfiguration für die Ausrichtung auf Geräte erstellen:

Konfiguration für das Geräte-Targeting erstellen

HTTP-Anfrage POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Pfadparameter –
Anfragetext Konfiguration für das Geräte-Targeting
Antworttext Konfiguration für das Geräte-Targeting
Konfigurationsobjekt für Targeting auf Geräte
{
  device_groups: [
    {
      name: string,
      device_selectors: [
        {
          device_ram : {
            min_bytes: integer
            max_bytes: integer
          },
          included_device_ids: [
            {
              build_brand: string,
              build_device: string
            }
          ],
          excluded_device_ids: [
            {
              build_brand: string,
              build_device: string
            }
          ],
          required_system_features: [
            {
              name: string
            }
          ],
          forbidden_system_features: [
            {
              name: string
            }
          ]
        }
      ]
    }
  ]
}

Felder:

  • device_tier_config_id (Ganzzahl): ID, die dieser Geräte-Targeting-Konfiguration entspricht

  • device_groups (Objekt): Gruppendefinitionen

    • name (String): Name der Gerätegruppe (eine von Ihnen definierte String-ID)
    • device_selectors (Objekt): Geräteanforderungen für ein Gerät, das zu dieser Gruppe gehört.
    • device_ram (Objekt): RAM-Anforderungen des Geräts
      • min_bytes (Ganzzahl): Mindestanforderung RAM (in Byte)
      • max_bytes (Ganzzahl): Maximal benötigter RAM (in Byte)
    • included_device_ids (Objekt): Gerätemodelle, die in diesem Selektor einbezogen werden sollen (max. 10.000 Geräte-IDs pro Gruppe). Ein Gerät muss in dieser Liste enthalten sein, damit es mit der Auswahl übereinstimmt. Das ist eine notwendige, aber nicht ausreichend Bedingung für den vollständigen Selektor (siehe Hinweis zum Kombinieren von Anforderungen in einem Selektor unten).
      • build_brand (String): Gerätehersteller
      • build_device (String): Gerätemodellcode
    • excluded_device_ids (Objekt): Gerätemodelle, die in diesem Selektor ausgeschlossen werden sollen (max. 10.000 Geräte-IDs pro Gruppe) Ein Gerät aus dieser Liste stimmt nicht mit dem Selektor überein, auch wenn er alle anderen Anforderungen in der Auswahl erfüllt.
      • build_brand (String): Gerätehersteller
      • build_device (String): Gerätemodellcode

    • required_system_features (Objekt): Funktionen, die ein Gerät in dieser Auswahl enthalten muss (max. 100 Features pro Gruppe). Bei einem Gerät müssen alle Systemfunktionen in dieser Liste enthalten sein, damit es zur Auswahl passt. Dies ist eine notwendige, aber nicht ausreichend Bedingung für den vollständigen Selektor (siehe Hinweis zum Kombinieren von Anforderungen in einem Selektor).

      Systemreferenz

      • name (String): eine Systemfunktion

    • forbidden_system_features (Objekt): Funktionen, die in dieser Auswahl nicht enthalten sein dürfen (max. 100 Features pro Gruppe). Wenn ein Gerät eine der Systemfunktionen in dieser Liste hat, stimmt es nicht mit der Auswahl überein, auch wenn es alle anderen Anforderungen in der Auswahl erfüllt.

      Systemreferenz

      • name (String): eine Systemfunktion

Die richtige Formatierung für den Gerätehersteller und den Modellcode findest du im Gerätekatalog in der Google Play Console. Dazu hast du eine der folgenden Möglichkeiten:

  • Wir untersuchen einzelne Geräte mit dem Gerätekatalog und ermitteln den Hersteller und den Modellcode an den entsprechenden Orten, wie im Beispiel unten gezeigt. Bei einem Google Pixel 4a lautet der Hersteller „Google“ und der Modellcode „sunfish“.

    Seite für Pixel 4a im Gerätekatalog

    Seite für Pixel 4a im Gerätekatalog

  • Sie laden eine CSV-Datei der unterstützten Geräte herunter und verwenden den Hersteller bzw. den Modellcode für die Felder build_brand bzw. build_device.

Die folgende Gruppe entspricht beispielsweise allen Geräten mit mehr als 4 GB RAM, mit Ausnahme von Pixel 5 (google redfin) und Pixel 3 (Google Blueline mit weniger als 4 GB RAM).

device_groups: [
  {
    name: "my_group_1",
    device_selectors: [
      {
        device_ram: {
          min_bytes: 4294967296
        },
        excluded_device_ids: [
          {
            build_brand: "google",
            build_device: "redfin"
          }
        ]
      },
      {
        included_device_ids: [
          {
            build_brand: "google",
            build_device: "blueline"
          }
        ]
      }
    ]
  }
]

Sie können sie folgendermaßen lesen:

[ (RAM > 4GB) AND NOT (google redfin) ] OR [ (google blueline) ]

Folgen Sie der Anleitung unten zum Validieren der Geräte-Targeting-Konfiguration, bevor Sie sie bei Google Play hochladen.

Geräte-Targeting-Konfiguration nach ID abrufen

Mit dem folgenden Aufruf können Sie eine bestimmte Konfiguration für das Geräte-Targeting nach ID abrufen:

HTTP-Anfrage GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}
Pfadparameter –
Anfragetext –
Antworttext Konfiguration für das Geräte-Targeting

Liste der Geräte-Targeting-Konfigurationen abrufen

Mit dem folgenden Aufruf können Sie die letzten zehn Konfigurationen für die Ausrichtung auf Geräte abrufen (oder optimal mit dem Abfrageparameter page_token eine Gruppe von zehn Konfigurationen festlegen):

HTTP-Anfrage GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Pfadparameter –
Abfrageparameter page_token (optional): Wird verwendet, um eine bestimmte Gruppe von zehn DTCs anzugeben. Dies ist nützlich, wenn Sie mehr als 10 DTCs erstellt haben und DTCs sehen möchten, die vor den letzten 10 erstellt wurden.
Anfragetext –
Antworttext Liste der Geräte-Targeting-Konfigurationen

page_token

Konfiguration für die Ausrichtung auf Geräte prüfen

bundletool enthält zwei Befehle, mit denen Sie prüfen können, ob Ihre Geräte-Targeting-Konfiguration wie beabsichtigt funktioniert, bevor Sie sie bei Google Play hochladen.

Mit bundletool print-device-targeting-config können Sie prüfen, ob die Syntax Ihrer JSON-Datei korrekt ist, und Ihre Gerätegruppen in einem besser lesbaren Format visualisieren.

bundletool print-device-targeting-config --config=mydtc.json

Mit bundletool evaluate-device-targeting-config können Sie auswerten, welche Gruppen einem bestimmten Gerät zugeordnet werden würden. Entweder verbinden Sie das Zielgerät mit Ihrer Workstation und verwenden das Flag --connected-device. Sie können aber auch eine JSON-Datei mit den Geräteeigenschaften manuell kompilieren und über das Flag --device-properties bereitstellen.

bundletool evaluate-device-targeting-config --config=mydtc.json --connected-device
bundletool evaluate-device-targeting-config --config=mydtc.json --device-properties=deviceproperties.json

Die Datei mit den Geräteeigenschaften sollte eine JSON-Datei sein, die der Protokollpuff-Struktur DeviceProperties entspricht. Beispiele:

{
  "ram": 2057072640,
  "device_id": {
    "build_brand":"google",
    "build_device":"redfin"
  },
  "system_features": [
    {
      "name":"android.hardware.bluetooth"
    },
    {
      "name":"android.hardware.camera"
    }
  ]
}

Android App Bundle bei Google Play hochladen

Über API

Mit der Google Play Developer API können Sie Ihr Android App Bundle bei Google Play hochladen und eine bestimmte Konfiguration für das Geräte-Targeting mit Ihrem Build verknüpfen.

Einen allgemeinen Überblick über die Bearbeitungsmethoden sowie detailliertere Beispiele für Veröffentlichungen in den verschiedenen Tracks in der Google Play Console finden Sie hier. Unter dem letzten Link finden Sie die AAB-freundlichen APIs anstelle der APK-freundlichen API, die auf dieser Seite aufgeführt sind. Um die Konfiguration für das Geräte-Targeting für Ihren Build anzugeben, fügen Sie dem Abfrageparameter deviceTierConfigId die Konfigurations-ID hinzu, während Sie die Methode edits.bundle.upload aufrufen:

https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications/{packageName}/edits/{editId}/bundles?deviceTierConfigId="{deviceTierConfigId}"

Über die Google Play Console

Folgen Sie dieser Anleitung, um Ihr Android App Bundle hochzuladen. Die aktuelle DTC-Konfiguration wird auf Ihr App Bundle angewendet.

Zusatz

Schnellstart mit Curl

Im folgenden Beispiel (unter Verwendung des Befehlszeilentools „curl“) wird gezeigt, wie Sie eine neue Konfiguration für das Geräte-Targeting erstellen und mit der Edits API eine neue Änderung erstellen, eine neue AAB hochladen (sie mit einer bestimmten Targeting-Konfiguration für das Gerät verknüpfen), die Track-/Release-Konfiguration festlegen und die Änderung übernehmen (um die Änderung zu veröffentlichen). Sie benötigen den Speicherort:

  • Den Schlüssel für Ihren API-Client
  • Paketname Ihrer App

Erstellen Sie zuerst eine Konfiguration für das Geräte-Targeting und notieren Sie sich die deviceTierConfigId, die Sie nach einem erfolgreichen Aufruf erhalten.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST -H "Content-Type: application/json" -d "{ device_groups: [ { name: "my_group_1", device_selectors: [ { device_ram: { min_bytes: 4294967296 }, excluded_device_ids: [ { build_brand: "google", build_device: "redfin" } ] }, { included_device_ids: [ { build_brand: "google", build_device: "blueline" } ] } ] } ] }" https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs

Änderung starten: Sie erhalten eine ID und die Ablaufzeit für die Änderung. Speichern Sie die ID für die folgenden Aufrufe.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits

Laden Sie das AAB hoch und geben Sie die Geräte-Targeting-Konfiguration (deviceTierConfigId) als Abfrageparameter an. Wenn der Aufruf erfolgreich ist, wird der Versionscode „sha1“ und „sha256“ des Builds angezeigt. Speichern Sie den Versionscode für den nächsten Aufruf.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" --data-binary @$HOME/{aabFile} -H "Content-Type: application/octet-stream" -XPOST https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications/{packageName}/edits/{editID}/bundles?deviceTierConfigId="{deviceTierConfigId}

Weisen Sie das AAB dem gewünschten Track zu. Zum Testen wird empfohlen, den internen Test-Track zu verwenden. Hier finden Sie weitere Informationen zu den verschiedenen Tracks. Hier führen wir ein einfaches Rollout ohne Versionshinweise durch. Auf dieser Seite finden Sie weitere Informationen zu gestaffelten Roll-outs, Release-Entwürfen und Versionshinweisen. Wenn du die Publisher API zum ersten Mal verwendest, solltest du sie als Versionsentwurf erstellen und ihn in der Google Play Console fertigstellen, um sicherzustellen, dass alles richtig konfiguriert ist.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPUT -H "Content-Type: application/json" -d "{ releases: [{status: '{status}', versionCodes: ['{versionCode}'] }]}" https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits/{editID}/tracks/{track}

Commit für Änderungen durchführen (verfahren Sie mit Vorsicht, da dadurch alle Änderungen für den gewünschten Track bei Google Play live geschaltet werden)

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits/{editID}:commit