Targeting per dispositivo per i moduli condizionali

Che cos'è il targeting per dispositivo per i moduli condizionali?

Il targeting per dispositivo ti consente di pubblicare moduli delle funzionalità condizionali sui dispositivi in base al loro hardware. Ad esempio, puoi scegliere di rendere disponibili alcune funzionalità solo sui dispositivi di fascia alta e non quelle che non sono in grado di utilizzare (per risparmiare spazio su questi dispositivi). Questo si basa sul concetto di moduli delle funzionalità in Play Feature Delivery. Come vedrai di seguito, hai la possibilità di definire i criteri di targeting (per ora in base alla RAM, a modelli di dispositivi specifici o a funzionalità di sistema disponibili) e targetizzare i moduli a gruppi di dispositivi specifici.

Percorso dello sviluppatore

A livello generale, per integrare il targeting per dispositivo nell'applicazione esistente, devi seguire questi passaggi:

  1. Sviluppa una funzionalità da fornire solo a un gruppo di dispositivi in base al loro hardware.
    • Implementa questa funzionalità come modulo della funzionalità.
    • Nella sezione delle condizioni del modulo di AndroidManifest.xml, specifica a quali gruppi di dispositivi deve essere caricato.
  2. Crea la tua configurazione di targeting per dispositivo, in modo che Play sappia come pubblicare i tuoi moduli delle funzionalità sui dispositivi degli utenti.
    • Imposta l'API Google Play Developer (se non è già stata completata), che utilizzerai per inviare le configurazioni DT a Play
    • Segui i passaggi per creare la configurazione DT
  3. Carica il tuo AAB su Play ed esegui un test per assicurarti che tutto sia configurato correttamente

Questo documento descrive come aggiungere il targeting per dispositivo per la pubblicazione condizionale utilizzando il plug-in Android per Gradle.

Crea modulo funzionalità condizionale con targeting per dispositivo

Aggiunta di un modulo relativo alle funzionalità nell'app

Play Feature Delivery ti consente di offrire determinate funzionalità della tua app in base a condizioni o scaricate on demand. Puoi leggere una panoramica al riguardo qui. Con il targeting per dispositivo puoi pubblicare una funzionalità in modo condizionale ai dispositivi assegnati ai gruppi forniti.

Per utilizzare i file DT per la consegna condizionale, devi usare bundletool 1.7.0 e versioni successive. Per farlo, devi specificare esplicitamente la versione bundletool per il plug-in Android Gradle. Puoi farlo nella sezione del buildscript del file build.gradle principale:

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

Per creare un modulo delle funzionalità, segui queste istruzioni per modularizzare un'applicazione Android.

Una volta completato lo sviluppo della funzionalità, puoi specificare le condizioni di invio in base al targeting per dispositivo nelle AndroidManifest.xml della funzionalità. Devi fornire una condizione del gruppo di dispositivi all'interno di un elemento dist:conditions di dist:module. Le informazioni generali sulle condizioni sono disponibili qui. Per i gruppi di dispositivi, sono disponibili nuove condizioni in cui è possibile specificare tutti i gruppi a cui questa funzionalità deve essere distribuita:

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

Ad esempio, supponiamo che tu abbia definito un gruppo di dispositivi denominato _my_group1 (apprenderai come definirlo nella sezione Creare una configurazione di targeting per dispositivo di seguito). Se il modulo delle funzionalità deve essere pubblicato solo per dispositivi che appartengono a _my_group1, i relativi AndroidManifest.xml dovrebbero avere il seguente aspetto:

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

Per una funzionalità che ha come target sia _my_group1 che _my_group2, AndroidManifest.xml ha il seguente aspetto:

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

Al termine, puoi creare il tuo Android App Bundle (AAB).

Test locale

Prima di continuare, ti consigliamo di testare a livello locale l'app bundle per assicurarti che tutto sia configurato correttamente. Con bundletool crei e testi la tua app in locale, specificando esplicitamente il gruppo di dispositivi corretto. Devi prima utilizzare build-apks per generare un set di file .apks, quindi eseguire il deployment della tua app su un dispositivo connesso utilizzando install-apks. Puoi anche specificare quali gruppi vuoi installare tramite il flag device-groups. Puoi trovare ulteriori informazioni su questo metodo di test locale qui. Tieni presente che questa pagina non è stata ancora aggiornata per DT e non contiene quindi il flag 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

In alternativa: puoi anche usare extract-apks per estrarre un set di APK per un dispositivo specifico (utilizzando get-device-spec e specificando i gruppi di dispositivi per questo dispositivo).

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

Creazione di una configurazione del targeting per dispositivo tramite l'API Google Play Developer

Guida introduttiva all'API Google Play Developer (se non è già stata completata)

Per configurare il targeting per dispositivo (definire i gruppi di dispositivi), devi utilizzare l'API Android Publisher per caricare la configurazione su Google Play. Per saperne di più sull'API, visita il link riportato sopra. Per iniziare, sono disponibili alcuni passaggi da seguire:

  1. Crea (se necessario) e collega il tuo progetto API a Google Play Console
  2. Configurare un client di accesso API

Puoi trovare il riferimento per l'API qui. In seguito, se scegli di caricare la build tramite l'API, utilizzerai i metodi Edits. Inoltre, ti consigliamo di esaminare questa pagina prima di utilizzare l'API.

Utilizzo dell'API Device Targeting Configuration

Puoi utilizzare la seguente chiamata API per creare la configurazione del targeting per dispositivo:

Crea configurazione targeting per dispositivo

Richiesta HTTP POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Parametri percorso N/A
Corpo della richiesta Configurazione del targeting per dispositivo
Corpo della risposta Configurazione del targeting per dispositivo
Oggetto configurazione targeting dispositivo
{
  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
            }
          ]
        }
      ]
    }
  ]
}

Campi:

  • device_tier_config_id (numero intero): ID corrispondente a questa configurazione di targeting per dispositivo

  • device_groups (oggetto): definizioni di gruppi.

    • name (stringa): nome del gruppo di dispositivi (un ID stringa da te definito).
    • device_selectors (oggetto): requisiti specifici per l'appartenenza di un dispositivo a questo gruppo.
    • device_ram (oggetto): requisiti di RAM del dispositivo
      • min_bytes (numero intero): RAM minima richiesta (in byte)
      • max_bytes (numero intero): RAM massima richiesta (in byte)
    • included_device_ids (oggetto): i modelli di dispositivi da includere in questo selettore (massimo 10.000 device_id per gruppo). Un dispositivo deve essere in questo elenco per corrispondere al selettore. Questa è una condizione necessaria, ma non sufficiente, per corrispondere al selettore completo (vedi la nota riportata di seguito sulla combinazione dei requisiti in un selettore).
      • build_brand (stringa): il produttore del dispositivo
      • build_device (stringa): il codice del modello del dispositivo.
    • excluded_device_ids (oggetto): i modelli di dispositivi da escludere in questo selettore (massimo 10.000 device_id per gruppo). Un dispositivo di questo elenco non corrisponderà al selettore, anche se soddisfa tutti gli altri requisiti del selettore.
      • build_brand (stringa): il produttore del dispositivo
      • build_device (stringa): il codice del modello del dispositivo.

    • required_system_features (oggetto): le funzionalità che un dispositivo deve essere incluso nel selettore (massimo 100 funzionalità per gruppo). Un dispositivo deve avere tutte le funzionalità di sistema in questo elenco per corrispondere al selettore. Questa è una condizione necessaria, ma non sufficiente, per corrispondere al selettore completo (vedi la nota di seguito sulla combinazione dei requisiti in un selettore).

      Riferimento alle funzionalità di sistema

      • name (stringa): una funzionalità del sistema.

    • forbidden_system_features (oggetto): funzionalità che un dispositivo non deve necessariamente essere incluso in questo selettore (massimo 100 funzionalità per gruppo). Se un dispositivo dispone di una qualsiasi delle funzionalità di sistema presenti in questo elenco, non corrisponde al selettore, anche se soddisfa tutti gli altri requisiti del selettore.

      Riferimento alle funzionalità di sistema

      • name (stringa): una funzionalità del sistema.

Puoi trovare la formattazione corretta per il produttore del dispositivo e il codice del modello nel Catalogo dei dispositivi su Google Play Console in uno dei seguenti modi:

  • Ispezione dei singoli dispositivi tramite il Catalogo dei dispositivi e individuazione del codice del produttore e del modello nelle posizioni, come mostrato nell'esempio di seguito (per Google Pixel 4a, il produttore è "Google" e il codice del modello è "sunfish")".

    pagina pixel 4a nel catalogo dei dispositivi

    pagina pixel 4a nel catalogo dei dispositivi

  • Scaricando un file CSV dei dispositivi supportati e utilizzando, rispettivamente, i campi Manufacturer e Model Code per i campi build_brand e build_device.

Ad esempio, il gruppo seguente corrisponde a tutti i dispositivi con più di 4 GB di RAM, ad eccezione di Pixel 5 (Google Redfin) e di Pixel 3 (Google Blueline, che ha meno di 4 GB di 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"
          }
        ]
      }
    ]
  }
]

Puoi leggerlo come segue:

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

Puoi seguire le istruzioni riportate di seguito per convalidare la configurazione del targeting per dispositivo prima di caricarla su Google Play.

Ottieni configurazione targeting per dispositivo per ID

Puoi recuperare una configurazione di targeting per dispositivo specifica per ID utilizzando la seguente chiamata:

Richiesta HTTP GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}
Parametri percorso N/A
Corpo della richiesta N/A
Corpo della risposta Configurazione del targeting per dispositivo

Ottieni elenco di configurazioni di targeting per dispositivo

Puoi ottenere le ultime 10 configurazioni di targeting per dispositivo alla chiamata seguente (o specificare in modo ottimale un set di dieci utilizzando il parametro di query page_token):

Richiesta HTTP GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Parametri percorso N/A
Parametri di ricerca page_token (facoltativo): utilizzato per specificare un gruppo specifico di 10 DTC. Ciò è utile se hai creato più di 10 DTC e vuoi visualizzare quelli creati prima delle ultime 10.
Corpo della richiesta N/A
Corpo della risposta Elenco di configurazioni del targeting per dispositivo

page_token

Convalida della configurazione del targeting per dispositivo

bundletool include due comandi che ti consentono di verificare che la configurazione del targeting per dispositivo funzioni come previsto prima di caricarla su Google Play.

Con bundletool print-device-targeting-config, puoi verificare che il file JSON sia sintatticamente corretto e visualizzare i gruppi di dispositivi in un formato più leggibile.

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

Con bundletool evaluate-device-targeting-config, puoi valutare quali gruppi corrisponderebbero a un dispositivo specifico. Puoi connettere il dispositivo di destinazione alla workstation e utilizzare il flag --connected-device oppure compilare manualmente un file JSON con le proprietà del dispositivo e fornirlo tramite il flag --device-properties.

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

Il file delle proprietà del dispositivo deve essere un file JSON che segue la struttura protobuf DeviceProprietà. Ecco alcuni esempi:

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

Caricare l'Android App Bundle su Google Play

Tramite API

Puoi utilizzare l'API Google Play Developer per caricare l'Android App Bundle su Google Play e collegare una specifica configurazione di targeting per dispositivo alla build.

Qui è disponibile una panoramica generale dei metodi di modifica, oltre a esempi più dettagliati sul rilascio per i diversi canali in Google Play Console (per l'ultimo link, ti consigliamo di utilizzare le API idonee per AAB anziché l'API compatibile con l'APK elencate nella pagina). Per specificare la configurazione del targeting per dispositivo per la build, dovrai aggiungere l'ID di configurazione al parametro di query deviceTierConfigId mentre chiami il metodo edits.bundle.upload, in questo modo:

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

Tramite Google Play Console

Puoi seguire queste istruzioni per caricare il tuo Android App Bundle. All'app bundle verrà applicata la configurazione DTC più recente.

Ausiliario

Guida rapida all'utilizzo di Curl

Di seguito è riportato un esempio (utilizzando lo strumento a riga di comando curl) di creazione di una nuova configurazione di targeting per dispositivo e l'utilizzo dell'API Edits per creare una nuova modifica, caricare un nuovo AAB (associandolo a una configurazione di targeting per dispositivo specifica), impostare la configurazione di monitoraggio/release ed eseguire il commit della modifica (rendendo pubblica la modifica). Assicurati di avere la posizione di:

  • La chiave corrispondente al tuo client API
  • Il nome del pacchetto della tua app

Innanzitutto, crea una configurazione di targeting per dispositivo e prendi nota del deviceTierConfigId che riceverai se la chiamata andrà a buon fine.

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

Avvia una modifica: riceverai un ID e una data di scadenza per la modifica. Salva l'ID per le chiamate seguenti.

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

Carica l'AAB, specificando la configurazione del targeting per dispositivo (deviceTierConfigId) come parametro di query. Se la chiamata ha esito positivo, vedrai il codice di versione, sha1 e sha256 della build. Salva il codice di versione per la chiamata successiva.

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}

Assegna l'AAB al canale desiderato (per i test, è consigliabile utilizzare il canale di test interno, ma puoi scoprire di più sui diversi canali qui), qui viene eseguita una semplice implementazione senza note di rilascio, ma puoi leggere questa pagina per scoprire di più su come implementare le implementazioni graduali, le bozze di rilascio e le note di rilascio. Se è la prima volta che utilizzi l'API Publisher, ti consigliamo di crearla come bozza e di completare la release su Google Play Console per assicurarti che tutto sia stato configurato correttamente.

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}

Esegui il commit delle modifiche (procedi con cautela, poiché in questo modo tutte le modifiche verranno pubblicate su Google Play per la traccia desiderata)

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