Kierowanie na urządzenia w przypadku modułów warunkowych

Czym jest kierowanie na urządzenia w przypadku modułów warunkowych?

Kierowanie na urządzenia umożliwia dostarczanie na urządzenia modułów funkcji warunkowych na podstawie ich sprzętu. Na przykład możesz zdecydować, że niektóre funkcje będą dostępne tylko na urządzeniach zaawansowanych, a nie na urządzeniach, które nie mają do nich dostępu (czyli zaoszczędzisz miejsce na tych urządzeniach). Tworząc funkcje na podstawie koncepcji modułów funkcji Play Feature Delivery. Jak zobaczysz poniżej, możesz zdefiniować kryteria kierowania (na razie na podstawie pamięci RAM, konkretnych modeli urządzeń lub dostępnych funkcji systemu) i kierować moduły na określone grupy urządzeń.

Ścieżka programisty

Ogólnie, aby zintegrować kierowanie na urządzenia z dotychczasową aplikacją, musisz wykonać te czynności:

1. Opracuj funkcję, którą chcesz udostępnić tylko na wybranych urządzeniach (w zależności od używanego sprzętu).
   • Wdróż tę funkcję jako moduł funkcji.
   • Określ w sekcji warunków modułu plik AndroidManifest.xml, do których grup urządzeń ma być dostarczany.
2. Utwórz konfigurację kierowania na urządzenia, aby Google Play wiedział, jak przesyłać moduły funkcji 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 przesyłania konfiguracji przenoszenia danych do Google Play.
   • Wykonaj kolejne kroki, by utworzyć konfigurację przenoszenia danych
3. Prześlij pakiet aplikacji na Androida do Play i sprawdź, czy wszystko jest poprawnie skonfigurowane.

W tym dokumencie opisujemy, jak dodać kierowanie na urządzenia na potrzeby wyświetlania warunkowego za pomocą wtyczki Androida do obsługi Gradle.

Tworzenie modułu funkcji warunkowych za pomocą kierowania na urządzenia

Dodawanie modułu funkcji do aplikacji

Play Feature Delivery umożliwia dostarczanie określonych funkcji aplikacji warunkowo lub pobieranie na żądanie. Tutaj znajdziesz opis tej funkcji. Kierowanie na urządzenia pozwala warunkowo udostępniać funkcję urządzeniom przypisanym do podanych grup.

Aby korzystać z przenoszenia danych do przesyłania warunkowego, musisz używać bundletool w wersji 1.7.0 lub nowszej. W tym celu musisz wyraźnie określić wersję narzędzia pakietu dla wtyczki Androida do obsługi Gradle. Możesz to osiągnąć w sekcji głównej pliku buildscript pliku build.gradle:

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

Aby utworzyć moduł funkcji, postępuj zgodnie z tymi instrukcjami modularyzacji aplikacji na Androida.

Po opracowaniu funkcji możesz określić warunki dostarczania na podstawie kierowania na urządzenia w AndroidManifest.xml Twojej funkcji. Musisz podać warunek grupy urządzeń w elemencie dist:conditions z dist:module. Ogólne informacje na temat warunków są dostępne tutaj. W przypadku grup urządzeń dostępne są nowe warunki, w których możesz określić wszystkie grupy, do których ma być dostarczana ta funkcja:

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

Załóżmy, że masz zdefiniowaną grupę urządzeń o nazwie _my_group1 (jak ją zdefiniować, z sekcji Tworzenie konfiguracji kierowania na urządzenia poniżej). Jeśli moduł funkcji powinien być dostarczany wyłącznie na urządzenia należące do grupy _my_group1, jego parametr AndroidManifest.xml powinien wyglądać tak:

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

W przypadku funkcji, która jest kierowana zarówno na _my_group1, jak i _my_group2, AndroidManifest.xml wygląda tak:

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

Gdy skończysz, możesz utworzyć pakiet Android App Bundle (Android App Bundle).

• Android Studio,
• Interfejs wiersza poleceń

Testowanie lokalne

Zanim przejdziesz dalej, zalecamy przetestowanie pakietu aplikacji lokalnie i upewnienie się, że wszystko jest prawidłowo skonfigurowane. Za pomocą bundletool możesz lokalnie kompilować i testować aplikację, wyraźnie wskazując prawidłową grupę urządzeń. Najpierw użyjesz narzędzia build-apks, aby wygenerować zestaw plików .apks, a następnie wdrożysz aplikację na połączonym urządzeniu za pomocą metody install-apks. Za pomocą flagi device-groups możesz też określić, które grupy chcesz zainstalować. Więcej informacji o tej metodzie testów lokalnych znajdziesz tutaj. Pamiętaj, że ta strona nie została jeszcze zaktualizowana do przenoszenia danych, więc brakuje flagi 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

Opcjonalnie: możesz też użyć extract-apks, aby wyodrębnić zestaw plików APK dla konkretnego urządzenia (za pomocą get-device-spec i określić grupy urządzeń dla tego urządzenia).

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

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 urządzenia (określić grupy urządzeń), musisz użyć interfejsu Android Publisher API, aby 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. Konfigurowanie 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 Edits. 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

{
  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
            }
          ]
        }
      ]
    }
  ]
}

Pola:

• device_tier_config_id (liczba całkowita): identyfikator odpowiadający tej konfiguracji kierowania na urządzenia

• device_groups (obiekt): definicje grup

  • name (ciąg znaków): nazwa grupy urządzeń (określony przez Ciebie ciąg znaków)
  • device_selectors (obiekt): wymagania dotyczące urządzeń, które musi spełniać urządzenie, które należy do tej grupy.
  • device_ram (obiekt): Wymagania dotyczące pamięci RAM urządzenia
    • min_bytes (liczba całkowita): minimalna wymagana ilość pamięci RAM (w bajtach)
    • max_bytes (liczba całkowita): maksymalna wymagana ilość pamięci RAM (w bajtach)
  • included_device_ids (obiekt): modele urządzeń, które mają być uwzględnione w tym selektorze (maksymalnie 10 000 identyfikatorów urządzeń na grupę). Aby można było dopasować selektor, na tej liście musi znajdować się jedno urządzenie. Jest to warunek niezbędny, ale niewystarczający, aby można było dopasować pełny selektor (patrz uwaga poniżej na temat łączenia wymagań w selektorze).
    • build_brand (ciąg znaków): Producent urządzenia
    • build_device (ciąg znaków): kod modelu urządzenia
  • excluded_device_ids (obiekt): modele urządzeń, które mają zostać wykluczone z tego selektora (maksymalnie 10 000 identyfikatorów urządzenia na grupę). Urządzenie z tej listy nie będzie pasować do selektora, nawet jeśli spełnia wszystkie pozostałe wymagania.
    • build_brand (ciąg znaków): Producent urządzenia
    • build_device (ciąg znaków): kod modelu urządzenia

  • required_system_features (obiekt): funkcje, które urządzenie musi znaleźć w tym selektorze (maksymalnie 100 funkcji na grupę). Aby można było dopasować selektor, na urządzeniu muszą znajdować się wszystkie funkcje systemowe z tej listy. Jest to warunek niezbędny, ale niewystarczający, aby można było dopasować pełny selektor (uwaga poniżej na temat łączenia wymagań w selektorze).

    Odniesienie do funkcji systemowych

    • name (ciąg znaków): funkcja systemowa

  • forbidden_system_features (obiekt): funkcje, których urządzenie nie może uwzględniać w tym selektorze (maksymalnie 100 funkcji na grupę). Jeśli urządzenie ma którąś z funkcji systemowych z tej listy, nie pasuje do selektora, nawet jeśli spełnia wszystkie pozostałe wymagania w selektorze.

    Odniesienie do funkcji systemowych

    • name (ciąg znaków): funkcja systemowa

Prawidłowe formatowanie dla producenta i kodu modelu urządzenia możesz znaleźć w Katalogu urządzeń w Konsoli Google Play, wykonując jedną z tych czynności:

• Sprawdzanie poszczególnych urządzeń za pomocą katalogu urządzeń i znajdowanie w nich producenta i kodu modelu, tak jak to widać na przykładzie poniżej. W przypadku telefonu Google Pixel 4a producentem jest „Google”, a kod modelu to „sunfish”)”.

  

  

• Pobierając plik CSV z obsługiwanymi urządzeniami i używając Manufacturer oraz Model Code w polach build_brand i build_device.

Na przykład ta grupa obejmuje wszystkie urządzenia z więcej niż 4 GB pamięci RAM, z wyjątkiem Pixela 5 (google redfin) i Pixela 3 (Google Blueline, który ma mniej niż 4 GB pamięci 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"
          }
        ]
      }
    ]
  }
]

Czytasz jako:

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

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ć według identyfikatora, używając tego wywołania:

Żądanie HTTP	GEThttps://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

Dziesięć ostatnich konfiguracji kierowania na urządzenia można uzyskać po tym wywołaniu (lub optymalnie określić zestaw 10 opcji za pomocą parametru zapytania page_token):

Żądanie HTTP	GEThttps://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 jednostek jednorazowych 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.

bundletool print-device-targeting-config pozwala sprawdzić poprawność składni pliku JSON i zwizualizować grupy urządzeń w bardziej czytelnym formacie.

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

Dzięki bundletool evaluate-device-targeting-config możesz ocenić, które grupy pasują do danego urządzenia. Podłącz urządzenie docelowe do stacji roboczej i użyj flagi --connected-device lub ręcznie skompilujesz plik JSON z właściwościami urządzenia i przekaż go za pomocą flagi --device-properties.

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

Plik właściwości urządzenia powinien być plikiem JSON zgodnym ze strukturą protokołu DeviceWłaściwości. Na przykład:

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

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 bardziej szczegółowe przykłady publikowania na różnych ścieżkach w Konsoli Google Play (w ostatnim linku należy podać interfejsy API zgodne 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.

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 udostępniania zmiany jako publicznej). Musisz mieć:

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

Najpierw utwórz konfigurację kierowania na urządzenia i zanotuj parametr deviceTierConfigId, który otrzymasz po udanym wywołaniu.

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

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 (deviceTierConfigId) jako parametr zapytania. Jeśli wywołanie się powiedzie, zobaczysz kod wersji, sha1 i sha256 kompilacji. Zapisz kod wersji do następnej rozmowy.

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}

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 prawidłowo skonfigurowane.

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}

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