Che cos'è il targeting per livello di dispositivo?
Il targeting per livello di dispositivo ti consente di pubblicare versioni diverse (ad es. risoluzioni e così via) dello stesso asset sui dispositivi in base al loro hardware. Ad esempio, puoi scegliere di pubblicare asset a bassa risoluzione su dispositivi di fascia bassa per migliorare le prestazioni e pubblicare asset ad alta risoluzione su dispositivi di fascia alta per migliorare la qualità grafica, il tutto senza aumentare le dimensioni complessive del gioco pubblicando solo gli asset necessari sui dispositivi degli utenti. Questo si basa sul concetto di pacchetti di asset in Play Asset Delivery. Come vedrai di seguito, hai la possibilità di definire i criteri dei livelli (per ora in base alla RAM, a modelli di dispositivi specifici o alle funzionalità di sistema disponibili) e puoi utilizzare fino a 5 livelli.
Come Play Asset Delivery, il targeting per livello del dispositivo supporta l'API 16 (Jelly Bean 4.1) e versioni successive, ma sui dispositivi con API 19 (KitKat 4.4.X) e versioni precedenti viene pubblicato il livello predefinito indipendentemente dalla build del dispositivo.
Percorso dello sviluppatore
A livello generale, per integrare DTT nel tuo gioco esistente, devi seguire questi passaggi:
- Integra il targeting a livello di dispositivo (e, per estensione, Play Asset Delivery)
all'interno del tuo gioco.
- Integrare Play Asset Delivery nel gioco (se non lo hai già fatto)
- Suddividere gli asset in pacchetti di asset
- Raggruppa il codice e gli asset per l'elemento Android App Bundle finale che caricherai su Play.
- Crea la configurazione del targeting per livello di dispositivo in modo che Google Play sappia come pubblicare gli asset sui dispositivi degli utenti.
- Configura l'API Google Play Developer (se non l'hai già fatto), che utilizzerai per inviare le configurazioni DTT a Google Play.
- Segui i passaggi per creare la configurazione DTT.
- Carica il tuo AAB su Play ed esegui il test per assicurarti che tutto sia configurato correttamente
Nella prima sezione vedrai i fork nella guida a seconda del sistema di compilazione in uso. Il sistema scelto dipende dal motore in uso e dalla configurazione esistente.
- Gradle (consigliato per i giochi Java e nativi): per i giochi creati
con Gradle, segui questi passaggi per configurare il sistema di compilazione in modo da
creare l'AAB con il supporto DTT.
- Se esporti il tuo gioco in Gradle e poi completi la compilazione lì, ti consigliamo di seguire queste istruzioni (ad es. Giochi Unity esportati in Gradle))
- Plug-in Unity: ti forniremo pacchetti unity da importare nel tuo progetto Unity, che ti consentiranno di configurare e creare il tuo AAB con il supporto DTT.
Configurare il targeting per livello del dispositivo all'interno dell'app
Integrare Play Asset Delivery nel gioco (se non è già stato completato)
Play Asset Delivery (PAD) ti consente di pubblicare dinamicamente gli asset del tuo gioco al momento dell'installazione o in fase di esecuzione. Puoi leggere una panoramica qui. Con il targeting per livello di dispositivo, Google Play pubblica pacchetti di asset in base alle configurazioni dei livelli di dispositivo prescritte per i diversi livelli di dispositivi. Ti consigliamo di seguire le indicazioni riportate di seguito e di integrare PAD nel tuo gioco (ad es. creare pacchetti di asset, implementare il recupero nel gioco) e poi modificare il codice del progetto per attivare il targeting per livello del dispositivo.
Gradle
Per i giochi creati con Gradle, segui queste istruzioni per creare i pacchetti di asset con Gradle, quindi segui le istruzioni per integrare il recupero dei pacchetti di asset all'interno del gioco:
- Java
- Nativo
- Giochi Unity esportati in Gradle
- Utilizza le librerie Java tramite JNI (ad esempio quella integrata in Unity).
Unity
Per i giochi creati in Unity, dovrai configurare i pacchetti di asset utilizzando la classe AssetPackConfig
, come descritto in queste istruzioni.
Creazione di directory specifiche per il livello del dispositivo
Se utilizzi Gradle
Ora suddividerai le risorse tra i N livelli (massimo 5) che definirai in un secondo momento. Crea le directory DTT prendendo le directory dei pacchetti di asset esistenti create nell'ultimo passaggio e correggendo la cartella appropriata (come descritto di seguito) con #tier_0, #tier_1, #tier_2 e così via. Quando utilizzi i pacchetti di asset nel gioco, non dovrai gestire le cartelle per postfix (in altre parole, il postfix viene rimosso automaticamente durante il processo di creazione).
Dopo il passaggio precedente, il codice potrebbe avere il seguente aspetto:
...
.../level1/src/main/assets/character-textures#tier_2/
.../level1/src/main/assets/character-textures#tier_1/
.../level1/src/main/assets/character-textures#tier_0/
...
Quando accedi ai file all'interno della cartella, puoi utilizzare lo stesso percorso senza postfix (in questo esempio, farò riferimento a level1/assets/character-textures/
senza postfix).
Se utilizzi Unity
Per aggiungere un asset pack che utilizza il DTT, puoi utilizzare i metodiAssetPackConfig
riportati di seguito:
/// Package the specified raw assets in the specified folders,
/// keyed by DeviceTier, in an AssetPack with the specified delivery mode.
public void AddAssetsFolders(
string assetPackName,
IDictionary<DeviceTier, string> deviceTierToAssetPackDirectoryPath,
AssetPackDeliveryMode deliveryMode)
/// Package the specified AssetBundle files, which vary only by DeviceTier,
/// in an AssetPack with the specified delivery mode.
public void AddAssetBundles(
IDictionary<DeviceTier, string> deviceTierToAssetBundleFilePath,
AssetPackDeliveryMode deliveryMode)
Ad esempio, supponiamo che tu abbia tre
AssetBundles
per il tuo personaggio a diversi livelli di dettaglio.
Per mappare questi AssetBundles
al livello di dispositivo corrispondente, utilizza il seguente snippet.
var assetPackConfig = new AssetPackConfig();
var tiers = new Dictionary<DeviceTier, string>
{
{0, "Assets/LowPoly/Character"},
{1, "Assets/Mid/Character"},
{2, "Assets/Detailed/Character"}
};
assetPackConfig.AddAssetBundles(tiers, AssetPackDeliveryMode.OnDemand);
Creazione dell'Android App Bundle
Gradle
Nel file build.gradle
del progetto, configura le dipendenze in modo che abbiano le versioni riportate di seguito (o successive) per il plug-in Android per Gradle e bundletool:
buildscript {
dependencies {
classpath 'com.android.tools.build:gradle:4.2.0'
classpath "com.android.tools.build:bundletool:1.7.1"
...
}
...
}
Dovrai anche aggiornare il tuo Gradle alla versione 6.7.1 o successiva.
Puoi aggiornare questa opzione in gradle/wrapper/gradle-wrapper.properties
all'interno del tuo progetto.
distributionUrl=https://services.gradle.org/distributions/gradle-6.7.1-all.zip
Infine, dovrai utilizzare la Play Asset Delivery Library. Se utilizzi ancora la Play Core Library monolitica, aggiornala alla versione 1.8.3 o successiva. Ti consigliamo di passare alla libreria Play Asset Delivery e di eseguire l'aggiornamento alla versione più recente, se possibile.
dependencies {
implementation 'com.google.android.play:asset-delivery:2.0.1'
...
}
Nel file build.gradle
del modulo dell'app principale, attiva la suddivisione DTT:
android {
bundle {
deviceTier {
enableSplit true
}
...
}
...
}
Infine, puoi creare il tuo Android App Bundle (AAB).
Bundletool
Crea il bundle con bundletool e
durante il passaggio per personalizzare l'AAB,
aggiungi quanto segue al file BundleConfig.pb
.
{
...
"optimizations": {
"splitsConfig": {
"splitDimension": [
...
{
"value": "DEVICE_TIER",
"negate": false,
"suffixStripping": {
"enabled": true,
}
}],
}
}
}
Unity
Dopo aver configurato il file AssetPackConfig
in modo da includere i pacchetti DTT, puoi passare la configurazione a uno dei seguenti metodi per creare l'AAB:
// Configures the build system to use the newly created assetPackConfig when
// calling Google > Build and Run or Google > Build Android App
Bundle.AssetPackConfigSerializer.SaveConfig(assetPackConfig);
// Alternatively, use BundleTool.BuildBundle to build an App Bundle from script
BuildBundle(new buildPlayerOptions(), assetPackConfig)
Test locale
Prima di procedere, ti consigliamo di testare l'app bundle a livello locale per assicurarti che sia tutto configurato correttamente. Con bundletool
(1.8.0 o versioni successive), puoi creare e testare localmente la tua app, specificando esplicitamente il livello dispositivo corretto. Devi prima utilizzare build-apks
per generare un insieme di .apks
file, quindi eseguire il deployment dell'app su un dispositivo connesso tramite install-apks
.
Puoi anche specificare il livello da installare tramite il flag device-tier. Puoi trovare ulteriori informazioni su questo metodo di test locale qui (tieni presente che questa pagina non è ancora stata aggiornata per il digitale terrestre e quindi manca il flag device-tier
).
bundletool build-apks --bundle=/path/to/app.aab --output=/path/to/app.apks --local-testing
bundletool install-apks --apks=/path/to/app.apks --device-tier=1
In alternativa: puoi anche utilizzare
extract-apks
per estrarre un
insieme di APK per un dispositivo specifico. Tuttavia, l'utilizzo di get-device-spec
e di specificare il livello del dispositivo per questo dispositivo non funzionerà in combinazione con il flag --local-testing
, il che significa che non potrai testare pacchetti di asset fast-follow o on demand.
bundletool get-device-spec --output=/path/to/device-spec.json --device-tier=1
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
Unity
L'opzione di menu Google -> Compila ed esegui compila ed esegue il gioco con il flag --local-testing
abilitato. Tuttavia, non consente di specificare il livello del dispositivo passato al comando install-apks
.
Se vuoi specificare un livello del dispositivo diverso da 0, devi:
- Crea l'AAB utilizzando l'opzione di menu Google -> Build Android App Bundle.
- Segui le istruzioni riportate nella sezione precedente per eseguire
bundletool
,build-apks
einstall-apks
sull'AAB compilato.
Creazione di una configurazione a livello dispositivo tramite l'API Google Play Developer
Inizia a utilizzare l'API Google Play Developer (se non l'hai già fatto)
Per configurare il targeting per dispositivo (ad es. definizione dei requisiti per ogni livello), devi utilizzare l'API Android Publisher per caricare la configurazione su Google Play. Puoi scoprire di più sull'API al link riportato sopra. Per iniziare, devi seguire alcuni passaggi:
- Crea (se necessario) e collega il progetto API a Google Play Console.
- Configura un client accesso API.
Puoi trovare il riferimento all'API qui. In seguito, se scegli di caricare la build tramite l'API, utilizzerai i metodi di modifica. Inoltre, ti invitiamo a esaminare questa pagina prima di utilizzare l'API.
Utilizzo dell'API Device Tier Configuration
Puoi utilizzare la seguente chiamata API per creare la configurazione a livello di dispositivo:
Crea configurazione livello dispositivo
Richiesta HTTP | POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs |
Parametri del percorso | N/D |
Corpo della richiesta | Configurazione del livello dispositivo |
Corpo della risposta | Configurazione livello dispositivo |
Oggetto di configurazione del livello del dispositivo
La definizione dei livelli di dispositivi prevede due passaggi:
- Definisci un insieme di gruppi di dispositivi.
- Definisci l'insieme di livelli dei dispositivi assegnando un livello ai gruppi di dispositivi.
Un gruppo di dispositivi è un insieme di dispositivi che corrispondono ai selettori definiti nella configurazione.
I selettori possono definire i requisiti per la RAM e il modello del dispositivo.
I gruppi sono identificati da un nome scelto da te; i gruppi possono sovrapporsi.
Successivamente, puoi definire l'insieme di livelli di dispositivo assegnando un ranking ai gruppi: ogni livello di dispositivo è definito dal suo livello e da un gruppo di dispositivi.
Se un dispositivo corrisponde a più livelli, gli verranno pubblicati i contenuti per il livello corrispondente più alto.
{ 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 } ] } ] } ], device_tier_set: { device_tiers: [ { level: int, device_group_names: [string] } ] } }
Campi:
- device_confid_id (numero intero): ID corrispondente a questa configurazione a livello di dispositivo.
device_groups (oggetto): definizioni dei gruppi
- name (stringa): il nome del gruppo di dispositivi (un ID stringa definito da te).
- device_selectors (oggetto): requisiti dei dispositivi affinché un dispositivo appartenga a questo gruppo.
- device_ram (oggetto): requisiti della RAM del dispositivo
- min_bytes (numero intero, incluso): RAM minima richiesta (in byte)
- max_bytes (numero intero, escluso): massima RAM richiesta (in byte)
- included_device_ids (oggetto): i modelli di dispositivi da includere in questo selettore (massimo 10000 device_id per gruppo). Un dispositivo deve essere presente in questo elenco per corrispondere al selettore. Questa è una condizione necessaria, ma non sufficiente per corrispondere al selettore completo (vedi la nota sopra sulla combinazione di requisiti in un selettore).
- build_brand (stringa): produttore del dispositivo
- build_device (stringa): codice del modello di dispositivo
- excluded_device_ids (oggetto): i modelli di dispositivi da escludere in questo selettore (massimo 10000 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): produttore del dispositivo
- build_device (stringa): codice del modello di dispositivo
required_system_features (oggetto): funzionalità che un dispositivo deve avere per essere incluso da questo selettore (massimo 100 funzionalità per gruppo). Un dispositivo deve avere tutte le funzionalità di sistema in questo elenco per corrispondere al selettore. Si tratta di una condizione necessaria, ma non sufficiente per la corrispondenza al selettore completo (vedi la nota sopra sulla combinazione di requisiti in un selettore).
Riferimento alle funzionalità di sistema
- name (stringa): una funzionalità di sistema
forbidden_system_features (oggetto): funzionalità che un dispositivo non deve devono essere incluso da questo selettore (massimo 100 funzionalità per gruppo). Se un dispositivo presenta una delle funzionalità di sistema 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à di sistema
device_tiers (oggetto): definizioni dei livelli
- level (int): il livello del livello
- group_name (array di stringhe): il nome dei gruppi di dispositivi che appartengono a questo livello
Puoi trovare la formattazione corretta per il codice del produttore e del modello del dispositivo utilizzando il Catalogo dei dispositivi su Google Play Console, in uno dei seguenti modi:
Ispezione dei singoli dispositivi utilizzando il Catalogo dei dispositivi e ricerca del codice del produttore e del modello nelle posizioni mostrate nell'esempio di seguito (per un Google Pixel 4a, il produttore è "Google" e il codice del modello è "sunfish").
Scaricare un file CSV dei dispositivi supportati e utilizzare Manufacturer e Model Code per i campi build_brand e build_device, rispettivamente.
Ecco un esempio di configurazione con tre livelli: il livello 2 utilizza il gruppo di dispositivi high (che include tutti i dispositivi superiori a 7 GB e Pixel 4), il livello 1 utilizza il gruppo di dispositivi medium (che include tutti i dispositivi tra 4 e 7 GB) e il livello 0, che è definito implicitamente come gruppo generico.
{
device_groups: [
{
name: 'high',
device_selectors: [
{
device_ram: {
min_bytes: 7516192768
},
},
{
included_device_ids: [
{
build_brand: 'google',
build_device: 'flame'
}
],
}
]
},
{
name: 'medium',
device_selectors: [
{
device_ram: {
min_bytes: 4294967296,
max_bytes: 7516192768
},
}
]
}
],
device_tier_set: {
device_tiers: [
{
level: 1,
device_group_names: [
'medium'
]
},
{
level: 2,
device_group_names: [
'high'
]
}
]
}
}
Puoi seguire le istruzioni riportate di seguito per convalidare la configurazione del targeting per dispositivo prima di caricarla su Google Play.
Recupera la configurazione del livello del dispositivo tramite ID
Puoi recuperare una configurazione del livello del dispositivo specifica tramite ID utilizzando la seguente chiamata:
Richiesta HTTP |
GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}
|
Parametri del percorso | N/D |
Corpo della richiesta | N/D |
Corpo della risposta | Configurazione livello dispositivo |
Recupera l'elenco delle configurazioni del livello del dispositivo
Puoi ottenere le ultime 10 configurazioni del livello del dispositivo in base alla seguente chiamata (o specificare in modo ottimale un insieme di dieci utilizzando il parametro di query page_token):
Richiesta HTTP | GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs |
Parametri del percorso | N/D |
Parametri di query | page_token (facoltativo) - utilizzato per specificare un gruppo specifico di 10 DTC. Questa opzione è utile se hai creato più di 10 DTC e vuoi visualizzare quelli creati prima dei 10 più recenti. |
Corpo della richiesta | N/D |
Corpo della risposta | Elenco delle configurazioni dei livelli di dispositivo
page_token |
Convalida della configurazione del targeting per dispositivo
bundletool
include due comandi che ti aiutano a verificare che la configurazione del targeting per dispositivo funzioni come previsto prima di caricarla su Google Play.
Con bundletool print-device-targeting-config
, puoi convalidare che il file JSON sia sintatticamente corretto e visualizzare i gruppi e i livelli 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
e livelli corrispondono a un dispositivo specifico. Puoi collegare il dispositivo di destinazione alla tua 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 del protobuf DeviceProperties. Ad esempio:
{
"ram": 2057072640,
"device_id": {
"build_brand":"google",
"build_device":"redfin"
},
"system_features": [
{
"name":"android.hardware.bluetooth"
},
{
"name":"android.hardware.camera"
}
]
}
Caricamento dell'app bundle Android su Google Play
Tramite API
Puoi utilizzare l'API Google Play per sviluppatori per caricare il tuo app bundle Android su Google Play e collegare una specifica configurazione di targeting per livello del dispositivo alla tua build.
È disponibile una
panoramica generale dei metodi di modifica qui,
oltre a
esempi più approfonditi sul rilascio nei diversi canali in Google Play Console
(per l'ultimo link, ti consigliamo di utilizzare le
API compatibili con AAB
anziché le
API compatibili con gli APK,
elencate nella pagina). Per specificare la configurazione del livello del dispositivo per la tua compilazione, dovrai aggiungere l'ID configurazione al parametro di query deviceTierConfigId
quando chiami il metodo edits.bundle.upload
, come segue:
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. La configurazione DTC più recente verrà applicata al tuo app bundle.
Per verificare che il bundle sia stato creato correttamente, vai a Explorer per app bundle (con la build corretta selezionata) > Caricamento, e fai clic su ogni pacchetto di asset. Dovrebbe essere indicato che hai N livelli che hai creato. In questo esempio, viene mostrato che ho tre livelli: 0, 1 e 2 per il mio asset pack main_asset.
Verificare che venga pubblicato il livello corretto
Utilizza il seguente metodo per assicurarti che al dispositivo venga fornito solo il livello corretto
adb shell pm path {packageName} |
Il risultato dovrebbe essere simile a questo:
package:{...}/base.apk
package:{...}/split_config.en.apk
package:{...}/split_config.xxhdpi.apk
package:{...}/split_main_asset.apk
package:{...}/split_main_asset.config.tier_2.apk
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 del livello del dispositivo e dell'utilizzo dell'API di modifica per creare una nuova modifica, caricare un nuovo AAB (associandolo con una configurazione del livello del dispositivo specifica), impostare la configurazione del canale/della release e commit della modifica. (rendendo la modifica pubblica). Assicurati di avere la posizione di:
- La chiave corrispondente al tuo client API
- Il nome del pacchetto della tua app
Innanzitutto, crea una configurazione del livello del dispositivo e prendi nota del valore deviceTierConfigId
che riceverai al termine di una chiamata andata a buon fine.
curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST -H "Content-Type: application/json" -d "{ device_groups: [ { name: 'high', device_selectors: [ { device_ram: { min_bytes: 7516192768 }, }, { included_device_ids: [ { build_brand: 'google', build_device: 'flame' } ], } ] }, { name: 'medium', device_selectors: [ { device_ram: { min_bytes: 4294967296, max_bytes: 7516192768 }, } ] } ], device_tier_set: { device_tiers: [ { level: 1, device_group_names: [ 'medium' ] }, { level: 2, device_group_names: [ 'high' ] } ] } }" https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Avvia una modifica: riceverai un ID e la data di scadenza della modifica. Salva l'ID per le chiamate successive.
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 livello del dispositivo come parametro di query. Se la chiamata è riuscita, vedrai un 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="{dttConfigID}"
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). Eseguiamo un semplice implementazione senza note di rilascio, ma puoi consultare questa pagina per scoprire di più su come eseguire implementazioni graduali, release in anteprima e note di rilascio. Se è la prima volta che utilizzi l'API Publisher, ti consigliamo di creare una release come bozza e di completarla in Google Play Console per assicurarti che sia tutto configurato correttamente.
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}
Esegui il commit delle modifiche (procedi con cautela, poiché in questo modo tutte le modifiche verranno pubblicate su 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