Asset-Targeting nach Land

Was ist die Asset-Ausrichtung 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 auf Geräte ausliefern. So können Sie beispielsweise angepasste Assets für verschiedene Länder bereitstellen, in denen Ihre App verfügbar ist, ohne dass die Gesamtgröße des Spiels zunimmt, da nur die erforderlichen Assets auf die Geräte der Nutzer übertragen werden. Das Konzept basiert auf dem Konzept von Asset-Packs in Play Asset Delivery. Wie Sie sehen, können Sie die Targeting-Kriterien mit bis zu 20 Ländergruppen definieren. In diesem Zusammenhang wird das Land des Geräts in der Regel anhand der Rechnungsadresse des Nutzers bestimmt, die in seinem Google Play-Konto registriert ist.

Wie bei der Play Asset Delivery wird das Targeting nach Land ab Android 4.1 (API-Level 16) unterstützt. Auf Geräten mit Android 4.4 (API-Level 19) oder niedriger wird das standardmäßige Land jedoch unabhängig vom Standort des Nutzers gesendet.

Entwickler Journey

So binden Sie das Targeting nach Land in Ihr bestehendes Spiel ein:

  1. Länderspezifische Ausrichtung (und somit Play Asset Delivery) in Ihr Spiel einbinden
    • Play Asset Delivery in Ihr Spiel einbinden (falls noch nicht geschehen)
    • Assets in Asset-Packs unterteilen
    • Verpacken Sie Ihren Code und Ihre Assets in einem endgültigen Android App Bundle-Artefakt, das Sie in Google Play hochladen.
  2. Erstellen Sie die Konfiguration für das Geräte-Targeting, damit Google Play weiß, wie Ihre Assets auf Nutzergeräten bereitgestellt werden sollen.
    • Richte die Google Play Developer API ein, falls noch nicht geschehen. Damit sendest du die Targeting-Konfigurationen an Google Play.
    • Führen Sie die Schritte zum Erstellen der Targeting-Konfiguration aus.
  3. Laden Sie Ihre AAB bei Google Play hoch und prüfen Sie, ob alles richtig konfiguriert ist.

Gradle ist das empfohlene Buildsystem für Java- und native Spiele. Bei Spielen, die mit Gradle erstellt wurden, können Sie das Build-System so konfigurieren, dass Ihre AAB mit Länderausrichtung unterstützt wird. Gehen Sie dazu so vor:

Wenn Sie Ihr Spiel nach Gradle exportieren und dort den Build abschließen, empfehlen wir Ihnen, dieser Anleitung zu folgen (z. B. Unity-Spiele, die nach Gradle exportiert wurden

Asset-Ausrichtung nach Land in Ihrer App einrichten

Play Asset Delivery in Ihr Spiel einbinden (falls noch nicht geschehen)

Mit der Dynamic Delivery von Assets bei Google Play (PAD) können Sie die Assets Ihres Spiels bei der Installation oder Laufzeit dynamisch bereitstellen. Hier finden Sie eine Übersicht. Bei der Ausrichtung nach Land werden die Inhalte Ihrer Asset-Pakete von Google Play basierend auf den Konfigurationen für Ländergruppen ausgeliefert, die Sie für verschiedene Nutzerstandorte festlegen. Wir empfehlen, der Anleitung unten zu folgen und PAD in Ihr Spiel einzubinden (d.h. Asset-Pakete erstellen, Abruf in Ihrem Spiel implementieren) und dann den Projektcode so zu ändern, dass das Targeting nach Land aktiviert wird.

Gradle

Folgen Sie bei Spielen, die mit Gradle erstellt wurden, der Anleitung unter Asset-Packs mit Gradle erstellen und folgen Sie dann der Anleitung zum Integrieren des Abrufs von Asset-Packs in Ihr Spiel:

Länderspezifische Verzeichnisse erstellen

Wenn Sie Gradle verwenden

Sie teilen Ihre Assets jetzt auf die Ländergruppen (max. 20) auf, die Sie später definieren. Erstellen Sie die Zielverzeichnisse, indem Sie die vorhandenen Asset-Bundle-Verzeichnisse aus dem letzten Schritt verwenden und den entsprechenden Ordner (wie unten beschrieben) mit #countries_latam, #countries_na usw. als Präfix versehen. Wenn Sie die Asset-Packs in Ihrem Spiel verwenden, müssen Sie die Ordner nicht mit einem Präfix ansteuern. Das Präfix wird also 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 im Ordner zugreifen, können Sie einfach denselben Pfad verwenden, ohne nach der Korrektur zu suchen (in diesem Beispiel würde ich ohne Postfixes auf level1/assets/character-textures/ verweisen).

Android App Bundle erstellen

Gradle

Konfigurieren Sie in der Datei build.gradle Ihres Projekts die Abhängigkeiten so, dass sie die folgenden Versionen (oder höher) für das Android Gradle-Plug-in und 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 müssen Sie Ihre Gradle-Version auf 8.0 oder höher aktualisieren. Sie können dies in Ihrem Projekt unter gradle/wrapper/gradle-wrapper.properties aktualisieren.

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

Außerdem müssen Sie die Play Asset Delivery Library verwenden. Wenn Sie noch die monolithische Play Core Library verwenden, aktualisieren Sie sie auf Version 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 nach Land:

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

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

Bündeltool

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

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

Lokales Testen

Bevor Sie fortfahren, sollten Sie Ihr App-Bundle lokal testen, um sicherzustellen, dass alles richtig eingerichtet ist. Mit bundletool (1.14.0 oder höher) können Sie Ihre App lokal erstellen und testen, indem Sie das richtige Land explizit angeben. Sie verwenden zuerst build-apks, um eine Reihe von .apks-Dateien zu generieren, und stellen dann Ihre Anwendung mithilfe von install-apks auf einem verbundenen Gerät bereit. Sie können auch über das Flag country-set angeben, welche Ländergruppe installiert werden soll. Weitere Informationen zu dieser Methode finden Sie hier. Beachten Sie, dass diese Seite noch nicht für die Ausrichtung nach Ländern aktualisiert wurde und daher die Kennzeichnung country-set fehlt.

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 mehrere APKs für ein bestimmtes Gerät zu extrahieren. Die Verwendung von get-device-spec und die Angabe des Landes für dieses Gerät funktioniert jedoch nicht in Verbindung mit dem Flag --local-testing. Du kannst also keine Fast-Follow- oder On-Demand-Asset-Packs testen.

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ätekonfiguration ü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 (d.h. Ihre Ländergruppen definieren), müssen Sie die Android Publisher API verwenden, um Ihre Konfiguration in Google Play hochzuladen. Weitere Informationen zur API finden Sie unter dem obigen Link. So können Sie loslegen:

  1. Erstellen Sie (falls erforderlich) Ihr API-Projekt und verknüpfen Sie es mit Ihrer Google Play Console.
  2. Richten Sie einen API-Zugriffsclient ein.

Die API-Referenz finden Sie hier. Wenn Sie Ihren Build später über die API hochladen, verwenden Sie die Methoden für Änderungen. Außerdem empfehlen wir dir, diese Seite zu lesen, bevor du die API verwendest.

Device Targeting Configuration API verwenden

Mit dem folgenden API-Aufruf können Sie die Konfiguration für die Geräteausrichtung 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 die Ausrichtung auf Geräte
Antworttext Konfiguration für die Ausrichtung auf Geräte
Konfigurationsobjekt für das Geräte-Targeting
{
  "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): Ländergruppendefinitionen
    • name (String): Der Name der Länderauswahl (eine von Ihnen definierte String-ID).
    • country_codes (String): Länder, die zu diesem Ländersatz gehören (Format: ISO 3166-1 alpha-2).

Folgen Sie der Anleitung unten, um die Konfiguration für die Geräteausrichtung zu validieren, bevor Sie sie bei Google Play hochladen.

Gerätekonfiguration nach ID abrufen

Sie können eine bestimmte Gerätekonfiguration für die Ausrichtung mithilfe des folgenden Aufrufs anhand der ID abrufen:

HTTP-Anfrage GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}
Pfadparameter –
Anfragetext –
Antworttext Konfiguration für die Ausrichtung auf Geräte

Liste der Konfigurationen für die Ausrichtung auf Geräte abrufen

Mit dem folgenden Aufruf können Sie die letzten zehn Konfigurationen für die Geräteausrichtung abrufen. Alternativ können Sie mit dem Abfrageparameter page_token eine Gruppe von zehn Konfigurationen angeben:

HTTP-Anfrage GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Pfadparameter –
Abfrageparameter page_token (optional): Damit wird eine bestimmte Gruppe von 10 DTCs angegeben. Das ist hilfreich, wenn Sie mehr als 10 DTCs erstellt haben und sich DTCs ansehen möchten, die vor den letzten 10 erstellt wurden.
Anfragetext –
Antworttext Liste der Konfigurationen für die Ausrichtung auf Geräte

page_token

Konfiguration des Geräte-Targetings prüfen

bundletool enthält zwei Befehle, mit denen Sie vor dem Hochladen Ihrer Konfiguration für das Geräte-Targeting prüfen können, ob sie wie vorgesehen funktioniert.

Mit bundletool print-device-targeting-config können Sie prüfen, ob Ihre JSON-Datei syntaktisch korrekt ist.

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

Mit bundletool evaluate-device-targeting-config können Sie prüfen, welche Ländergruppe zu einem bestimmten Gerät passt. Sie können das Land des Nutzers ü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 in Google Play hochladen und eine bestimmte Gerätekonfiguration mit Ihrem Build verknüpfen.

Hier finden Sie einen allgemeinen Überblick über die Methoden für Änderungen sowie detailliertere Beispiele für die Veröffentlichung in den verschiedenen Tracks in der Google Play Console. Für den letzten Link sollten Sie die AAB-kompatiblen APIs anstelle der auf der Seite aufgeführten APK-kompatiblen API verwenden. Wenn Sie die Konfiguration für die Geräteausrichtung für Ihren Build angeben möchten, fügen Sie die Konfigurations-ID dem Abfrageparameter deviceTierConfigId hinzu, während Sie die Methode edits.bundle.upload aufrufen. Das sieht so aus:

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 aktuellste DTC-Konfiguration wird auf Ihr App-Bundle angewendet.

Überprüfen, ob die richtigen Assets bereitgestellt werden

Verwende die folgende Methode, damit 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: Curl verwenden

Unten finden Sie ein Beispiel (mit dem Befehlszeilentool „curl“), wie Sie eine neue Gerätekonfiguration für die Ausrichtung erstellen und mit der Edits API eine neue Änderung erstellen, eine neue AAB hochladen (mit einer bestimmten Gerätekonfiguration für die Ausrichtung verknüpfen), die Track-/Release-Konfiguration festlegen und die Änderung committen. damit die Änderung öffentlich sichtbar wird. Sie benötigen die Standorte der folgenden Elemente:

  • Der Schlüssel, der Ihrem API-Client entspricht
  • Der Paketname Ihrer App

Erstellen Sie zuerst eine Gerätekonfiguration 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 "{ "user_country_sets": [ { "name": "latam", "country_codes": [ "AR", "BR" ] }, { "name": "sea", "country_codes": [ "VN", "TW" ] } ] }" https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs

Starte eine Bearbeitung: Sie erhalten eine ID und eine 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 die AAB hoch und geben Sie die Konfiguration für die Geräteausrichtung als Abfrageparameter an. Wenn der Aufruf erfolgreich war, sehen Sie einen 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. Für Tests wird empfohlen, den internen Test-Track zu verwenden. Hier finden Sie weitere Informationen zu den verschiedenen Tracks. Hier wird ein einfaches Roll-out ohne Versionshinweise durchgeführt. Auf dieser Seite finden Sie weitere Informationen zu gestaffelten Roll-outs, Versionsentwürfen und Versionshinweisen. Wenn Sie die Publisher API zum ersten Mal verwenden, empfehlen wir, diese als Release-Entwurf zu erstellen und den Release in der Google Play Console abzuschließen, 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}

Änderungen übernehmen (Vorsicht: Dadurch werden alle Änderungen am gewünschten Release-Track bei Google Play veröffentlicht.)

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