Kierowanie zasobów według kraju

Czym jest kierowanie zasobów według kraju?

Kierowanie zasobów według kraju umożliwia wyświetlanie różnych wersji (np. rozdzielczości) tego samego komponentu na urządzeniach na podstawie kraju, w którym znajduje się użytkownik. Możesz na przykład dostarczać dostosowane zasoby do różnych krajów, w których dostępna jest Twoja aplikacja, bez zwiększania ogólnego rozmiaru gry, przesyłając na urządzenia użytkowników tylko niezbędne zasoby. bazuje na koncepcji pakietów zasobów w funkcji Asset Delivery w Google Play. Jak zobaczysz poniżej, możesz zdefiniować kryteria kierowania z maksymalnie 20 zestawami krajów. W tym kontekście kraj urządzenia jest zazwyczaj określany na podstawie adresu rozliczeniowego zarejestrowanego na koncie Google Play użytkownika.

Podobnie jak w przypadku Play Asset Delivery, kierowanie na kraj jest obsługiwane w Androidzie 4.1 (poziom interfejsu API 16) lub nowszym. Na urządzeniach z Androidem w wersji 4.4 (poziom interfejsu API 19) lub starszej domyślny kraj jest dostarczany niezależnie od lokalizacji użytkownika.

Ścieżka dewelopera

Aby zintegrować kierowanie według kraju z dotychczasową grą, wykonaj te czynności:

1. Zintegruj w grze kierowanie według kraju (i co za tym idzie, Play Asset Delivery).
   • Zintegruj z grą Play Asset Delivery (jeśli jeszcze tego nie zrobiono)
   • Podziel swoje zasoby na pakiety zasobów
   • Spakuj kod i zasoby w ramach końcowego artefaktu pakietu aplikacji na Androida, który prześlesz do Google Play.
2. Utwórz konfigurację kierowania na urządzenia, aby Google Play wiedział, jak dostarczać zasoby na urządzenia użytkowników.
   • Skonfiguruj interfejs Google Play Developer API (jeśli nie zostało to jeszcze zrobione). Będziesz go używać do wysyłania konfiguracji kierowania do Google Play.
   • Wykonaj czynności potrzebne do utworzenia konfiguracji kierowania.
3. Prześlij pakiet AAB do Google Play i sprawdź, czy wszystko jest prawidłowo skonfigurowane.

Gradle to zalecany system kompilacji dla gier natywnych i w języku Java. W przypadku gier skompilowanych za pomocą Gradle wykonaj te czynności, aby skonfigurować system kompilacji w celu skompilowania AAB z obsługą kierowania na kraje.

Jeśli wyeksportujesz grę do Gradle, a potem ukończysz kompilację, zalecamy wykonanie tych czynności (np. gry Unity wyeksportowane do Gradle)).

Konfigurowanie kierowania komponentów na kraje w aplikacji

Integracja Play Asset Delivery z grą (jeśli jeszcze nie została ukończona)

Play Asset Delivery (PAD) umożliwia dynamiczne przesyłanie zasobów gry w momencie instalacji lub w czasie działania. Tutaj możesz przeczytać omówienie tej funkcji. W przypadku kierowania według kraju Google Play będzie dostarczać treści z Twoich pakietów zasobów na podstawie konfiguracji zestawu krajów określonych przez Ciebie dla różnych lokalizacji użytkowników. Zalecamy, aby postępować zgodnie z podanymi niżej wskazówkami i zintegrować PAD z grą (np. utworzyć pakiety zasobów i wdrożyć odzyskiwanie w grze), a następnie zmodyfikować kod projektu, aby umożliwić kierowanie według kraju.

Gradle

W przypadku gier utworzonych za pomocą Gradle skorzystaj z tych instrukcji tworzenia pakietów zasobów w Gradle, a potem postępuj zgodnie z instrukcjami integracji pobierania pakietów zasobów z grą:

• Java
• Natywne
• Gry w jedność wyeksportowane do Gradle
  • Użyj bibliotek Java za pomocą JNI (np. biblioteki wbudowanej w Unity).

Tworzenie katalogów dla poszczególnych krajów

Jeśli używasz Gradle

Komponenty zostaną podzielone między zbiory krajów (maksymalnie 20), które zdefiniujesz później. Utwórz katalogi docelowe, korzystając z dotychczasowych katalogów pakietów zasobów utworzonych w ostatnim kroku i poprawiając odpowiedni folder (jak opisano poniżej) za pomocą #countries_latam, #countries_na itp. Korzystając z pakietów zasobów w grze, nie musisz adresować folderów za pomocą postfiksa (czyli postfiks jest automatycznie usuwany podczas procesu kompilacji).

Po zakończeniu poprzedniego kroku może to wyglądać tak:

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

Gdy uzyskujesz dostęp do plików w folderze, możesz użyć tej samej ścieżki bez postfixów (w tym przykładzie level1/assets/character-textures/ bez żadnych postfixów).

Tworzenie pakietu Android App Bundle

Gradle

W pliku build.gradle projektu skonfiguruj zależności tak, aby wtyczka Androida do obsługi Gradle i bundletool miały te wersje (lub nowsze):

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

Musisz też zaktualizować wersję Gradle do wersji 8.0 lub nowszej. Możesz to zmienić w gradle/wrapper/gradle-wrapper.propertiesw ramach projektu.

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

Na koniec musisz użyć biblioteki Play Asset Delivery Library. Jeśli nadal używasz monolitycznej biblioteki Play Core Library, zaktualizuj ją do wersji 1.8.3 lub nowszej. Zalecamy przejście na Bibliotekę Play Asset Delivery i w miarę możliwości zaktualizowanie do najnowszej wersji.

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

W pliku build.gradle głównego modułu aplikacji włącz podział kierowania na kraje:

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

Możesz też utworzyć pakiet Android App Bundle (AAB).

• Android Studio
• CLI

Bundletool

Utwórz pakiet za pomocą narzędzia bundletool. Na etapie dostosowywania pakietu AAB dodaj do pliku BundleConfig.pb następujące informacje.

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

Testowanie lokalne

Zanim przejdziesz dalej, zalecamy lokalne przetestowanie pakietu aplikacji i sprawdzenie, czy jest poprawnie skonfigurowany. Za pomocą bundletool (1.14.0 lub nowszej) możesz skompilować i przetestować aplikację lokalnie, wyraźnie podając odpowiedni kraj. Najpierw użyjesz narzędzia build-apks do wygenerowania zestawu plików .apks, a potem użyjesz narzędzia install-apks do wdrożenia aplikacji na połączonym urządzeniu. Możesz też określić, który zestaw krajów chcesz zainstalować, za pomocą flagi country-set. Więcej informacji o tej metodzie testowania lokalnego znajdziesz tutaj (pamiętaj, że ta strona nie została jeszcze zaktualizowana pod kątem kierowania reklam według kraju, dlatego nie ma na niej flagi 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

Opcjonalnie: możesz też użyć extract-apks, aby wyodrębnić zestaw plików APK dla określonego urządzenia. Użycie flagi get-device-spec i wskazanie kraju dla tego urządzenia nie zadziała w połączeniu z flagą --local-testing, co oznacza, że nie będzie można testować pakietów zasobów Fast Follow ani pakietów na żądanie.

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

Tworzenie konfiguracji kierowania na urządzenia za pomocą interfejsu Google Play Developer API

Pierwsze kroki z interfejsem Google Play Developer API (jeśli jeszcze nie zostały ukończone)

Aby skonfigurować kierowanie według kraju (czyli zdefiniować zestawy krajów), musisz przesłać konfigurację do Google Play za pomocą interfejsu Android Publisher API. Więcej informacji o interfejsie API znajdziesz, klikając powyższy link. Aby rozpocząć, musisz wykonać kilka czynności:

1. Utwórz (w razie potrzeby) projekt interfejsu API i połącz go z Konsolą Google Play.
2. Skonfiguruj klienta dostępu do interfejsu API

Dokumentację API znajdziesz tutaj. Jeśli później zdecydujesz się przesłać wersję za pomocą interfejsu API, użyjesz metod edycji. Przed użyciem interfejsu API zachęcamy też do zapoznania się z tą stroną.

Korzystanie z interfejsu Device Targeting Configuration API

Aby utworzyć konfigurację kierowania na urządzenia, możesz użyć tego wywołania interfejsu API:

Tworzenie konfiguracji kierowania na urządzenia

żądanie HTTP,	POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Parametry ścieżki	Nie dotyczy
Treść żądania	Konfiguracja kierowania na urządzenia
Treść odpowiedzi	Konfiguracja kierowania na urządzenia

Obiekt konfiguracji kierowania na urządzenia

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

Pola:

• device_confid_id (liczba całkowita): identyfikator odpowiadający tej konfiguracji kierowania na urządzenie.
• user_country_sets (obiekt): Definicje zestawów krajów
  • name (ciąg tekstowy): nazwa zestawu krajów (zdefiniowany przez Ciebie ciąg tekstowy).
  • country_codes (ciąg znaków): kraje należące do tego zestawu (format: ISO 3166-1 alfa-2).

Przed przesłaniem konfiguracji kierowania na urządzenia do Google Play możesz ją potwierdzić, postępując zgodnie z instrukcjami podanymi poniżej.

Pobieranie konfiguracji kierowania na urządzenia według identyfikatora

Konfigurację kierowania na urządzenie możesz pobrać za pomocą tego wywołania:

żądanie HTTP,	GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}
Parametry ścieżki	Nie dotyczy
Treść żądania	Nie dotyczy
Treść odpowiedzi	Konfiguracja kierowania na urządzenia

Pobieranie listy konfiguracji kierowania na urządzenia

Aby uzyskać ostatnie 10 konfiguracji kierowania na urządzenia, użyj tego wywołania (lub wybierz optymalny zestaw 10 konfiguracji za pomocą parametru zapytania page_token):

żądanie HTTP,	GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Parametry ścieżki	Nie dotyczy
Parametry zapytania	page_token (opcjonalny) – służy do określenia konkretnej grupy 10 kontrolerów DTC. Jest to przydatne, jeśli masz utworzonych ponad 10 konfiguracji DTC i chcesz wyświetlić te, które zostały utworzone przed 10 najnowszymi.
Treść żądania	Nie dotyczy
Treść odpowiedzi	Lista konfiguracji kierowania na urządzenia token_strony

Weryfikowanie konfiguracji kierowania na urządzenia

bundletool zawiera 2 polecenia, które pomogą Ci sprawdzić, czy konfiguracja kierowania na urządzenia działa zgodnie z oczekiwaniami, zanim prześlesz ją do Google Play.

Za pomocą bundletool print-device-targeting-config możesz sprawdzić, czy plik JSON jest poprawny pod względem składni.

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

Za pomocą bundletool evaluate-device-targeting-config możesz sprawdzić, który zestaw krajów pasuje do konkretnego urządzenia. Kraj użytkownika możesz podać za pomocą flagi --country-code.

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

Przesyłanie pakietu aplikacji na Androida do Google Play

Przez interfejs API

Za pomocą interfejsu Google Play Developer API możesz przesłać pakiet Android App Bundle do Google Play i powiązać z kompilacją określoną konfigurację kierowania na urządzenia.

Tutaj znajdziesz ogólny przegląd metod edycji, a także szczegółowe przykłady publikowania na różnych ścieżkach w Konsoli Google Play (w przypadku ostatniego linku użyj interfejsów API zgodnych z Androidem AAB, a nie interfejsów API zgodnych z Androidem APK, które są wymienione na tej stronie). Aby określić konfigurację kierowania na urządzenia w kompilacji, musisz dodać identyfikator konfiguracji do parametru zapytania deviceTierConfigId przy wywoływaniu metody edits.bundle.upload w ten sposób:

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

Za pomocą Konsoli Google Play

Aby przesłać pakiet aplikacji na Androida, wykonaj te instrukcje. Do pakietu aplikacji zostanie zastosowana najnowsza konfiguracja DTC.

Weryfikacja, czy dostarczane są prawidłowe komponenty

Aby mieć pewność, że na urządzenie są dostarczane tylko odpowiednie komponenty, użyj tej metody:

adb shell pm path {packageName}

Powinien pojawić się komunikat podobny do tego:

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

Pomocniczy

Szybki start z używaniem Curl

Poniżej przedstawiamy przykład (za pomocą narzędzia wiersza poleceń curl) tworzenia nowej konfiguracji kierowania na urządzenie oraz korzystania z interfejsu API Edycji w celu utworzenia nowej zmiany, przesłania nowej wersji AAB (po jej powiązaniu z konkretną konfiguracją kierowania na urządzenie), ustawienia konfiguracji ścieżki/wersji i zapisania zmiany. (czyli opublikujesz zmiany). Upewnij się, że masz dostęp do tych lokalizacji:

• klucz odpowiadający klientowi API,
• Nazwa pakietu Twojej aplikacji

Najpierw utwórz konfigurację kierowania na urządzenie i zapisz deviceTierConfigId, który otrzymasz po pomyślnym wywołaniu.

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

Rozpocznij edycję – otrzymasz identyfikator i czas wygaśnięcia zmiany. Zapisz identyfikator dla kolejnych wywołań.

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

Prześlij AAB, podając konfigurację kierowania na urządzenie jako parametr zapytania. Jeśli wywołanie zakończy się powodzeniem, zobaczysz kod wersji, sha1 i sha256 kompilacji. zapisz kod wersji na potrzeby następnego wywołania.

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}"

Przypisz pakiet AAB do wybranej ścieżki (do testowania zalecamy użycie ścieżki testu wewnętrznego, ale tutaj znajdziesz więcej informacji o różnych ścieżkach). Tutaj przeprowadzimy proste wdrożenie bez informacji o wersji. Więcej informacji o wdrażaniu etapowym i wersjach roboczych znajdziesz na tej stronie. Jeśli po raz pierwszy korzystasz z Publisher API, zalecamy utworzenie wersji roboczej i ukończenie jej w Konsoli Google Play, aby mieć pewność, że wszystko jest prawidłowo skonfigurowane.

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}

Zapisz zmiany (działaj ostrożnie, ponieważ w przeciwnym razie wszystkie zmiany zostaną wprowadzone w Google Play na wybranej ścieżce).

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