Targeting asset per paese

Che cos'è il targeting per risorsa per paese?

Il targeting per asset per paese ti consente di pubblicare versioni diverse (ad esempio con risoluzioni diverse) dello stesso asset sui dispositivi in base al paese in cui si trova l'utente. Ad esempio, puoi scegliere di pubblicare asset personalizzati nei diversi paesi in cui la tua app è disponibile, il tutto senza determinare un aumento delle dimensioni complessive del gioco fornendo solo gli asset necessari ai dispositivi degli utenti. Questo si basa sul concetto di pacchetti di asset in Play Asset Delivery. Come vedrai di seguito, puoi definire i criteri di targeting con fino a 20 set di paesi. In questo contesto, il paese del dispositivo viene solitamente determinato dall'indirizzo di fatturazione registrato dall'utente sul proprio 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 posizione dell'utente.

Percorso dello sviluppatore

In linea generale, per integrare il targeting per paese nel tuo gioco esistente, segui questi passaggi:

1. Integrare il targeting per paese (e per estensione Play Asset Delivery) nel 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.
2. Creare la configurazione del targeting per dispositivo in modo che Play sappia come inviare gli asset ai dispositivi degli utenti.
   • Configura l'API Google Play Developer (se non l'hai già fatto), che utilizzerai per inviare le configurazioni di targeting a Google Play.
   • Segui i passaggi per creare la configurazione del targeting.
3. Carica il tuo AAB su Play ed esegui il test per assicurarti che tutto sia configurato correttamente

Gradle è il sistema di build consigliato per i giochi Java e nativi. Per i giochi creati utilizzando Gradle, segui questi passaggi per configurare il sistema di compilazione per creare l'AAB con il supporto del targeting per paese.

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

Configurare il targeting degli asset per paese 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 paese, Google Play pubblica i contenuti dei pacchetti di asset in base alle configurazioni dei set di paesi prescritte per le diverse località degli utenti. 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 di modificare il codice del progetto per attivare il targeting per paese.

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

Creazione di directory specifiche per i paesi impostati

Se utilizzi Gradle

Ora suddividerai gli asset tra i set di paesi (massimo 20) che definirai in un secondo momento. Crea le directory di destinazione prendendo le directory dei pacchetti di asset esistenti create nell'ultimo passaggio e correggendo la cartella appropriata (come descritto di seguito) con #countries_latam, #countries_na e così via. Quando utilizzi i pacchetti di asset nel tuo gioco, non dovrai indirizzare le cartelle tramite il suffisso (in altre parole, il suffisso viene rimosso automaticamente durante il processo di compilazione).

Dopo il passaggio precedente, il codice potrebbe avere il seguente aspetto:

...
.../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 all'interno della cartella, puoi semplicemente utilizzare lo stesso percorso senza correzioni di post. In questo esempio, mi riferisco come level1/assets/character-textures/ senza correzioni di errori.

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:8.1.0-alpha01'
    classpath "com.android.tools.build:bundletool:1.14.0"
    ...
  }
  ...
}

Dovrai anche aggiornare la versione di Gradle alla 8.0 o successiva. Puoi aggiornare questa opzione 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 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, abilita 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, mentre sei nel passaggio per personalizzare il tuo AAB, aggiungi quanto segue al file BundleConfig.pb.

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

Test locale

Prima di procedere, ti consigliamo di testare l'app bundle a livello locale per assicurarti che sia tutto configurato correttamente. Utilizzando bundletool (1.14.0 o versioni successive), puoi compilare e testare localmente la tua app, specificando esplicitamente il paese corretto. Innanzitutto, utilizzerai build-apks per generare un insieme di file .apks, quindi eseguirai il deployment dell'app su un dispositivo connesso utilizzando install-apks. Puoi anche specificare l'insieme di paesi da installare tramite il flag country-set. Puoi trovare ulteriori informazioni su questo metodo di test locale qui (tieni presente che questa pagina non è ancora stata aggiornata per il targeting per paese e quindi manca 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 utilizzare extract-apks per estrarre un insieme di APK per un dispositivo specifico. Tuttavia, l'utilizzo di get-device-spec insieme alla specifica del paese per questo dispositivo non funzionerà in combinazione con il flag --local-testing, il che significa che non potrai effettuare test sui pacchetti di asset on demand o di aggiornamento rapido.

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 di targeting per 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 paese (ovvero definire i set di paesi), 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:

1. Crea (se necessario) e collega il progetto API a Google Play Console.
2. Configura un client di accesso all'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 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 del percorso	N/D
Corpo della richiesta	Configurazione del targeting per dispositivo
Corpo della risposta	Configurazione del targeting per dispositivo

Oggetto di configurazione del targeting per dispositivo

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

Campi:

• device_confid_id (intero): ID corrispondente a questa configurazione di targeting per il dispositivo.
• user_country_sets (oggetto): definizioni degli insiemi di paesi
  • name (stringa): il nome dell'insieme di paesi (un ID stringa definito da te).
  • country_codes (stringa): i 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 la configurazione del targeting per dispositivo tramite ID

Puoi recuperare una configurazione di targeting per 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 del targeting per dispositivo

Recupera l'elenco delle configurazioni di targeting per dispositivo

Puoi ottenere le ultime 10 configurazioni di targeting per dispositivo utilizzando la 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 di configurazioni di targeting per dispositivo token_pagina

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.

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

Con bundletool evaluate-device-targeting-config, puoi valutare quale paese impostato corrisponderebbe a un dispositivo specifico. Puoi fornire il paese dell'utente tramite il flag --country-code.

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

Caricamento dell'app bundle Android su Google Play

Via API

Puoi utilizzare l'API Google Play per sviluppatori per caricare il tuo app bundle Android su Google Play e collegare una configurazione di targeting per dispositivo specifica alla tua build.

Qui puoi trovare una panoramica generale dei metodi di modifica, nonché esempi più approfonditi sulla pubblicazione nei diversi canali di Google Play Console (per l'ultimo link, ti consigliamo di utilizzare le API compatibili con AAB anziché l'API compatibile con APK, elencate nella pagina). Per specificare la configurazione del targeting per dispositivo per la tua compilazione, dovrai aggiungere l'ID configurazione al parametro di query deviceTierConfigId durante la chiamata al 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 l'app bundle per Android. La configurazione DTC più recente verrà applicata al tuo app bundle.

Verifica che vengano pubblicati gli asset corretti

Utilizza il seguente metodo per assicurarti che solo gli asset corretti vengano inviati al dispositivo

adb shell pm path {packageName}

Dovresti vedere qualcosa di simile a quanto segue:

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) di creazione di una nuova configurazione di targeting per i dispositivi e dell'utilizzo dell'API di modifica per creare una nuova modifica, caricare un nuovo AAB (associandolo con una configurazione di targeting per i dispositivi specifica), impostare la configurazione della traccia/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 di targeting per dispositivo e prendi nota dei deviceTierConfigId che riceverai se la chiamata va a buon fine.

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 la data di scadenza della 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 è 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="{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). 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