Kierowanie zasobów według kraju

Na czym polega kierowanie zasobów według kraju?

Kierowanie na zasoby według kraju pozwala dostarczać różne wersje (np. rozdzielczości) tego samego zasobu na urządzeniach w zależności od kraju, w którym znajduje się użytkownik. Możesz na przykład dostarczać niestandardowe zasoby do różnych krajów, w których jest dostępna Twoja aplikacja. Nie spowoduje to zwiększenia ogólnego rozmiaru gry, ponieważ będzie przesyłać tylko niezbędne zasoby na urządzenia użytkowników. Ten przykład nawiązuje do koncepcji pakietów zasobów w ramach funkcji Asset Delivery w Google Play. Jak widać poniżej, kryteria kierowania możesz zdefiniować za pomocą maksymalnie 20 zestawów krajów. W tym kontekście kraj urządzenia jest zwykle określany na podstawie adresu rozliczeniowego użytkownika zarejestrowanego na jego koncie Google Play.

Podobnie jak w przypadku Play Asset Delivery, kierowanie według kraju obsługuje Androida w wersji 4.1 (poziom API 16) i nowszych. Jednak na urządzeniach z Androidem 4.4 (poziom interfejsu API 19) lub niższym domyślny kraj jest ustawiany niezależnie od lokalizacji użytkownika.

Ścieżka programisty

Ogólnie, aby zintegrować z grą kierowanie według kraju, wykonaj te czynności:

1. Zintegruj w swojej grze kierowanie reklam według kraju (a także rozszerzenia Play Asset Delivery)
   • Zintegruj funkcję Play Asset Delivery ze swoją grą (jeśli jeszcze tego nie zrobiłeś).
   • Podziel zasoby na pakiety zasobów.
   • Spakuj kod i zasoby, aby utworzyć końcowy artefakt pakietu Android App Bundle, który prześlesz do Google Play.
2. Utwórz konfigurację kierowania na urządzenia, aby Google Play wiedział, jak przesyłać Twoje zasoby na urządzenia użytkowników.
   • Skonfiguruj interfejs Google Play Developer API (jeśli jeszcze nie został skonfigurowany), którego będziesz używać do wysyłania konfiguracji kierowania do Google Play.
   • Wykonaj podane czynności, aby utworzyć konfigurację kierowania.
3. Prześlij pakiet aplikacji na Androida do Play i sprawdź, czy wszystko jest poprawnie skonfigurowane.

Gradle to zalecany system kompilacji gier w języku Java i gier natywnych. W przypadku gier utworzonych za pomocą Gradle wykonaj te czynności, aby skonfigurować system kompilacji pod kątem kierowania na kraje.

Jeśli wyeksportujesz grę do Gradle, a potem dokończ jej kompilację, zalecamy wykonanie tych instrukcji (np. gry na Unity eksportowane do Gradle).

Konfigurowanie kierowania na zasoby według kraju w aplikacji

integracja Play Asset Delivery z grą (jeśli nie została jeszcze zakończona);

Usługa Play Asset Delivery (PAD) umożliwia dynamiczne przesyłanie zasobów gry w momencie instalacji lub w czasie działania. Tutaj znajdziesz opis tej funkcji. Gdy wybierzesz kierowanie na kraj, Google Play będzie wyświetlać zawartość Twoich pakietów zasobów na podstawie konfiguracji kraju określonego przez Ciebie w przypadku różnych lokalizacji użytkowników. Zalecamy, aby postępować zgodnie z poniższymi wskazówkami i wdrożyć PAD w swojej grze (np. utworzyć pakiety zasobów, wdrożyć pobieranie w grze), a potem zmodyfikować kod projektu, aby umożliwić kierowanie na kraje.

Gradle

W przypadku gier utworzonych za pomocą Gradle wykonaj te instrukcje tworzenia pakietów zasobów za pomocą Gradle, a potem postępuj zgodnie z instrukcjami integracji pobierania pakietów zasobów w Twojej grze:

• Java
• Reklamy natywne
• Gry na Unity eksportowane do Gradle
  • Użyj bibliotek Java za pomocą interfejsu JNI (np. biblioteki wbudowanej w Unity).

Tworzenie katalogów specyficznych dla kraju

Jeśli używasz Gradle

Teraz podzielisz swoje zasoby między zestawy krajów (maks. 20), które zdefiniujesz później. Utwórz katalogi docelowe, korzystając z istniejących katalogów pakietów zasobów utworzonych w ostatnim kroku i poprawiaj odpowiedni folder (jak opisano poniżej) za pomocą #countries_latam, #countries_na itp. Jeśli korzystasz z pakietów zasobów w grze, nie musisz wprowadzać do folderów za pomocą postfix (czyli postfix jest automatycznie usuwany podczas kompilacji).

Po poprzednim 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 uzyskasz dostęp do plików w folderze, możesz użyć tej samej ścieżki bez poprawek postów (w tym przykładzie będzie to level1/assets/character-textures/ bez poprawek).

Tworzenie pakietu Android App Bundle

Gradle

W pliku build.gradle projektu skonfiguruj zależności, aby dla wtyczki Androida do obsługi Gradle i narzędzia bundletool były dostępne poniższe (lub wyższe) wersje:

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

Musisz też zaktualizować Gradle do wersji 8.0 lub nowszej. Możesz to zmienić w sekcji gradle/wrapper/gradle-wrapper.properties w projekcie.

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

Na koniec musisz użyć Biblioteki Play Asset Delivery. Jeśli nadal używasz monolitycznej biblioteki podstawowej Play, zaktualizuj ją do wersji 1.8.3 lub nowszej. Zalecamy przejście na bibliotekę Play Asset Delivery i zaktualizowanie jej do najnowszej wersji, jeśli to możliwe.

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

Na koniec możesz utworzyć pakiet Android App Bundle (Android App Bundle).

• Android Studio,
• Interfejs wiersza poleceń

Narzędzie pakietu

Utwórz pakiet za pomocą narzędzia do łączenia i w trakcie dostosowywania pakietu AAB dodaj poniższe polecenie do pliku BundleConfig.pb.

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

Testowanie lokalne

Zanim przejdziesz dalej, zalecamy przetestowanie pakietu aplikacji lokalnie i upewnienie się, że wszystko jest prawidłowo skonfigurowane. Za pomocą bundletool (w wersji 1.14.0 lub nowszej) możesz kompilować i testować aplikację lokalnie, podając wyraźnie właściwy kraj. Najpierw za pomocą build-apks wygenerujesz zestaw plików .apks, a następnie wdrożysz aplikację na połączonym urządzeniu za pomocą install-apks. Za pomocą flagi country-set możesz też określić, który zestaw krajów chcesz zainstalować. Więcej informacji o tej metodzie testowania lokalnego znajdziesz tutaj (pamiętaj, że ta strona nie została jeszcze zaktualizowana pod kątem kierowania na kraje, więc brakuje w 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 konkretnego urządzenia. Jednak użycie danych get-device-spec i określenie kraju, z którego pochodzi to urządzenie, nie będzie działać w połączeniu z flagą --local-testing, co oznacza, że nie będzie można przetestować pakietów zasobów Szybkich śledzenia ani pakietów zasobó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 masz ukończonego kursu)

Aby skonfigurować kierowanie na kraje (tj. zdefiniować zestawy krajów), musisz użyć interfejsu API wydawcy Androida i przesłać konfigurację do Google Play. Więcej informacji o interfejsie API znajdziesz, klikając powyższy link. Jest kilka kroków, które musisz wykonać, aby rozpocząć:

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

Dokumentacja API znajdziesz tutaj. Jeśli zdecydujesz się później przesłać kompilację przez interfejs API, będziesz używać metod edycji. Zachęcamy również do zapoznania się z tą stroną przed użyciem interfejsu API.

Korzystanie z interfejsu API konfiguracji kierowania na urządzenia

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ądzenia.
• user_country_sets (obiekt): definicje krajów ustawione
  • name (ciąg znaków): nazwa zestawu krajów (określony przez Ciebie identyfikator ciągu).
  • country_codes (ciąg znaków): kraje należące do tego zestawu krajów (format: ISO 3166-1 alfa-2).

Zanim prześlesz ją do Google Play, możesz zweryfikować konfigurację kierowania na urządzenia, postępując zgodnie z podanymi niżej instrukcjami.

Pobierz konfigurację kierowania na urządzenia według identyfikatora

Konfigurację kierowania na urządzenia możesz pobrać za pomocą tego identyfikatora:

Żą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

Pobierz listę konfiguracji kierowania na urządzenia

Ostatnie 10 konfiguracji kierowania na urządzenia możesz uzyskać, korzystając z następującego wywołania (lub optymalnie określić zbiór 10 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 określonej grupy 10 kodów DTC. Jest to przydatne, jeśli masz utworzonych więcej niż 10 modyfikatorów bezpośrednich i chcesz zobaczyć te ostatnie sprzed 10 ostatnich.
Treść żądania	Nie dotyczy
Treść odpowiedzi	Lista konfiguracji kierowania na urządzenia page_token,

Weryfikowanie konfiguracji kierowania na urządzenia

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

Dzięki bundletool print-device-targeting-config możesz sprawdzić, czy składnia pliku JSON jest poprawna.

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

Dzięki bundletool evaluate-device-targeting-config możesz sprawdzić, który kraj będzie pasował 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 Android App Bundle 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 połączyć z kompilacją konkretną konfigurację kierowania na urządzenia.

Tutaj znajdziesz ogólny przegląd metod edycji i dokładniejsze przykłady publikowania na różnych ścieżkach w Konsoli Google Play (w ostatnim linku zalecamy użycie interfejsów API zgodnych z AAB zamiast interfejsów API zgodnych z APK, które są wymienione na stronie). Aby określić w kompilacji konfigurację kierowania na urządzenia, podczas wywoływania metody edits.bundle.upload dodaj identyfikator konfiguracji do parametru zapytania deviceTierConfigId:

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

W Konsoli Google Play

Aby przesłać pakiet Android App Bundle, postępuj zgodnie z tymi instrukcjami. Do pakietu aplikacji zostanie zastosowana najnowsza konfiguracja DTC.

Sprawdzanie, czy są dostarczane prawidłowe zasoby

Użyj tej metody, aby mieć pewność, że na urządzenie są przesyłane tylko prawidłowe zasoby

adb shell pm path {packageName}

Zobaczysz coś takiego:

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

Pomoc

Szybkie wprowadzenie do Curl

Poniżej znajdziesz przykład (za pomocą narzędzia wiersza poleceń curl) tworzenia nowej konfiguracji kierowania na urządzenia oraz korzystania z interfejsu Edits API do tworzenia zmian, przesyłania nowego pakietu aplikacji na Androida (powiązania go z konkretną konfiguracją kierowania na urządzenia), ustawiania konfiguracji ścieżki/wersji i zatwierdzenia zmiany. W ten sposób opublikujesz informacje o zmianie. Musisz mieć:

• Klucz odpowiadający Twojemu klientowi interfejsu API.
• nazwę pakietu aplikacji;

Najpierw utwórz konfigurację kierowania na urządzenia i zanotuj deviceTierConfigId, które otrzymasz po udanym 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 modyfikacji. 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 pakiet aplikacji na Androida, określając konfigurację kierowania na urządzenia jako parametr zapytania. Jeśli wywołanie zakończy się powodzeniem, zobaczysz kod wersji, sha1 i sha256 kompilacji. Zapisz kod wersji do 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 aplikacji do odpowiedniej ścieżki (do testowania zalecamy użycie ścieżki testu wewnętrznego, ale tutaj znajdziesz więcej informacji o różnych ścieżkach). Tutaj przeprowadzamy proste wdrożenie bez informacji o wersji. Na tej stronie znajdziesz więcej informacji o wdrażaniu etapowym, wersjach roboczych i informacjach o wersji. Jeśli po raz pierwszy korzystasz z interfejsu Publisher API, zalecamy utworzenie go w wersji roboczej i dokończenie aktualizacji w Konsoli Google Play, aby mieć pewność, że wszystko jest skonfigurowane prawidłowo.

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}

Zatwierdź zmiany (działaj ostrożnie, ponieważ spowoduje to opublikowanie wszystkich zmian w Google Play na odpowiedniej ścieżce).

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