Google Play Asset Delivery 레퍼런스

Google Play Asset Delivery(Google PAD) 는 에셋 팩을 디바이스에 설치한 후 전송하는 Google Play Store의 솔루션입니다. 본 솔루션은 Android App Bundle 배포 형식과 함께 사용해야 합니다. App Bundle에서 최초 설치에 필요한 코드 및 바이너리를 처리하며 최종 사용자에게 커스터마이징된 .apk를 배포하고, Play Asset Delivery 시스템은 .apk와 별개로 모델, 텍스처, 사운드, 셰이더, 기타 대용량 에셋 파일을 제공합니다. 덕분에 Google Play를 통해 앱을 배포할 때, 필요에 따라 콘텐츠를 전송함으로써 콘텐츠가 차지하는 공간을 관리할 수 있습니다.

Google Play Asset Delivery와 관련된 일반 정보는 공식 Android 문서(https://android-developers.googleblog.com/2020/06/introducing-google-play-asset-delivery.html)를 참조하세요.

언리얼 엔진 4.25 부터는 플러그인을 통한 Google PAD 통합 기능을 이용하여 진행 중인 프로젝트에서 이 시스템을 간단히 구현할 수 있습니다. 이 플러그인이 제공하는 함수 라이브러리는 다운로드를 관리하고 Play Asset Delivery 시스템의 정보를 요청하는 호출이 있습니다. UGooglePADFunctionLibrary는 C++와 블루프린트에서 이용할 수 있습니다.

Android App Bundle로 배포하는 방법에 대해 자세히 알아보려면 Android 프로젝트 패키징을 참조하세요.

Google PAD 플러그인 활성화하기

Google PAD 플러그인은 언리얼 에디터 플러그인(Plugins) 창의 Android 섹션에 있으며, 언리얼 엔진 4.25.0 이상 버전에서 기본으로 활성화되어 있습니다. Google PAD를 사용하려면 반드시 Android App Bundle을 패키징 형식으로 사용해야 합니다.

플러그인을 완전히 활성화하려면 프로젝트 세팅(Project Settings) 을 열고, 플러그인(Plugins) > GooglePAD > 패키징(Packaging) 으로 이동합니다. 플러그인 활성화(Enable Plugin) 체크박스를 클릭하면, Android 프로젝트에서 처음부터 모듈을 사용할 수 있습니다.

Google PAD를 install-time 에셋에 사용하려면 플랫폼(Platforms) > Android > APK 패키징(APK Packaging) 으로 이동해 .apk 안에 게임 데이터 패키징?(Package Data inside APK) 을 비활성화합니다. 그러면 주요 .obb 파일이 자동으로 install-time 에셋 팩 형태로 전송됩니다.

클릭하여 이미지 확대

에셋 팩 생성하기

Google PAD용 에셋 팩(Asset packs) 은 Android App Bundle 빌드 내부에서 패키징되며, 업로드되면 Google Play Store에서 관리합니다. 이 섹션에서는 App Bundle에 포함할 에셋 팩을 패키징하고 정리하는 방법을 설명합니다.

에셋 팩 전송 모드

청크(Chunk) 는 외부 에셋 정리를 위한 언리얼 엔진의 형식입니다. 청크 0은 게임의 기본 설치 파일, 나머지 청크는 게임의 주요 설치 외에 쓰이는 에셋을 포함하는 .pak 파일입니다.

Google PAD를 활용하려면 게임의 에셋을 청크로 그룹화한 뒤, 이 청크를 사용할 전송 모드에 기반해서 에셋 팩으로 그룹화해야 합니다. Google Play Asset Delivery는 다음과 같은 에셋 팩 전송 모드를 지원합니다.

애플리케이션마다 총 50 개의 에셋 팩을 생성할 수 있습니다. Install-Time 및 Fast-Follow 에셋 팩은 프로젝트마다 하나만 보유할 수 있지만, On-Demand 에셋 팩은 50개를 넘지만 않으면 얼마든지 사용할 수 있습니다.

청크 생성하기

프로젝트 세팅(Project Settings) 을 열고 프로젝트(Project) > 패키징(Packaging)으로 이동하여 청크 생성(Generate Chunks)을 활성화합니다.

이제 에셋 매니저(asset manager) 혹은 프라이머리 에셋 라벨(primary asset labels) 로 에셋을 청크로 정리할 수 있습니다.

프라이머리 에셋 라벨은 콘텐츠 브라우저(Content Browser)에서 우클릭한 뒤 기타(Miscellaneous) > 데이터 에셋(Data Asset) 을 클릭하여 생성할 수 있습니다.

클릭하여 이미지 확대

그러면 데이터 에셋 클래스(Data Asset Class) 선택 창이 표시됩니다. PrimaryAssetLabel 을 선택하고 선택(Select) 을 클릭합니다.

클릭하여 이미지 확대

새 프라이머리 에셋 라벨의 이름을 지정한 뒤, 더블 클릭하여 정보를 편집합니다.

클릭하여 이미지 확대

내 디렉터리의 에셋에 라벨(Label Assets in my Directory) 을 활성화하여 동일한 폴더의 모든 에셋이 이 에셋 라벨에 속하도록 지정합니다. 청크 ID(Chunk ID) 를 0보다 큰 값으로 설정하여 이 라벨에 속한 에셋이 포함될 청크를 지정하세요. 명시적 에셋(Explicit Assets) 목록을 사용하는 에셋 라벨에도 에셋을 직접 추가할 수 있습니다.

에셋 매니저는 프로젝트 세팅(Project Settings) 의 게임(Game) > 에셋 매니저(Asset Manager) 에 있습니다.

클릭하여 이미지 확대

여기에서는 프로젝트에서 에셋을 청크에 절차적 으로 그룹화할 때 사용할 규칙을 지정할 수 있습니다. 자세한 정보는 쿠킹 및 청킹(Cooking and Chunking) 페이지를 참조하세요.

특정 청크에 포함시킬 에셋을 지정한 뒤 프로젝트를 패키징 하면 청크가 .pak 파일로 출력됩니다. 출력된 파일은 Saved\StagedBuilds[PlatformName][ProjectName]\Content\Paks의 프로젝트 폴더에 있습니다.

클릭하여 이미지 확대

App Bundle 빌드에 청크 포함하기

Play Asset Delivery의 전송 모드마다 청크를 App Bundle에 통합할 때 필요한 내용이 다릅니다.

Install-Time 에셋은 따로 변경할 필요가 없습니다.

Fast-Follow 및 On-Demand 에셋은 포함할 .pak 파일을 선택한 뒤 프로젝트의 Build/Android/gradle/assetpacks 디렉터리로 옮겨야 합니다. 전송 모드마다 다음과 같이 하위 폴더가 다릅니다.

• Fast-Follow 에셋 팩은 반드시 Build/Android/gradle/assetpacks/fast-follow/[assetpackname]/src/main/assets에 있어야 합니다.

• On-Demand 에셋 팩은 반드시 Build/Android/gradle/assetpacks/on-demand/[assetpackname]/src/main/assets에 있어야 합니다.

[assetpackname]을 청크를 포함할 에셋 팩 이름으로 변경합니다. .pak 파일의 구성마다 다양한 이름의 에셋 팩을 생성할 수 있지만, 에셋 팩 이름은 중복될 수 없고 Fast-Follow와 On-Demand 간에 재사용할 수 없습니다. 이 이름은 API를 사용해 에셋 팩을 쿼리할 때 사용합니다.

마지막으로는 다음 코드가 포함된 에셋 팩 폴더에 build.gradle 파일을 추가해야 합니다.

	apply plugin: 'com.android.asset-pack'

	def fileparts = projectDir.absolutePath.replaceAll('\\\\', '/').tokenize('/')
	def assetPackName = fileparts[fileparts.size()-1]
	def assetPackType = fileparts[fileparts.size()-2]

	assetPack {
		packName = assetPackName
		dynamicDelivery {
			deliveryType = assetPackType
			instantDeliveryType = assetPackType
		}
	}
Copy full snippet

apply plugin: 'com.android.asset-pack' def fileparts = projectDir.absolutePath.replaceAll('\\\\', '/').tokenize('/') def assetPackName = fileparts[fileparts.size()-1] def assetPackType = fileparts[fileparts.size()-2] assetPack { packName = assetPackName dynamicDelivery { deliveryType = assetPackType instantDeliveryType = assetPackType } }

조건을 충족한 뒤 프로젝트를 다시 App Bundle 형태로 패키징하면, 빌드에 각 에셋 팩이 포함됩니다. App Bundle을 Google Play Store에 업로드하면, Google PAD API 통해 다운로드할 수 있습니다.

이 워크플로는 언리얼 엔진 4.26에서 더 간소화될 예정입니다.

API 레퍼런스

이번에는 Google PAD 함수 라이브러리에서 사용할 수 있는 함수와 그 활용법을 자세히 다룹니다.

요청 및 오류 처리

Google PAD 함수 라이브러리의 모든 요청은 EGooglePADErrorCode를 반환합니다. 이 코드는 작업의 성공 여부를 나타내는데 실패 시 요청을 완료하지 못하게 하는 오류를 나타냅니다. 발생 가능한 오류 코드는 다음과 같습니다.

요청 함수는 이 반환 값 외에도 요청된 정보를 제공하는 출력 변수를 가집니다. 결과가 AssetPack_NO_ERROR면 제공된 정보를 가지고 정상적으로 진행할 수 있습니다. 오류가 발생했다면 흐름 제어를 통해 해당 오류 코드에 적절히 대응해야 합니다.

다운로드한 파일 위치 얻기

GetAssetPackLocation 함수는 다운로드한 에셋 팩의 위치를 가져오고 관련 정보를 로컬 캐싱합니다. 에셋을 사용할 수 있다면, 필요에 따라 캐싱된 정보를 이용할 때 사용할 정수 핸들을 출력합니다.

GetAssetsPath를 호출하여 위치 핸들을 제공하면 원하는 에셋 팩의 에셋 경로가 포함된 스트링을 출력합니다. GetStorageMethod는 사용자의 디바이스에 에셋 팩이 저장된 방법을 알려주는EGooglePADStorageMethod를 출력합니다. 에셋 경로 및 저장 방법을 알고 있다면 적절한 호출을 통해 에셋을 이용할 수 있습니다.

가능한 저장 방법은 다음과 같습니다.

위의 정보를 이용한 작업이 끝났다면, 반드시 위치 핸들을 ReleaseAssetPackLocation에 전달해 캐싱된 위치 정보를 해제해야 합니다.

GetAssetPackLocation이 AsetPack_UNAVAILABLE 혹은 AssetPack_DOWNLOAD_NOT_FOUND 오류 코드를 반환할 경우, 원하는 에셋 팩을 사용할 수 없다는 뜻이므로 다운로드해야 합니다.

에셋 팩과 관련된 정보 요청하기

RequestInfo 함수는 에셋 팩 이름의 Tarray를 받아 현재 상태를 알려주는 EGooglePADErrorCode를 반환합니다. RequestInfo는 다운로드에 꼭 필요한 함수는 아니지만, 원격 에셋 팩이 유효한지 여부를 결정할 때 사용할 수 있습니다.

다운로드 요청 또는 취소하기

RequestDownload 함수는 다운로드하려는 에셋 팩의 이름을 나타내는 스트링의 ‘Tarray’를 선택한 뒤, 원격 서비스에 요청을 보내 해당 에셋 팩의 다운로드를 시작합니다. RequestDownload에 오류가 없으면, 에셋 팩을 다운로드한 뒤 백그라운드에서 앱에 비동기적으로 전송합니다.

이 함수는 비동기적이므로 RequestDownload 함수는 다운로드한 에셋 팩에 대한 정보를 반환하지 않고, 요청의 성공 여부를 나타내는 오류 코드만 반환합니다. 현재 다운로드 상태를 점검하려면 아래 다운로드 상태 모니터링(Monitoring Download Status)에서 자세히 다룬 함수를 사용하고, 에셋 팩 자체를 활용하려면 다운로드가 끝난 뒤 GetAssetPackLocation을 사용해야 합니다.

CancelDownload 함수도 에셋 팩 이름 목록을 사용하고, 지정된 에셋 팩의 다운로드를 취소합니다.

무선 데이터 상태 얻기

ShowCellularDataConfirmation 함수를 사용하면 사용자가 자신의 무선 네트워크를 이용해 데이터를 다운로드할지 묻는 메시지가 나타납니다. 메시지가 이미 표시되었다면, ‘GetShowCellularDataConfirmationStatus’를 이용해 사용자의 다운로드 승인 여부를 나타내는 EGooglePADCellularDataConfirmStatus를 반환할 수 있습니다.

결과가 AssetPack_CONFIRM_UNKNOWN 및 AssetPack_CONFIRM_PENDING이라면 사용자가 아직 승인하지 않았다는 뜻이며, 애플리케이션은 사용자가 승인할 때까지 대기 상태를 유지합니다.

결과가 AssetPack_CONFIRM_USER_CANCELLED이면 사용자가 무선 데이터 사용을 허용하지 않기로 했다는 뜻이며, 다운로드가 허가되지 않습니다.

결과가 AssetPack_CONFIRM_USER_APPROVED이면 사용자가 무선 데이터의 사용을 허가했다는 뜻이며, 다운로드를 진행할 수 있습니다. 이 함수가 AssetPack_NETWORK_UNRESTRICTED 결과를 포함한 EGooglePADErrorCode를 반환하는 경우도 있습니다. 사용자가 와이파이를 사용 중이며 무선 데이터를 사용할 필요가 없다는 뜻이므로, 이 함수를 계속 점검하지 않고 다운로드를 진행할 수 있습니다.

다운로드 상태 모니터링

GetDownloadState를 사용하면 에셋 팩의 다운로드 상태를 로컬 캐싱하고 캐싱된 정보에 액세스를 제공하는 다운로드 핸들을 반환합니다. 이 함수는 다운로드하려는 에셋 팩의 이름을 받아 핸들을 정수 형태로 반환합니다. 다운로드 핸들을 계속 캐싱해서 다운로드 상태를 모니터링해야 합니다. 아니면 다운로드 핸들을 나중에 다시 얻어야 합니다.

유효한 다운로드 핸들이 있으면 GetDownloadStatus를 호출해 원하는 에셋 팩의 상태를 EGooglePADDownloadStatus로 반환할 수 있습니다. 이 열거형은 아래에서 보이는 여러 다운로드 상태 중 하나를 나타냅니다.

다운로드 상태 핸들을 사용하여 사용자의 디바이스에 현재 다운로드한 바이트 수를 반환하는 GetBytesDownloaded와 다운로드한 총 타깃 크기를 반환하는 GetTotalBytesToDownload를 호출할 수도 있습니다.

다운로드 상태 정보 사용이 끝났으면 ReleaseDownloadState를 호출해 캐싱된 다운로드 정보를 메모리에서 해제할 핸들을 준비해야 합니다.

에셋 팩 제거하기

RequestRemoval 함수를 사용하면 특정 에셋 팩의 이름을 받은 뒤, 사용자의 디바이스에서 지정한 에셋 팩을 비동기적으로 제거합니다. 에셋 팩의 제거 상태는 위에서 다룬 GetDownloadStatus로 모니터링할 수 있습니다.

추천하는 구현 방법

Google PAD API를 구현할 때 각 다운로드별로 다른 상태의 사이클로 모델링할 수 있습니다.

커스텀 GameState 클래스에서 솔루션을 구현하면 씬과 게임 모드를 바꾸는 도중에도 다운로드를 계속 추적할 수 있습니다. 또는, 시작 시 로드되는 프론트엔드 게임 모드에서 솔루션을 구현하여 게임을 시작하기 전 필요한 패치 및 업데이트를 수행할 수도 있습니다. 솔루션에 들어갈 정확한 세부 정보는 프로젝트에서 에셋을 업데이트할 때 필요한 내용에 따라 달라집니다.