조건부 모듈을 위한 기기 타겟팅

조건부 모듈을 위한 기기 타겟팅이란

기기 타겟팅을 사용하면 하드웨어에 따라 조건부 기능 모듈을 기기에 전송할 수 있습니다. 예를 들어 일부 기능을 고급형 기기에만 전송하고 이 기능을 사용할 수 없는 기기에는 전송하지 않도록(즉, 기기의 공간 절약) 선택할 수 있습니다. 기기 타겟팅은 Play Feature Delivery의 기능 모듈 개념을 기반으로 합니다. 아래에서 볼 수 있듯이 타겟팅 기준(현재는 RAM, 특정 기기 모델, 사용 가능한 시스템 기능을 기반으로 함)을 정의하고 모듈을 특정 기기 그룹에 타겟팅할 수 있습니다.

개발자의 여정

기존 애플리케이션에 기기 타겟팅을 통합하려면 개략적으로 다음 단계를 따라야 합니다.

  1. 하드웨어에 따라 일련의 기기에만 전송하려는 기능을 개발합니다.
    • 이 기능을 기능 모듈로 구현합니다.
    • AndroidManifest.xml의 모듈 조건 섹션에서 어느 기기 그룹에 전송해야 할지 지정합니다.
  2. Play가 사용자 기기에 기능 모듈이 전송되는 방식을 알 수 있도록 기기 타겟팅 구성을 만듭니다.
    • DT 구성을 Play에 전송하는 데 사용할 Google Play Developer API를 설정합니다(아직 완료하지 않은 경우).
    • 단계에 따라 DT 구성을 만듭니다.
  3. AAB를 Play에 업로드하고 모든 것이 올바르게 구성되었는지 테스트합니다.

이 문서에서는 Android Gradle 플러그인을 사용하여 조건부 전송을 위한 기기 타겟팅을 추가하는 방법을 설명합니다.

기기 타겟팅을 사용한 조건부 기능 모듈 만들기

앱에 기능 모듈 추가

Play Feature Delivery를 사용하면 앱의 특정 기능을 조건부로 전송하거나 주문형으로 다운로드할 수 있습니다. 여기에서 개요를 읽어보세요. 기기 타겟팅을 사용하면 제공된 그룹에 할당된 기기에 조건부로 기능을 전송할 수 있습니다.

조건부 전송에 DT를 사용하려면 bundletool 버전 1.7.0 이상을 사용해야 합니다. 그러려면 Android Gradle 플러그인용 bundletool 버전을 명시적으로 지정해야 합니다. 루트 build.gradle 파일의 buildscript 섹션을 사용하면 됩니다.

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

기능 모듈을 만들려면 Android 애플리케이션 모듈화의 안내를 따르세요.

기능 개발이 완료되면 기능의 AndroidManifest.xml에서 기기 타겟팅을 기반으로 전송 조건을 지정할 수 있습니다. dist:module 요소의 dist:conditions 내에 기기 그룹 조건을 제공해야 합니다. 조건에 관한 일반적인 정보는 여기를 참고하세요. 기기 그룹의 경우 이 기능을 전송받아야 하는 모든 그룹을 지정할 수 있는 새 조건을 사용할 수 있습니다.

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

예를 들어 _my_group1이라는 기기 그룹을 정의했다고 가정하겠습니다(정의하는 방법은 아래의 기기 타겟팅 구성 만들기 섹션 참고). 기능 모듈을 _my_group1 그룹에 속한 기기에만 전송해야 하는 경우 AndroidManifest.xml은 다음과 같습니다.

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

_my_group1과 _my_group2를 모두 타겟팅하는 기능의 경우 AndroidManifest.xml은 다음과 같습니다.

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

완료되면 AAB(Android App Bundle)를 빌드할 수 있습니다.

로컬 테스트

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

다른 방법도 있습니다. 즉, extract-apks를 사용하여 특정 기기의 APK 세트를 추출할 수 있습니다(이 기기의 기기 그룹을 지정하는 것과 함께 get-device-spec 사용).

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

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

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

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

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

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

Device Targeting Configuration API 사용

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

기기 타겟팅 구성 만들기

HTTP 요청 POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
경로 매개변수 N/A
요청 본문 기기 타겟팅 구성
응답 본문 기기 타겟팅 구성
기기 타겟팅 구성 객체
{
  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_config_id(정수): 이 기기 타겟팅 구성에 해당하는 ID

  • device_groups(객체): 그룹 정의

    • name(문자열): 기기 그룹의 이름(정의한 문자열 ID)
    • device_selectors(객체): 기기가 이 그룹에 속하기 위해 필요한 기기 요구사항
    • device_ram(객체): 기기 RAM 요구사항
      • min_bytes(정수): 필요한 최소 RAM(바이트)
      • max_bytes(정수): 필요한 최대 RAM(바이트)
    • included_device_ids(객체): 이 선택기에 포함할 기기 모델(그룹당 최대 1만 개 device_ids). 이 목록에 선택기와 일치하는 기기가 있어야 합니다. 전체 선택기와 일치하기 위한 필요조건이지만 충분조건은 아닙니다(선택기의 요구사항 결합에 관한 아래의 참고 사항 확인).
      • build_brand(문자열): 기기 제조업체
      • build_device(문자열): 기기 모델 코드
    • excluded_device_ids(객체): 이 선택기에서 제외할 기기 모델(그룹당 최대 1만 개 device_ids). 이 목록의 기기는 선택기의 다른 모든 요구사항과 일치하더라도 선택기와 일치하지 않습니다.
      • build_brand(문자열): 기기 제조업체
      • build_device(문자열): 기기 모델 코드

    • required_system_features(객체): 이 선택기에 포함되기 위해 기기에 필요한 기능(그룹당 최대 100개 기능). 기기가 선택기와 일치하려면 이 목록의 모든 시스템 기능이 기기에 있어야 합니다. 전체 선택기와 일치하기 위한 필요조건이지만 충분조건은 아닙니다(선택기의 요구사항 결합에 관한 아래의 참고 사항 확인).

      시스템 기능 참조

      • name(문자열): 시스템 기능

    • forbidden_system_features(객체): 이 선택기에 포함되기 위해 기기에 있어서는 안 되는 기능(그룹당 최대 100개 기능). 이 목록에 있는 시스템 기능 중 하나라도 기기에 있는 경우 기기는 선택기의 다른 모든 요구사항과 일치하더라도 선택기와 일치하지 않습니다.

      시스템 기능 참조

      • name(문자열): 시스템 기능

Google Play Console에서 기기 카탈로그를 사용하여 다음 중 한 가지 방법으로 기기 제조업체 및 모델 코드의 올바른 형식을 찾을 수 있습니다.

  • 기기 카탈로그를 사용하여 개별 기기를 검사하고 아래 예와 같은 위치에서 제조업체 및 모델 코드를 찾습니다(Google Pixel 4a의 경우 제조업체는 'Google'이고 모델 코드는 'sunfish').

    기기 카탈로그의 Pixel 4a 페이지

    기기 카탈로그의 Pixel 4a 페이지

  • 지원되는 기기의 CSV를 다운로드하고 build_brand 필드와 build_device 필드에 각각 제조업체와 모델 코드를 사용합니다.

예를 들어 다음 그룹은 RAM이 4GB를 초과하는 모든 기기와 일치합니다. 단, Pixel 5(google redfin)는 제외되고 Pixel 3(Google Blueline, RAM 4GB 미만)는 포함됩니다.

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

다음과 같이 읽을 수 있습니다.

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

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

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

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

HTTP 요청 GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}
경로 매개변수 N/A
요청 본문 N/A
응답 본문 기기 타겟팅 구성

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

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

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

page_token

기기 타겟팅 구성 확인

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

bundletool print-device-targeting-config를 사용하면 JSON 파일이 문법적으로 올바른지 확인하고 기기 그룹을 보다 읽기 쉬운 형식으로 시각화할 수 있습니다.

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

bundletool evaluate-device-targeting-config를 사용하면 특정 기기와 일치하는 그룹을 평가할 수 있습니다. 대상 기기를 워크스테이션에 연결하고 --connected-device 플래그를 사용하거나 기기 속성으로 JSON 파일을 직접 컴파일하고 --device-properties 플래그를 통해 제공합니다.

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

기기 속성 파일은 DeviceProperties protobuf 구조를 따르는 JSON 파일이어야 합니다. 예:

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

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에 적용됩니다.

추가사항

빠른 시작: curl 사용

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

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

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

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

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

AAB를 업로드하고 기기 타겟팅 구성(deviceTierConfigId)을 쿼리 매개변수로 지정합니다. 호출이 성공하면 빌드의 버전 코드 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="{deviceTierConfigId}

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

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}

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

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