Targeting asset per paese

Che cos'è il targeting degli asset per paese?

Il targeting degli asset per paese ti consente di pubblicare versioni diverse (ad esempio le risoluzioni) dello stesso asset sui dispositivi in base al paese in cui si trova l'utente. Ad esempio, puoi scegliere di pubblicare asset personalizzati in diversi paesi in cui la tua app è disponibile, il tutto senza che ciò comporti alcun aumento delle dimensioni complessive del gioco fornendo solo gli asset necessari ai dispositivi degli utenti. Questa funzionalità si basa sul concetto di pacchetti di asset in Asset Delivery di Play. Come indicato di seguito, puoi definire i criteri di targeting con un massimo di 20 insiemi di paesi. In questo contesto, il paese del dispositivo è in genere determinato dall'indirizzo di fatturazione dell'utente registrato nel suo account Google Play.

Come Play Asset Delivery, il targeting per paese supporta Android 4.1 (livello API 16) e versioni successive. Tuttavia, sui dispositivi con Android 4.4 (livello API 19) o versioni precedenti, il paese predefinito impostato viene pubblicato indipendentemente dalla località dell'utente.

Percorso dello sviluppatore

A livello generale, per integrare il targeting per paese nel tuo gioco esistente, segui i passaggi:

1. Integra il targeting per paese (e, per estensione, Play Asset Delivery) all'interno del tuo gioco
   • Integrare Play Asset Delivery nel tuo gioco (se non l'hai già fatto)
   • Dividi gli asset in pacchetti di asset.
   • Raggruppa il codice e gli asset per l'elemento Android App Bundle finale che caricherai su Play.
2. Crea la tua configurazione di targeting per dispositivo affinché Play sappia come inviare le tue risorse ai dispositivi degli utenti.
   • Imposta l'API Google Play Developer (se non è già stata completata), che è quella che utilizzerai per inviare le configurazioni di targeting a Google Play.
   • Segui i passaggi per creare la configurazione di targeting.
3. Carica il tuo AAB su Play ed esegui un test per assicurarti che tutto sia configurato correttamente

Gradle è il sistema di build consigliato per Java e giochi nativi. Per i giochi creati con Gradle, segui questi passaggi per configurare il sistema di build in modo da creare il tuo AAB con il supporto per il targeting per paese.

Se esporti il gioco in Gradle e poi completi la build lì, ti consigliamo di seguire queste istruzioni (ad esempio, i giochi Unity esportati in Gradle)).

Impostare il targeting degli asset per paese nella tua app

Integrazione di Play Asset Delivery nel tuo gioco (se non l'hai già completata)

Play Asset Delivery (PAD) ti consente di pubblicare dinamicamente gli asset del tuo gioco al momento dell'installazione o nel runtime e puoi leggere una panoramica a riguardo qui. Con il targeting per paese, Google Play pubblica i contenuti dei tuoi pacchetti di asset in base alle configurazioni dei paesi impostati per le diverse località degli utenti. Ti consigliamo di seguire le indicazioni riportate di seguito e di integrare PAD nel tuo gioco (ovvero creare pacchetti di asset, implementare il recupero nel gioco) e poi modificare il codice del progetto per attivare il targeting per paese.

Gradle

Per i giochi creati con Gradle, segui queste istruzioni per creare pacchetti di asset con Gradle, quindi segui le istruzioni per integrare il recupero dei pacchetti di asset nel tuo gioco:

• Java
• Nativo
• Giochi Unity esportati in Gradle
  • Utilizza le librerie Java tramite JNI (ad esempio quella integrata in Unity).

Creazione di directory specifiche per i paesi

Se utilizzi Gradle

Ora suddividi gli asset tra gli insiemi di paesi (massimo 20) che definirai in seguito. Per creare le directory scelte come target, segui le directory dei gruppi di asset esistenti create nell'ultimo passaggio e pubblica la correzione della cartella appropriata (come descritto di seguito) con #countries_latam, #countries_na e così via. Se utilizzi i pacchetti di asset nel tuo gioco, non dovrai gestire le cartelle in base al postfix (in altre parole, il postfix viene rimosso automaticamente durante il processo di creazione).

Dopo il passaggio precedente, l'aspetto potrebbe essere simile al seguente:

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

Quando accedi ai file nella cartella, puoi utilizzare lo stesso percorso senza correzione dei post (in questo esempio farei riferimento a level1/assets/character-textures/ senza postfix).

Creazione di Android App Bundle

Gradle

Nel file build.gradle del progetto, configura le dipendenze in modo che abbiano le versioni seguenti (o successive) per il plug-in Android Gradle e bundletool:

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

Dovrai anche aggiornare la versione di Gradle alla versione 8.0 o successiva. Puoi aggiornarlo in gradle/wrapper/gradle-wrapper.properties all'interno del progetto.

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

Infine, dovrai utilizzare la libreria di distribuzione degli asset di Google Play; se continui a usare la libreria monolitica di base di Play, aggiornala alla versione 1.8.3 o successiva. Ti consigliamo di passare alla Raccolta asset di pubblicazione di Google Play e di eseguire l'aggiornamento all'ultima versione, 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 del targeting per paese:

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

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

• Android Studio
• Interfaccia a riga di comando

Bundletool

Crea il tuo bundle con bundletool e durante la personalizzazione dell'AAB, aggiungi quanto segue al file BundleConfig.pb.

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

Test locale

Prima di continuare, ti consigliamo di testare a livello locale l'app bundle per assicurarti che tutto sia configurato correttamente. Se utilizzi bundletool (1.14.0 o versioni successive), crei e testi la tua app in locale, specificando esplicitamente il paese corretto. Devi prima utilizzare build-apks per generare un insieme di file .apks, quindi eseguire il deployment della tua app su un dispositivo connesso utilizzando install-apks. Puoi anche specificare il set di paesi per cui vuoi installare l'app tramite il flag country-set. Puoi trovare ulteriori informazioni su questo metodo di test locale qui (tieni presente che questa pagina non è stata ancora aggiornata per il targeting per paese e non è quindi presente il flag 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

In alternativa: puoi anche usare extract-apks per estrarre un set di APK per un dispositivo specifico. Tuttavia, l'utilizzo di get-device-spec insieme alla specifica del paese per questo dispositivo non funzionerà insieme al flag --local-testing, quindi non potrai testare i pacchetti di asset fast-follow o on demand.

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

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 in base al paese (ovvero definire i set di paesi) dovrai usare 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. Imposta 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 di modifica. Inoltre, ti consigliamo di esaminare questa pagina prima di utilizzare l'API.

Utilizzo dell'API Device Targeting Configuration

Per creare la configurazione del targeting per dispositivo, puoi utilizzare la seguente chiamata API:

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

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

Campi:

• device_confid_id (numero intero): ID corrispondente a questa configurazione di targeting per dispositivo.
• user_country_sets (oggetto): definizioni degli insiemi di paesi
  • name (stringa): il nome del paese impostato (un ID stringa da te definito).
  • country_codes (stringa). Paesi che appartengono a questo insieme di paesi (formato: ISO 3166-1 alpha-2).

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 in base all'ID utilizzando la seguente chiamata:

Richiesta HTTP	GET https://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	GET https://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 token_pagina

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 la sintassi del file JSON sia corretta.

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

Con bundletool evaluate-device-targeting-config, puoi valutare quale paese impostato corrisponde a un dispositivo specifico. Puoi indicare il paese dell'utente con la bandierina --country-code.

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

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 durante la chiamata al 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.

Verifica del caricamento degli asset corretti in corso...

Utilizza il metodo seguente per assicurarti che sul dispositivo vengano inviate solo le risorse corrette

adb shell pm path {packageName}

Il risultato dovrebbe essere simile al seguente:

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

Ausiliario

Guida rapida all'utilizzo di Curl

Di seguito è riportato un esempio (utilizzando lo strumento a riga di comando curl) della creazione di una nuova configurazione di targeting per dispositivo e dell'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 così pubblica la modifica). Assicurati di avere la località 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 valore deviceTierConfigId che riceverai se la chiamata viene eseguita correttamente.

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

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 come parametro di query. Se la chiamata ha esito positivo, vedrai il codice di versione, sha1 e sha256 della build. Salva il codice 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="{deviceTargetingConfigID}"

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 completarla in 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}'</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 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