이 페이지는 Cloud Translation API를 통해 번역되었습니다.

국가별 애셋 타겟팅

국가별 애셋 타겟팅이란 무엇인가요?

국가별 애셋 타겟팅을 사용하면 사용자가 위치한 국가를 기반으로 기기에 동일한 애셋의 여러 버전(예: 해상도)을 제공할 수 있습니다. 예를 들어 사용자 기기에 필요한 애셋만 전송함으로써 전반적인 게임 크기를 늘리지 않고도 앱이 제공되는 여러 국가에 맞춤 애셋을 제공할 수 있습니다. 기기 등급 타겟팅은 Play Asset Delivery의 애셋 팩 개념을 기반으로 합니다. 아래에서 볼 수 있듯이 최대 20개의 국가 세트로 타겟팅 기준을 정의할 수 있습니다. 이 컨텍스트에서 기기 국가는 일반적으로 Google Play 계정에 등록된 사용자의 청구서 수신 주소에 따라 결정됩니다.

국가별 타겟팅은 Play Asset Delivery와 마찬가지로 Android 4.1(API 수준 16) 및 이후 버전을 지원합니다. 단, Android 4.4(API 수준 19) 및 이후 버전을 실행하는 기기에서는 사용자 위치에 관계없이 기본 국가 세트가 제공됩니다.

개발자의 여정

기존 게임에 국가별 타겟팅을 통합하려면 개략적으로 다음 단계를 따르세요.

국가별 타겟팅(그리고 더 나아가 Play Asset Delivery)을 게임 내에 통합합니다.
- Play Asset Delivery를 게임에 통합합니다(아직 하지 않은 경우).
- 애셋을 애셋 팩으로 나눕니다.
- 코드와 애셋을 패키지로 묶어 Play에 업로드할 최종 Android App Bundle 아티팩트를 만듭니다.
Play가 사용자 기기에 애셋이 전송되는 방식을 알 수 있도록 기기 타겟팅 구성을 만듭니다.
- 타겟팅 구성을 Play에 전송하는 데 사용할 Google Play Developer API를 설정합니다(아직 완료하지 않은 경우).
- 단계에 따라 타겟팅 구성을 만듭니다.
AAB를 Play에 업로드하고 모든 것이 올바르게 구성되었는지 테스트합니다.

Gradle은 자바 및 네이티브 게임에 권장되는 빌드 시스템입니다. Gradle을 사용하여 빌드한 게임의 경우 다음 단계에 따라 국가별 타겟팅 지원으로 AAB를 빌드하도록 빌드 시스템을 구성합니다.

게임을 Gradle로 내보낸 다음 Gradle에서 빌드를 완료하는 경우에는 여기 나와 있는 안내를 따르세요(예: Gradle로 내보낸 Unity 게임).

앱 내에서 국가별 애셋 타겟팅 설정

게임에 Play Asset Delivery 통합(아직 완료하지 않은 경우)

PAD(Play Asset Delivery)를 사용하면 설치 시 또는 런타임 시에 게임의 애셋을 동적으로 전송할 수 있습니다. 여기에서 개요를 확인할 수 있습니다. 국가별 타겟팅을 사용하면 Play에서 개발자가 각 사용자 위치에 대해 지정한 국가 세트 구성을 기반으로 애셋 팩의 콘텐츠를 제공합니다. 아래 안내에 따라 PAD를 게임에 통합(예: 애셋 팩 만들기, 게임에서 검색 구현)한 다음 국가별 타겟팅을 사용하도록 프로젝트 코드를 수정하는 것이 좋습니다.

Gradle

Gradle을 사용하여 빌드한 게임의 경우 다음 안내에 따라 Gradle을 사용하여 애셋 팩을 빌드한 후에 안내에 따라 게임 내에서 애셋 팩 검색을 통합하세요.

자바
네이티브
Gradle로 내보낸 Unity 게임
- JNI를 통해 자바 라이브러리를 사용합니다(예: Unity에 내장된 라이브러리).

국가별 디렉터리 만들기

Gradle을 사용하는 경우

이제 나중에 정의할 국가 세트(최대 20개)로 애셋을 분할합니다. 마지막 단계에서 만든 기존 애셋 번들 디렉터리를 사용하고 적절한 폴더(아래 설명 참고)에 #countries_latam, #countries_na 등의 접미사를 붙여 타겟팅된 디렉터리를 만듭니다. 게임에 애셋 팩을 사용할 때는 접미사로 폴더를 처리할 필요가 없습니다(즉, 빌드 프로세스 중에 접미사가 자동으로 제거됨).

이전 단계를 완료하면 다음과 같을 수 있습니다.

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

폴더 아래의 파일에 액세스하면 동일한 경로를 접미사 처리 없이 사용할 수 있습니다(이 예에서는 접미사 없는 level1/assets/character-textures/로 함).

Android App Bundle 빌드

Gradle

프로젝트의 build.gradle 파일에서 Android Gradle 플러그인 및 bundletool에 아래 버전(이상)을 사용하도록 종속 항목을 구성합니다.

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

또한 Gradle 버전을 8.0 및 이후 버전으로 업데이트해야 합니다. 프로젝트 내의 gradle/wrapper/gradle-wrapper.properties에서 업데이트할 수 있습니다.

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

마지막으로, Play Asset Delivery 라이브러리를 사용해야 합니다. 아직 모놀리식 Play Core 라이브러리를 사용하고 있다면 1.8.3 및 이후 버전으로 업데이트하세요. 가능한 경우 Play Core 라이브러리를 Play Asset Delivery 라이브러리로 전환하고 최신 버전으로 업데이트할 것을 권장합니다.

dependencies {
  implementation 'com.google.android.play:asset-delivery:2.0.1'
  ...
}

기본 앱 모듈의 build.gradle 파일에서 국가별 타겟팅 분할을 사용 설정합니다.

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

마지막으로 AAB(Android App Bundle)를 빌드할 수 있습니다.

bundletool

bundletool을 사용하여 번들을 빌드하고 AAB를 맞춤설정하는 단계에서 BundleConfig.pb 파일에 다음을 추가합니다.

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

로컬 테스트

계속하기 전에 App Bundle을 로컬에서 테스트하여 모든 것이 올바르게 설정되었는지 확인하는 것이 좋습니다. bundletool(1.14.0 및 이전 버전)을 사용하여 로컬로 앱을 빌드하고 테스트하면서 올바른 국가를 명시적으로 지정합니다. 먼저 build-apks를 사용하여 .apks 파일 집합을 생성한 다음 install-apks를 사용하여 연결된 기기에 앱을 배포합니다. country-set 플래그를 통해 설치할 국가 세트를 지정할 수도 있습니다. 이 로컬 테스트 방법에 관한 자세한 내용은 여기에서 확인할 수 있습니다(이 페이지는 국가별 타겟팅용으로 아직 업데이트되지 않았으므로 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

다른 방법도 있습니다. 즉, extract-apks를 사용하여 특정 기기의 APK 세트를 추출할 수 있습니다. 하지만 이 기기의 국가를 지정하는 것과 함께 get-device-spec을 사용하면 --local-testing 플래그와 함께 작동하지 않습니다. 즉, 빠른 추적 또는 주문형 애셋 팩을 테스트할 수 없습니다.

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

Google Play Developer API를 통해 기기 타겟팅 구성 만들기

Google Play Developer API 시작하기(아직 완료하지 않은 경우)

국가별 타겟팅을 구성하려면 (즉, 국가 세트 정의) Android Publisher API를 사용하여 구성을 Google Play에 업로드해야 합니다. 위 링크에서 API에 관해 자세히 알아볼 수 있습니다. 몇 가지 단계에 따라 시작할 수 있도록 안내합니다.

API 프로젝트를 만들고(필요한 경우) Google Play Console에 연결합니다.
API 액세스 클라이언트를 설정합니다.

API 참조는 여기에서 확인할 수 있으며 나중에 API를 통해 빌드를 업로드하기로 하는 경우 Edits 메서드를 사용합니다. 또한 API를 사용하기 전에 이 페이지를 검토하는 것이 좋습니다.

Device Targeting Configuration API 사용

다음 API 호출을 사용하여 기기 타겟팅 구성을 만들 수 있습니다.

기기 타겟팅 구성 만들기

HTTP 요청	`POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs`
경로 매개변수	해당 사항 없음
요청 본문	기기 타겟팅 구성
응답 본문	기기 타겟팅 구성

기기 타겟팅 구성 객체

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

필드:

device_confid_id(정수): 이 기기 타겟팅 구성에 해당하는 ID
user_country_sets(객체): 국가 세트 정의
- name(문자열): 국가 세트의 이름(정의한 문자열 ID)
- country_codes(문자열): 이 국가 세트에 속하는 국가(형식: ISO 3166-1 alpha-2)

Google Play에 업로드하기 전에 기기 타겟팅 구성 확인에 관한 아래의 안내를 따르세요.

ID별로 기기 타겟팅 구성 가져오기

다음 호출을 사용하여 ID별로 특정 기기 타겟팅 구성을 가져올 수 있습니다.

HTTP 요청	`GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}`
경로 매개변수	해당 사항 없음
요청 본문	해당 사항 없음
응답 본문	기기 타겟팅 구성

기기 타겟팅 구성 목록 가져오기

다음 호출이 제공되는 경우 최근 10개의 기기 타겟팅 구성을 가져올 수 있습니다(또는 최적으로 page_token 쿼리 매개변수를 사용하여 10개로 이루어진 세트를 지정함).

HTTP 요청	`GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs`
경로 매개변수	해당 사항 없음
쿼리 매개변수	page_token(선택사항) - DTC 10개로 이루어진 특정 그룹을 지정하는 데 사용됩니다. DTC를 10개 넘게 만들었으며 최신 10개 이전에 생성된 DTC를 확인하려는 경우 유용합니다.
요청 본문	해당 사항 없음
응답 본문	기기 타겟팅 구성 목록 page_token

기기 타겟팅 구성 확인

bundletool에는 Play에 업로드하기 전에 기기 타겟팅 구성이 의도한 대로 작동하는지 확인할 수 있는 두 가지 명령어가 포함되어 있습니다.

bundletool print-device-targeting-config를 사용하면 JSON 파일이 문법적으로 올바른지 확인할 수 있습니다.

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

bundletool evaluate-device-targeting-config를 사용하면 특정 기기와 일치하는 국가 세트를 평가할 수 있습니다. --country-code 플래그를 통해 사용자 국가를 제공할 수 있습니다.

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

Google Play에 Android App Bundle 업로드

API 사용

Google Play Developer API를 사용하여 Android App Bundle을 Google Play에 업로드하고 특정 기기 타겟팅 구성을 빌드에 연결할 수 있습니다.

여기에서 Edits 메서드의 일반 개요를 확인할 수 있습니다. 또한 Google Play Console에서 다른 트랙에 출시하는 방법을 보여주는 심도 있는 예시도 참고할 수 있습니다(최신 링크를 보려면 페이지의 목록이 나온 APK 친화적인 API 대신 AAB 친화적인 API 사용). 빌드의 기기 타겟팅 구성을 지정하려면 edits.bundle.upload 메서드를 호출하는 동안 deviceTierConfigId 쿼리 매개변수에 구성 ID를 추가합니다. 다음과 같습니다.

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

Google Play Console 사용

여기에 나온 안내에 따라 Android App Bundle을 업로드할 수 있습니다. 최신 DTC 구성이 App Bundle에 적용됩니다.

올바른 애셋이 제공되고 있는지 확인

다음 메서드를 사용하여 올바른 애셋만 기기로 전송되도록 합니다.

adb shell pm path {packageName}

다음과 같이 표시됩니다.

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

추가사항

빠른 시작: curl 사용

다음은 새 기기 타겟팅 구성 만들기(명령줄 도구 curl 사용)의 예와 Edits API를 사용하여 새 수정사항을 만들고, 새 AAB를 업로드하고(특정 기기 타겟팅 구성과 연결), 트랙/출시 구성을 설정하고, 수정사항을 커밋하는(이에 따라 변경사항을 공개로 설정) 예입니다. 다음의 위치가 있어야 합니다.

API 클라이언트에 상응하는 키
앱의 패키지 이름

먼저 기기 타겟팅 구성을 만들고 호출 성공 시 수신되는 deviceTierConfigId를 기록해 둡니다.

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

수정 시작 - 수정의 ID와 만료 시간이 표시됩니다. 다음 호출의 ID를 저장합니다.

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

AAB를 업로드하고 기기 타겟팅 구성을 쿼리 매개변수로 지정합니다. 호출이 성공하면 빌드의 버전 코드 sha1과 sha256이 표시됩니다. 다음 호출을 위해 버전 코드를 저장합니다.

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

원하는 트랙에 AAB를 할당(테스트의 경우 내부 테스트 트랙을 사용하는 것이 좋지만 다양한 트랙에 관해 여기에서 자세히 알아보기), 이 과정에서는 출시 노트 없이 단순한 출시를 진행합니다. 하지만 단계적 출시, 임시 버전, 출시 노트 관련 방법을 자세히 알아보려면 이 페이지를 확인해 보세요. 게시자 API를 처음 사용하는 경우 임시 버전으로 만들어 Google Play Console에서 버전을 완료하여 모든 것이 올바르게 구성되었는지 확인하는 것이 좋습니다.

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}

변경사항을 커밋합니다. Play에서 원하는 트랙에 모든 변경사항이 게시되므로 신중하게 진행하세요.

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