Asset-Targeting nach Land

Was ist Asset-Targeting nach Land?

Mit dem Asset-Targeting nach Land können Sie je nach Land, in dem sich der Nutzer befindet, verschiedene Versionen (z. B. Auflösungen) desselben Assets an Geräte senden. Beispielsweise können Sie benutzerdefinierte Assets in verschiedenen Ländern bereitstellen, in denen Ihre App verfügbar ist – ohne die Gesamtgröße des Spiels zu erhöhen, da nur die erforderlichen Assets an die Geräte der Nutzer gesendet werden. Dies baut auf dem Konzept der Asset-Packs in der Asset-Lieferung von Google Play auf. Wie Sie unten sehen, können Sie Targeting-Kriterien mit bis zu 20 Ländern definieren. Das Land des Geräts wird in der Regel anhand der Rechnungsadresse des Nutzers bestimmt, die in seinem Google Play-Konto registriert ist.

Wie bei Play Asset Delivery werden bei der länderspezifischen Ausrichtung Android 4.1 (API-Level 16) und höher unterstützt. Auf Geräten mit Android 4.4 (API-Level 19) oder niedriger wird das Standardland jedoch unabhängig vom Standort des Nutzers ausgeliefert.

Vorgehensweise für Entwickler*innen

So binden Sie die länderspezifische Ausrichtung in Ihr Spiel ein:

1. Integrieren Sie Targeting nach Land (und durch Erweiterung, Play Asset Delivery) in Ihr Spiel.
   • Integrieren Sie Play Asset Delivery in Ihr Spiel (falls Sie dies noch nicht getan haben).
   • Assets in Asset-Packs aufteilen
   • Verpacke deinen Code und die Assets für das endgültige Android App Bundle-Artefakt, das du bei Google Play hochlädst.
2. Erstellen Sie Ihre Geräte-Targeting-Konfiguration, damit Play weiß, wie Ihre Assets an die Nutzergeräte gesendet werden sollen.
   • Richten Sie die Google Play Developer API ein (falls noch nicht abgeschlossen). Damit senden Sie die Targeting-Konfigurationen an Play.
   • Führen Sie die Schritte zum Erstellen der Targeting-Konfiguration aus.
3. Laden Sie Ihr AAB in Google Play hoch und testen Sie, ob alles richtig konfiguriert ist

Gradle ist das empfohlene Build-System für Java und native Spiele. Führen Sie bei Spielen, die mit Gradle erstellt wurden, die folgenden Schritte aus, um das Build-System zu konfigurieren, um Ihr AAB mit Unterstützung für die Länderausrichtung zu erstellen.

Wenn du dein Spiel nach Gradle exportierst und den Build dort fertigstellst, empfehlen wir, dieser Anleitung zu folgen (z. B. zu Gradle exportierte Unity-Spiele) verwenden.

Asset-Targeting nach Land in Ihrer App einrichten

Play Asset Delivery in dein Spiel integrieren (falls noch nicht abgeschlossen)

Mit Play Asset Delivery (PAD) können Sie die Assets Ihres Spiels bei der Installation oder Laufzeit dynamisch bereitstellen. Eine Übersicht dazu finden Sie hier. Beim Targeting nach Land stellt Google Play die Inhalte Ihrer Asset-Packs basierend auf den Länderkonfigurationen bereit, die Sie für verschiedene Nutzerstandorte vorschreiben. Es wird empfohlen, der unten stehenden Anleitung zu folgen und PAD in dein Spiel zu integrieren (d.h. Asset-Packs zu erstellen, Abrufe in deinem Spiel zu implementieren) und dann den Projektcode so zu ändern, dass das Targeting nach Land möglich ist.

Gradle

Folgen Sie bei Spielen, die mit Gradle erstellt wurden, dieser Anleitung zum Erstellen von Asset-Packs mit Gradle und anschließend der Anleitung zum Einbinden des Asset-Pack-Abrufs in Ihr Spiel:

• Java
• Nativ
• Unity-Spiele in Gradle exportiert
  • Verwenden Sie die Java-Bibliotheken über die JNI (z. B. die in Unity integrierte).

Länderspezifische Verzeichnisse erstellen

Bei Verwendung von Gradle

Du teilst deine Assets jetzt auf die Ländergruppen (max. 20) auf, die du später definieren wirst. Erstellen Sie Ihre Zielverzeichnisse. Verwenden Sie dazu die vorhandenen Asset-Bundle-Verzeichnisse, die im letzten Schritt erstellt wurden, und korrigieren Sie den entsprechenden Ordner (wie unten beschrieben) mit #countries_latam, #countries_na usw. Wenn Sie die Asset-Packs in Ihrem Spiel verwenden, müssen Sie Ordner nicht per Postfix adressieren, d. h., das Postfix wird während des Build-Prozesses automatisch entfernt.

Nach dem vorherigen Schritt könnte das so aussehen:

...
.../level1/src/main/assets/character-textures#countries_latam/
.../level1/src/main/assets/character-textures#countries_na/
.../level1/src/main/assets/character-textures/
...

Wenn Sie auf die Dateien unter dem Ordner zugreifen, können Sie einfach denselben Pfad ohne Post-Fixing verwenden (in diesem Beispiel würde ich als level1/assets/character-textures/ ohne Postfixes verweisen).

Android App Bundle erstellen

Gradle

Konfigurieren Sie in der Datei build.gradle Ihres Projekts die Abhängigkeiten so, dass sie die unten aufgeführten Versionen (oder höher) für das Android-Gradle-Plug-in und das Bundletool haben:

buildscript {
  dependencies {
    classpath 'com.android.tools.build:gradle:8.1.0-alpha01'
    classpath "com.android.tools.build:bundletool:1.14.0"
    ...
  }
  ...
}

Außerdem musst du deine Gradle-Version auf 8.0 oder höher aktualisieren. Sie können dies in Ihrem Projekt in gradle/wrapper/gradle-wrapper.properties aktualisieren.

distributionUrl=https://services.gradle.org/distributions/gradle-8.0-rc-1-all.zip

Schließlich müssen Sie die Play Asset Delivery Library verwenden. Wenn Sie noch die monolithische Play Core Library verwenden, aktualisieren Sie sie auf 1.8.3 oder höher. Wir empfehlen, zur Play Asset Delivery Library zu wechseln und nach Möglichkeit auf die neueste Version zu aktualisieren.

dependencies {
  implementation 'com.google.android.play:asset-delivery:2.0.1'
  ...
}

Aktivieren Sie in der Datei build.gradle des Haupt-App-Moduls die Aufteilung der Ausrichtung auf Länder:

android {
  bundle {
    countrySet {
      enableSplit true
    }
    ...
  }
  ...
}

Als Letztes können Sie Ihr Android App Bundle (AAB) erstellen.

• Android Studio
• Befehlszeile

Bundletool

Erstellen Sie Ihr Bundle mit Bundletool und fügen Sie im Schritt zum Anpassen Ihres AAB Folgendes in die BundleConfig.pb-Datei ein:

{
  ...
  "optimizations": {
    "splitsConfig": {
      "splitDimension": [
      ...
      {
        "value": "COUNTRY_SET",
        "negate": false,
        "suffixStripping": {
          "enabled": true,
        }
      }],
    }
  }
}

Lokale Tests

Bevor du fortfährst, solltest du dein App Bundle lokal testen, um sicherzustellen, dass alles korrekt eingerichtet ist. Mit bundletool (1.14.0 oder höher) erstellen und testen Sie Ihre Anwendung lokal und geben dabei das richtige Land an. Zuerst verwenden Sie build-apks, um eine Reihe von .apks-Dateien zu generieren, und stellen dann die App mithilfe von install-apks auf einem verbundenen Gerät bereit. Über das Flag country-set können Sie auch angeben, welche Ländereinstellung installiert werden soll. Weitere Informationen zu dieser Methode für lokale Tests finden Sie hier. Da diese Seite für die Ausrichtung nach Land noch nicht aktualisiert wurde, fehlt das Flag country-set.

bundletool build-apks --bundle=/path/to/app.aab --output=/path/to/app.apks --local-testing
bundletool install-apks --apks=/path/to/app.apks --country-set=latam

Alternativ: Sie können auch extract-apks verwenden, um eine Reihe von APKs für ein bestimmtes Gerät zu extrahieren. Die Verwendung von get-device-spec zusammen mit der Angabe des Landes für dieses Gerät funktioniert nicht in Verbindung mit dem Flag --local-testing. Das bedeutet, dass du keine Fast-Follow- oder On-Demand-Asset-Packs testen kannst.

bundletool get-device-spec --output=/path/to/device-spec.json --country-set=latam
bundletool 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 Targeting nach Land konfigurieren möchten, also Ihre Ländersätze definieren, müssen Sie die Android Publisher API verwenden, um Ihre 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. Erstellen Sie bei Bedarf Ihr API-Projekt und verknüpfen Sie es mit der Google Play Console.
2. Richten Sie einen API-Zugriffsclient ein.

Die API-Referenz finden Sie hier. Wenn Sie den Build später über die API hochladen, verwenden Sie die Bearbeitungsmethoden. 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

{
  "user_country_sets": [
    {
      "name": "latam",
      "country_codes": [
        "AR",
        "BR",
        ...
      ]
    },
    {
      "name": "sea",
      "country_codes": [
        "VN",
        "TW",
        ...
      ]
    }
  ]
}

Felder:

• device_confid_id (Ganzzahl): ID, die dieser Geräte-Targeting-Konfiguration entspricht.
• user_country_sets (Objekt): Definitionen von Ländergruppen
  • name (String): Name des Ländersatzes (eine von Ihnen definierte String-ID).
  • country_codes (String): Die Länder, die zu diesem Ländersatz gehören (Format: ISO 3166-1 alpha-2).

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	GET https://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 erhalten Sie die letzten zehn Konfigurationen für die Ausrichtung auf Geräte (oder geben Sie am besten mit dem Abfrageparameter page_token eine zehn Liste an):

HTTP-Anfrage	GET https://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 Seitentoken

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.

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

Mit bundletool evaluate-device-targeting-config kannst du prüfen, welche Ländereinstellung für ein bestimmtes Gerät gilt. Das Land des Nutzers können Sie über das Flag --country-code angeben.

bundletool evaluate-device-targeting-config --config=mydtc.json --connected-device --country-code=AR

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

Prüfen, ob die richtigen Assets geliefert werden

Mit der folgenden Methode kannst du dafür sorgen, dass nur die richtigen Assets an das Gerät gesendet werden.

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_asset.apk
package:{...}/split_main_asset.config.countries_latam.apk

Zusatz

Schnellstart mit Curl

Im Folgenden finden Sie ein Beispiel (unter Verwendung des Befehlszeilentools curl) zum Erstellen einer neuen Geräte-Targeting-Konfiguration und zum Erstellen einer neuen Änderung über die Edits API, zum Hochladen eines neuen AAB (Verknüpfen mit einer bestimmten Geräte-Targeting-Konfiguration), zum Festlegen der Track-/Release-Konfiguration und zum Commit der Änderung. (die Änderung wird somit öffentlich gemacht). Sie benötigen den folgenden 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 den deviceTierConfigId, den Sie nach einem erfolgreichen Aufruf erhalten.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST -H "Content-Type: application/json" -d "{ "user_country_sets": [ { "name": "latam", "country_codes": [ "AR", "BR" ] }, { "name": "sea", "country_codes": [ "VN", "TW" ] } ] }" 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 als Abfrageparameter an. Wenn der Aufruf erfolgreich ist, sehen Sie den Versionscode „sha1“ und „sha256“ des Builds. 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="{deviceTargetingConfigID}"

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 diesen 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}'</code>, <code><strong>versionCodes</strong></code>: <code>['{versionCode}']</code> <code><strong>}]}</strong></code>" <code>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