APK 확장 파일

Google Play에서 사용자가 다운로드하는 압축된 APK는 100MB 이하여야 합니다. 대부분 앱에서 이 공간은 앱의 모든 코드와 저작물을 저장하기에 충분합니다. 그러나 일부 앱에는 고화질 그래픽, 미디어 파일 또는 다른 대용량 저작물을 저장할 공간이 더 많이 필요합니다. 이전에는 앱의 압축된 다운로드 크기가 100MB를 초과하는 경우 사용자가 앱을 열 때 개발자가 직접 추가 리소스를 호스팅하고 다운로드해야 했습니다. 추가 파일을 호스팅하고 제공하는 데는 많은 비용이 들 수 있고 일반적으로 사용자 환경이 이상적이지 않습니다. 개발자에게는 더 수월하고 사용자에게는 편리한 프로세스를 만들기 위해 Google Play에서는 개발자가 APK를 보완하는 대용량 확장 파일 2개를 첨부할 수 있게 합니다.

Google Play는 앱을 위해 확장 파일을 호스팅하고 기기에 무료로 제공합니다. 확장 파일은 앱에서 액세스할 수 있는 기기의 공유 저장공간 위치(SD 카드 또는 USB 마운트 가능 파티션. '외부' 저장소라고도 함)에 저장됩니다. 대부분의 기기에서 Google Play는 APK를 다운로드하는 동시에 확장 파일을 다운로드하므로 사용자가 처음으로 앱을 열 때 필요한 모든 항목이 앱에 포함됩니다. 하지만 앱이 시작될 때 Google Play에서 파일을 다운로드해야 하는 경우도 있습니다.

앱의 압축된 다운로드 크기가 100MB보다 큰데도 확장 파일을 사용하지 않으려면 최대 200MB의 압축된 다운로드 크기가 허용되는 Android App Bundle을 사용하여 앱을 업로드하면 됩니다. 또한 App Bundle을 사용하면 APK 생성 및 Google Play 서명이 연기되므로 사용자는 앱 실행에 필요한 코드와 리소스만 담긴 최적화된 APK를 다운로드하게 됩니다. 개발자가 여러 개의 APK 또는 확장 파일을 빌드하고 서명하고 관리할 필요가 없으며 사용자는 더 작고 최적화된 앱을 다운로드하게 됩니다.

개요

Google Play Console을 사용하여 APK를 업로드할 때마다 확장 파일 한두 개를 APK에 추가할 수 있습니다. 각 파일은 크기가 최대 2GB이고 형식에 제한이 없지만 압축 파일을 사용하여 다운로드하는 동안 대역폭을 절약하는 것이 좋습니다. 개념적으로 각 확장 파일의 역할은 서로 다릅니다.

  • 기본 확장 파일은 앱에 필요한 추가 리소스를 위한 기본 확장 파일입니다.
  • 패치 확장 파일은 선택사항이며 기본 확장 파일의 소규모 업데이트에 사용됩니다.

두 확장 파일을 원하는 방식으로 사용할 수 있지만 기본 확장 파일은 기본 저작물을 제공하는 데 사용하고 거의 업데이트하지 않는 것이 좋습니다. 패치 확장 파일은 크기가 더 작고 '패치를 전달'하는 역할을 하며 각 주요 출시에서 또는 필요에 따라 업데이트해야 합니다.

하지만 앱 업데이트에 새 패치 확장 파일만 필요한 경우에도 새 APK를 업데이트된 versionCode와 함께 매니페스트에 업로드해야 합니다. Play Console을 통해 기존 APK에 확장 파일을 업로드할 수 없습니다.

참고: 패치 확장 파일은 의미상 기본 확장 파일과 동일하며 각 파일을 원하는 방식으로 사용할 수 있습니다.

파일 이름 형식

업로드할 수 있는 확장 파일의 형식에는 제한이 없습니다(ZIP, PDF, MP4 등). JOBB 도구를 사용하여 리소스 파일 세트 및 세트의 후속 패치를 캡슐화하고 암호화할 수도 있습니다. 파일 형식과 관계없이 Google Play에서는 파일을 불투명 바이너리 blob으로 간주하고 다음 스키마를 사용하여 파일의 이름을 바꿉니다.

[main|patch].<expansion-version>.<package-name>.obb

이 스키마에는 세 가지 구성요소가 있습니다.

main 또는 patch
파일이 기본 확장 파일인지 패치 확장 파일인지 지정합니다. APK마다 기본 파일 1개와 패치 파일 1개만 있을 수 있습니다.
<expansion-version>
확장이 처음 연결되는 APK의 버전 코드와 일치하는 정수입니다 (앱의 android:versionCode 값과 일치).

Play Console을 사용하면 업로드된 확장 파일을 새 APK와 함께 재사용할 수 있지만 확장 파일의 이름이 변경되지 않고 파일을 처음 업로드할 때 적용된 버전이 유지되므로 '처음'이 강조됩니다.

<package-name>
앱의 자바 스타일 패키지 이름입니다.

예를 들어 APK 버전이 314159이고 패키지 이름이 com.example.app이라고 가정합니다. 기본 확장 파일을 업로드하면 파일 이름이 다음으로 바뀝니다.

main.314159.com.example.app.obb

저장 위치

Google Play에서 확장 파일을 기기에 다운로드하면 파일이 시스템의 공유 저장공간 위치에 저장됩니다. 제대로 작동하려면 확장 파일을 삭제하거나 이동하거나 이름을 바꾸어서는 안 됩니다. 앱이 Google Play에서 직접 다운로드해야 하는 경우 정확히 동일한 위치에 파일을 저장해야 합니다.

getObbDir() 메서드는 확장 파일의 구체적인 위치를 다음 형식으로 반환합니다.

<shared-storage>/Android/obb/<package-name>/
  • <shared-storage>는 공유 저장공간의 경로로 getExternalStorageDirectory()에서 가져올 수 있습니다.
  • <package-name>은 앱의 자바 스타일 패키지 이름으로 getPackageName()에서 가져올 수 있습니다.

각 앱에서 이 디렉터리에 있는 확장 파일의 수는 두 개를 넘지 않습니다. 하나는 기본 확장 파일이고 다른 하나는 패치 확장 파일(필요한 경우)입니다. 이전 버전은 새 확장 파일로 앱을 업데이트할 때 덮어쓰기됩니다. Android 4.4(API 수준 19) 이후 앱에서 외부 저장소 권한 없이 OBB 확장 파일을 읽을 수 있습니다. 하지만 Android 6.0(API 수준 23) 이후의 일부 구현에는 여전히 권한이 필요하므로 앱 매니페스트에서 READ_EXTERNAL_STORAGE 권한을 선언하고 런타임 시 다음과 같이 권한을 요청해야 합니다.

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

Android 버전 6 이후의 경우 런타임에 외부 저장소 권한을 요청해야 합니다. 하지만 Android의 일부 구현에서는 OBB 파일을 읽기 위한 권한이 필요하지 않습니다. 다음 코드 스니펫은 외부 저장소 권한을 요청하기 전에 읽기 액세스 권한을 확인하는 방법을 보여줍니다.

Kotlin

val obb = File(obb_filename)
var open_failed = false

try {
    BufferedReader(FileReader(obb)).also { br ->
        ReadObbFile(br)
    }
} catch (e: IOException) {
    open_failed = true
}

if (open_failed) {
    // request READ_EXTERNAL_STORAGE permission before reading OBB file
    ReadObbFileWithPermission()
}

Java

File obb = new File(obb_filename);
 boolean open_failed = false;

 try {
     BufferedReader br = new BufferedReader(new FileReader(obb));
     open_failed = false;
     ReadObbFile(br);
 } catch (IOException e) {
     open_failed = true;
 }

 if (open_failed) {
     // request READ_EXTERNAL_STORAGE permission before reading OBB file
     ReadObbFileWithPermission();
 }

확장 파일의 콘텐츠를 압축해제해야 하는 경우 나중에 OBB 확장 파일을 삭제하지 말고 압축해제된 데이터를 동일한 디렉터리에 저장하지 마세요. 압축해제된 파일은 getExternalFilesDir()에 의해 지정된 디렉터리에 저장해야 합니다. 하지만 가능한 경우 데이터를 압축해제할 필요 없이 파일에서 직접 데이터를 읽을 수 있는 확장 파일 형식을 사용하는 것이 가장 좋습니다. 예를 들어 Google에서는 ZIP 파일에서 직접 데이터를 읽는 APK 확장 Zip 라이브러리라는 라이브러리 프로젝트를 제공합니다.

주의: APK 파일과 달리 공유 저장공간에 저장된 모든 파일은 사용자 및 다른 앱에서 읽을 수 있습니다.

팁: 미디어 파일을 ZIP 파일로 패키징하는 경우 ZIP 파일을 압축해제할 필요 없이 오프셋 및 길이 컨트롤(예: MediaPlayer.setDataSource()SoundPool.load())을 사용하여 파일에 미디어 재생 호출을 사용할 수 있습니다. 이 작업을 실행하려면 ZIP 패키지를 만들 때 미디어 파일을 추가로 압축해서는 안 됩니다. 예를 들어 zip 도구를 사용하는 경우 -n 옵션을 사용하여 압축하지 말아야 하는 파일 접미사를 지정해야 합니다.
zip -n .mp4;.ogg main_expansion media_files

다운로드 프로세스

대체로 Google Play에서는 APK를 기기에 다운로드하는 동시에 확장 파일을 다운로드하고 저장합니다. 하지만 Google Play에서 확장 파일을 다운로드할 수 없거나 사용자가 이전에 다운로드된 확장 파일을 삭제했을 수도 있습니다. 이런 상황을 처리하려면 앱에서 기본 활동이 시작될 때 Google Play에서 제공하는 URL을 사용하여 파일을 직접 다운로드할 수 있어야 합니다.

대략적인 다운로드 프로세스는 다음과 같습니다.

  1. 사용자가 Google Play에서 앱 설치를 선택합니다.
  2. Google Play에서 확장 파일을 다운로드할 수 있는 경우 (대부분 기기의 경우) APK와 함께 확장 파일을 다운로드합니다.

    Google Play에서 확장 파일을 다운로드할 수 없는 경우에는 APK만 다운로드합니다.

  3. 사용자가 앱을 실행하면 앱에서 확장 파일이 기기에 이미 저장되어 있는지 확인해야 합니다.
    1. 저장된 경우 앱을 사용할 수 있습니다.
    2. 저장되지 않은 경우 앱에서 HTTP를 통해 Google Play로부터 확장 파일을 다운로드해야 합니다. 앱에서 각 확장 파일의 이름, 파일 크기 및 URL을 반환하는 Google Play의 앱 라이선스 서비스를 사용하여 Google Play 클라이언트에 요청을 전송해야 합니다. 그런 다음 개발자가 이 정보를 사용하여 파일을 다운로드하고 적절한 저장 위치에 저장합니다.

주의: 앱이 시작될 때 기기에 아직 파일이 없는 경우 Google Play에서 확장 파일을 다운로드하기 위해 필요한 코드를 포함하는 것이 중요합니다. 다음 확장 파일 다운로드 섹션에 설명된 대로 Google에서는 이 프로세스를 크게 간소화하고 최소한의 개발자 코드를 사용하여 서비스에서 파일을 다운로드할 수 있는 라이브러리를 제공합니다.

개발 시 고려할 사항

다음은 앱에서 확장 파일을 사용하기 위해 실행해야 하는 작업의 요약입니다.

  1. 먼저 앱의 압축된 다운로드 크기가 100MB보다 커야 하는지 확인합니다. 공간은 아주 중요하며 총 다운로드 크기를 가능한 한 작게 유지해야 합니다. 앱에서 여러 화면 밀도를 위한 여러 버전의 그래픽 저작물을 제공하기 위해 100MB를 초과하는 공간을 사용하는 경우 각 APK에 APK에서 타겟팅하는 화면에 필요한 저작물만 포함되는 여러 APK를 대신 게시해 보세요. Google Play에 게시할 때 최상의 결과를 얻으려면 앱의 컴파일된 코드와 리소스가 모두 포함되지만 APK 생성 및 Google Play 서명은 연기되는 Android App Bundle을 업로드하세요.
  2. APK에서 분리할 앱 리소스를 결정하고 기본 확장 파일로 사용할 파일에 패키징합니다.

    일반적으로 기본 확장 파일을 업데이트할 때는 두 번째 패치 확장 파일만 사용해야 합니다. 하지만 리소스가 기본 확장 파일의 2GB 제한을 초과하는 경우 저작물의 나머지 부분에 패치 파일을 사용할 수 있습니다.

  3. 기기의 공유 저장소 위치에 있는 확장 파일의 리소스를 사용하도록 앱을 개발합니다.

    확장 파일을 삭제하거나 이동하거나 이름을 바꾸어서는 안 됩니다.

    앱에서 특정 형식을 요구하지 않는 경우 확장 파일용 ZIP 파일을 만든 다음 APK 확장 Zip 라이브러리를 사용하여 읽는 것이 좋습니다.

  4. 앱이 시작될 때 기기에 확장 파일이 있는지 확인하는 로직을 앱의 기본 활동에 추가합니다. 기기에 파일이 없는 경우 Google Play의 앱 라이선스 서비스를 사용하여 확장 파일의 URL을 요청한 다음 확장 파일을 다운로드하고 저장하세요.

    작성해야 하는 코드의 양을 크게 줄이고 다운로드하는 동안 적절한 사용자 환경을 제공하려면 다운로드 프로그램 라이브러리를 사용하여 다운로드 동작을 구현하는 것이 좋습니다.

    라이브러리를 사용하는 대신 자체 다운로드 서비스를 빌드하는 경우 확장 파일의 이름을 변경해서는 안 되며 확장 파일을 적절한 저장 위치에 저장해야 합니다.

앱 개발을 완료한 후에는 확장 파일 테스트 가이드를 따르세요.

규칙 및 제한사항

APK 확장 파일 추가는 Play Console을 사용하여 앱을 업로드할 때 사용할 수 있는 기능입니다. 앱을 처음으로 업로드하거나 확장 파일을 사용하는 앱을 업데이트하는 경우 다음 규칙 및 제한사항에 유의해야 합니다.

  1. 각 확장 파일은 2GB 이하여야 합니다.
  2. Google Play에서 확장 파일을 다운로드하려면 사용자가 Google Play에서 앱을 획득했어야 합니다. 앱이 다른 방법으로 설치된 경우 Google Play에서 확장 파일의 URL을 제공하지 않습니다.
  3. 앱 내에서 다운로드를 실행하는 경우 Google Play에서 제공하는 각 파일의 URL은 다운로드마다 고유하며 각 URL은 앱에 부여된 직후에 만료됩니다.
  4. 새 APK를 사용하여 앱을 업데이트하거나 동일한 앱을 위해 여러 APK를 업로드하는 경우 이전 APK를 위해 업로드했던 확장 파일을 선택할 수 있습니다. 확장 파일의 이름은 변경되지 않으며 파일이 원래 연결되었던 APK에서 수신한 버전을 유지합니다.
  5. 여러 기기에 서로 다른 확장 파일을 제공하기 위해 확장 파일을 여러 APK와 함께 사용하는 경우에도 각 기기에 고유한 versionCode 값을 제공하고 서로 다른 필터를 선언하려면 기기별로 별도의 APK를 업로드해야 합니다.
  6. 확장 파일을 변경하는 것만으로는 앱 업데이트를 출시할 수 없습니다. 앱을 업데이트하려면 새 APK를 업로드해야 합니다. 변경사항이 확장 파일의 저작물과만 관련된 경우 versionCode(때로는 versionName도 함께)만 변경하여 APK를 업데이트할 수 있습니다.

  7. obb/ 디렉터리에 다른 데이터를 저장하지 않습니다. 일부 데이터를 압축해제해야 하는 경우 getExternalFilesDir()에 의해 지정된 위치에 데이터를 저장하세요.
  8. .obb 확장 파일을 삭제하거나 이름을 바꾸지 않습니다(업데이트를 실행하지 않는 경우). 삭제하거나 이름을 바꾸면 Google Play(또는 앱 자체)에서 반복적으로 확장 파일을 다운로드합니다.
  9. 확장 파일을 수동으로 업데이트할 때는 이전 확장 파일을 삭제해야 합니다.

확장 파일 다운로드

대부분의 경우 Google Play에서는 APK를 설치하거나 업데이트하는 동시에 확장 파일을 다운로드하여 기기에 저장합니다. 이에 따라 앱을 처음 실행할 때 확장 파일을 사용할 수 있게 됩니다. 하지만 앱에서 Google Play 앱 라이선스 서비스의 응답에 제공된 URL에 요청하여 확장 파일을 직접 다운로드해야 하는 경우도 있습니다.

확장 파일을 다운로드하기 위해 필요한 기본 로직은 다음과 같습니다.

  1. 앱이 시작되면 공유 저장공간 위치 (Android/obb/<package-name>/ 디렉터리)에서 확장 파일을 찾습니다.
    1. 이 위치에 확장 파일이 있으면 설정이 완료되고 앱을 계속 실행할 수 있습니다.
    2. 확장 파일이 해당 위치에 없는 경우 다음을 수행합니다.
      1. Google Play의 앱 라이선스를 사용해 요청을 실행하여 앱의 확장 파일 이름, 크기, URL을 가져옵니다.
      2. Google Play에서 제공한 URL을 사용하여 확장 파일을 다운로드하고 저장합니다. 파일을 반드시 공유 저장공간 위치(Android/obb/<package-name>/)에 저장하고 Google Play의 응답에 제공된 정확한 파일 이름을 사용해야 합니다.

        참고: Google Play에서 제공하는 확장 파일의 URL은 다운로드마다 고유하며 각 URL은 앱에 부여된 직후에 만료됩니다.

앱이 유료 앱이 아닌 무료인 경우 아마도 앱 라이선스 서비스를 사용해보지 않았을 것입니다. 이 서비스는 기본적으로 개발자가 앱에 라이선스 정책을 시행하고 사용자에게 앱을 사용할 수 있는 권리가 있는지(사용자가 Google Play에서 정당하게 비용을 지불했는지) 확인할 수 있도록 설계되었습니다. 확장 파일의 기능을 촉진하기 위해 라이선스 서비스는 앱에 Google Play에서 호스팅되는 앱 확장 파일의 URL이 포함된 응답을 제공하도록 향상되었습니다. 따라서 앱이 사용자에게 무료로 제공되는 경우에도 APK 확장 파일을 사용하려면 라이선스 인증 라이브러리(LVL)를 포함해야 합니다. 물론 앱이 무료인 경우 라이선스 인증을 시행할 필요가 없습니다. 확장 파일의 URL을 반환하는 요청을 실행하기 위한 라이브러리만 있으면 됩니다.

참고: 앱이 무료이든 유료이든 관계없이 Google Play에서는 사용자가 Google Play에서 앱을 획득한 경우에만 확장 파일 URL을 반환합니다.

LVL 외에도 HTTP 연결을 통해 확장 파일을 다운로드하고 기기 공유 저장공간의 적절한 위치에 저장하는 코드 세트가 필요합니다. 이 절차를 앱에 구축할 때 고려해야 할 몇 가지 사항이 있습니다.

  • 기기에 확장 파일을 저장할 공간이 충분하지 않을 수도 있으므로 다운로드를 시작하기 전에 확인하고 공간이 충분하지 않은 경우 사용자에게 경고해야 합니다.
  • 사용자 상호작용을 차단하지 않고 다운로드가 완료되는 동안 사용자가 앱을 종료할 수 있도록 하려면 파일 다운로드가 백그라운드 서비스로 실행되어야 합니다.
  • 요청 및 다운로드 도중에 다양한 오류가 발생할 수 있으며 적절하게 처리해야 합니다.
  • 다운로드 도중에 네트워크 연결이 변경될 수 있으므로 이러한 변경사항을 처리해야 하며 다운로드가 중단된 경우 가능할 때 다운로드를 계속해야 합니다.
  • 다운로드가 백그라운드에서 실행되는 동안 다운로드 진행률을 나타내고, 다운로드가 완료되면 사용자에게 알리고, 선택된 경우 사용자를 앱으로 다시 이동하는 알림을 제공해야 합니다.

이 작업을 간소화하기 위해 Google에서는 라이선스 서비스를 통해 확장 파일 URL을 요청하고, 확장 파일을 다운로드하고, 위에 나열된 모든 작업을 실행하고, 개발자 활동을 일시중지한 후 다운로드를 계속할 수 있는 다운로드 프로그램 라이브러리를 빌드했습니다. 다운로드 프로그램 라이브러리와 몇 가지 코드 훅을 앱에 추가하면 추가 코딩 작업 없이 확장 파일을 다운로드할 수 있습니다. 따라서 개발자의 노력을 최소화하면서 최상의 사용자 환경을 제공하려면 다운로드 프로그램 라이브러리를 사용하여 확장 파일을 다운로드하는 것이 좋습니다. 다음 섹션에서는 라이브러리를 앱에 통합하는 방법을 설명합니다.

Google Play URL을 사용하여 확장 파일을 다운로드하는 자체 솔루션을 개발하려면 앱 라이선스 설명서에 따라 라이선스 요청을 실행한 후 추가 응답에서 확장 파일 이름, 크기, URL을 가져와야 합니다. 라이선스 서비스에서 확장 파일 이름, 크기, URL을 캡처하는 (라이선스 인증 라이브러리에 포함된) APKExpansionPolicy 클래스를 라이선스 정책으로 사용해야 합니다.

다운로드 프로그램 라이브러리 정보

APK 확장 파일을 앱과 함께 사용하고 개발자의 노력을 최소화하면서 최상의 사용자 환경을 제공하려면 Google Play APK 확장 라이브러리 패키지에 포함된 다운로드 프로그램 라이브러리를 사용하는 것이 좋습니다. 이 라이브러리는 백그라운드 서비스에서 확장 파일을 다운로드하고, 다운로드 상태가 포함된 사용자 알림을 표시하고, 네트워크 연결 중단을 처리하고, 가능할 때 다운로드를 계속하는 등 다양한 작업을 처리합니다.

다운로드 프로그램 라이브러리를 사용하여 확장 파일 다운로드를 구현하려면 다음과 같이 하면 됩니다.

  • 개발자가 코드 몇 줄만 입력하면 되는 특수 Service 서브클래스 및 BroadcastReceiver 서브클래스를 확장합니다.
  • 확장 파일이 이미 다운로드되었는지 확인하고 다운로드되지 않은 경우 다운로드 프로세스를 호출하고 진행률 UI를 표시하는 로직을 기본 활동에 추가합니다.
  • 기본 활동에서 몇 가지 메서드를 사용하여 다운로드 진행률에 관한 업데이트를 수신하는 콜백 인터페이스를 구현합니다.

다음 섹션에서는 다운로드 프로그램 라이브러리를 사용하여 앱을 설정하는 방법을 설명합니다.

다운로드 프로그램 라이브러리 사용 준비

다운로드 프로그램 라이브러리를 사용하려면 SDK Manager에서 패키지 두 개를 다운로드하고 앱에 적절한 라이브러리를 추가해야 합니다.

먼저 Android SDK Manager(Tools > SDK Manager)를 열고 Appearance & Behavior > System Settings > Android SDK에서 SDK Tools 탭을 선택하여 다음 패키지를 선택하고 다운로드합니다.

  • Google Play 라이선스 라이브러리 패키지
  • Google Play APK 확장 라이브러리 패키지

라이선스 인증 라이브러리 및 다운로드 프로그램 라이브러리의 새 라이브러리 모듈을 만듭니다. 각 라이브러리의 경우:

  1. File > New > New Module을 선택합니다.
  2. Create New Module 창에서 Android Library를 선택한 다음 Next를 선택합니다.
  3. 'Google Play 라이선스 라이브러리' 및 'Google Play 다운로드 프로그램 라이브러리'와 같은 앱/라이브러리 이름을 지정하고 Minimum SDK level을 선택한 다음 Finish를 선택합니다.
  4. File > Project Structure를 선택합니다.
  5. Properties 탭을 선택하고 Library Repository<sdk>/extras/google/ 디렉터리의 라이브러리(라이선스 인증 라이브러리의 경우 play_licensing/, 다운로드 프로그램 라이브러리의 경우 play_apk_expansion/downloader_library/)를 입력합니다.
  6. OK를 선택하여 새 모듈을 만듭니다.

참고: 다운로드 프로그램 라이브러리는 라이선스 인증 라이브러리에 종속됩니다. 라이선스 인증 라이브러리를 다운로드 프로그램 라이브러리의 프로젝트 속성에 추가해야 합니다.

또는 명령줄에서 라이브러리를 포함하도록 프로젝트를 업데이트하세요.

  1. 디렉터리를 <sdk>/tools/ 디렉터리로 변경합니다.
  2. --library 옵션으로 android update project를 실행하여 LVL 및 다운로드 프로그램 라이브러리를 프로젝트에 추가합니다. 예:
    android update project --path ~/Android/MyApp \
    --library ~/android_sdk/extras/google/market_licensing \
    --library ~/android_sdk/extras/google/market_apk_expansion/downloader_library
    

라이선스 인증 라이브러리와 다운로드 프로그램 라이브러리를 모두 앱에 추가하면 Google Play에서 확장 파일을 다운로드하는 기능을 신속하게 통합할 수 있습니다. 확장 파일의 형식과 공유 저장공간에서 확장 파일을 읽는 방법은 앱의 필요에 따라 별도로 구현해야 합니다.

팁: APK 확장 패키지에는 앱에서 다운로드 프로그램 라이브러리를 사용하는 방법을 보여주는 샘플 앱이 포함됩니다. 샘플에서는 APK 확장 Zip 라이브러리라는 APK 확장 패키지에서 사용할 수 있는 제3의 라이브러리를 사용합니다. 확장 파일에 ZIP 파일을 사용하려면 앱에 APK 확장 Zip 라이브러리도 추가하는 것이 좋습니다. 자세한 내용은 아래의 APK 확장 Zip 라이브러리 사용 섹션을 참조하세요.

사용자 권한 선언

확장 파일을 다운로드하려면 다운로드 프로그램 라이브러리에 앱의 매니페스트 파일에서 선언해야 하는 여러 권한이 필요합니다. 예를 들면 다음과 같습니다.

<manifest ...>
    <!-- Required to access Google Play Licensing -->
    <uses-permission android:name="com.android.vending.CHECK_LICENSE" />

    <!-- Required to download files from Google Play -->
    <uses-permission android:name="android.permission.INTERNET" />

    <!-- Required to keep CPU alive while downloading files
        (NOT to keep screen awake) -->
    <uses-permission android:name="android.permission.WAKE_LOCK" />

    <!-- Required to poll the state of the network connection
        and respond to changes -->
    <uses-permission
        android:name="android.permission.ACCESS_NETWORK_STATE" />

    <!-- Required to check whether Wi-Fi is enabled -->
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

    <!-- Required to read and write the expansion files on shared storage -->
    <uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    ...
</manifest>

참고: 기본적으로 다운로드 프로그램 라이브러리에는 API 레벨 4가 필요하지만 APK 확장 Zip 라이브러리에는 API 레벨 5가 필요합니다.

다운로드 프로그램 서비스 구현

다운로드를 백그라운드에서 실행하기 위해 다운로드 프로그램 라이브러리에서는 개발자가 확장해야 하는 DownloaderService라는 자체 Service 서브클래스를 제공합니다. DownloaderService는 확장 파일을 자동으로 다운로드하는 것 외에 다음 작업도 실행합니다.

  • 필요한 경우(예: 연결이 끊긴 경우) 다운로드를 일시중지하고 가능한 경우(연결된 경우) 다운로드를 계속하기 위해 기기 네트워크 연결(CONNECTIVITY_ACTION 브로드캐스트)의 변경사항을 수신 대기하는 BroadcastReceiver를 등록합니다.
  • 서비스가 중단되는 경우 다운로드를 다시 시도하도록 RTC_WAKEUP 알람을 예약합니다.
  • 다운로드 진행률 및 오류나 상태 변경사항을 표시하는 맞춤 Notification을 만듭니다.
  • 앱에서 다운로드를 수동으로 일시중지했다가 계속할 수 있도록 허용합니다.
  • 확장 파일을 다운로드하기 전에 공유 저장공간이 마운트되어 있고 사용할 수 있는지, 파일이 이미 존재하지 않는지, 공간이 충분한지 확인합니다. 충족되지 않는 사항이 있는 경우 사용자에게 알립니다.

앱에서 DownloaderService 클래스를 확장하는 클래스를 만들고 아래와 같은 메서드 3개를 재정의하여 구체적인 앱 세부정보를 제공하면 됩니다.

getPublicKey()
이 메서드는 Play Console의 프로필 페이지에서 사용할 수 있는 게시자 계정의 Base64로 인코딩된 RSA 공개 키인 문자열을 반환해야 합니다 (라이선스 설정 참고).
getSALT()
이 메서드는 라이선스 Policy에서 Obfuscator를 만드는 데 사용하는 임의의 바이트 배열을 반환해야 합니다. 솔트가 라이선스 데이터가 저장된 난독화된 SharedPreferences 파일이 고유하고 검색 불가능하도록 합니다.
getAlarmReceiverClassName()
이 메서드는 앱에서 다운로드가 다시 시작되어야 한다고 (다운로드 프로그램 서비스가 예기치 않게 중지되면 발생할 수 있음) 알리는 알람을 수신해야 하는 BroadcastReceiver의 클래스 이름을 반환해야 합니다.

예를 들어 다음은 DownloaderService의 전체 구현입니다.

Kotlin

// You must use the public key belonging to your publisher account
const val BASE64_PUBLIC_KEY = "YourLVLKey"
// You should also modify this salt
val SALT = byteArrayOf(
        1, 42, -12, -1, 54, 98, -100, -12, 43, 2,
        -8, -4, 9, 5, -106, -107, -33, 45, -1, 84
)

class SampleDownloaderService : DownloaderService() {

    override fun getPublicKey(): String = BASE64_PUBLIC_KEY

    override fun getSALT(): ByteArray = SALT

    override fun getAlarmReceiverClassName(): String = SampleAlarmReceiver::class.java.name
}

Java

public class SampleDownloaderService extends DownloaderService {
    // You must use the public key belonging to your publisher account
    public static final String BASE64_PUBLIC_KEY = "YourLVLKey";
    // You should also modify this salt
    public static final byte[] SALT = new byte[] { 1, 42, -12, -1, 54, 98,
            -100, -12, 43, 2, -8, -4, 9, 5, -106, -107, -33, 45, -1, 84
    };

    @Override
    public String getPublicKey() {
        return BASE64_PUBLIC_KEY;
    }

    @Override
    public byte[] getSALT() {
        return SALT;
    }

    @Override
    public String getAlarmReceiverClassName() {
        return SampleAlarmReceiver.class.getName();
    }
}

알림: BASE64_PUBLIC_KEY 값을 게시자 계정에 속한 공개 키가 되도록 업데이트해야 합니다. 이 키는 프로필 정보의 Developer Console에서 찾을 수 있습니다. 이 과정은 다운로드를 테스트하는 경우에도 필요합니다.

manifest 파일에서 서비스를 선언해야 합니다.

<app ...>
    <service android:name=".SampleDownloaderService" />
    ...
</app>

알람 수신기 구현

파일 다운로드 진행률을 모니터링하고 필요한 경우 다운로드를 다시 시작하기 위해 DownloaderService에서는 앱의 BroadcastReceiverIntent를 전달하는 RTC_WAKEUP 알람을 예약합니다. 다운로드 프로그램 라이브러리에서 다운로드의 상태를 확인하고 필요한 경우 다운로드를 다시 시작하는 API를 호출하도록 BroadcastReceiver를 정의해야 합니다.

DownloaderClientMarshaller.startDownloadServiceIfRequired()를 호출하도록 onReceive() 메서드를 재정의하면 됩니다.

예:

Kotlin

class SampleAlarmReceiver : BroadcastReceiver() {

    override fun onReceive(context: Context, intent: Intent) {
        try {
            DownloaderClientMarshaller.startDownloadServiceIfRequired(
                    context,
                    intent,
                    SampleDownloaderService::class.java
            )
        } catch (e: PackageManager.NameNotFoundException) {
            e.printStackTrace()
        }
    }
}

Java

public class SampleAlarmReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        try {
            DownloaderClientMarshaller.startDownloadServiceIfRequired(context,
                intent, SampleDownloaderService.class);
        } catch (NameNotFoundException e) {
            e.printStackTrace();
        }
    }
}

서비스의 getAlarmReceiverClassName() 메서드에서 이 클래스의 이름을 반환해야 합니다(이전 섹션 참조).

manifest 파일에서 수신기를 선언해야 합니다.

<app ...>
    <receiver android:name=".SampleAlarmReceiver" />
    ...
</app>

다운로드 시작

런처 아이콘에 의해 시작되는 앱의 기본 활동이 확장 파일이 이미 기기에 있는지 확인하고 기기에 없는 경우 다운로드를 시작해야 합니다.

다운로드 프로그램 라이브러리를 사용하여 다운로드를 시작하려면 다음 절차를 따라야 합니다.

  1. 파일이 다운로드되었는지 여부를 확인합니다.

    다운로드 프로그램 라이브러리의 Helper 클래스에 이 프로세스에 도움이 되는 API가 포함되어 있습니다.

    • getExpansionAPKFileName(Context, c, boolean mainFile, int versionCode)
    • doesFileExist(Context c, String fileName, long fileSize)

    예를 들어 APK 확장 패키지에 제공되는 샘플 앱은 활동의 onCreate() 메서드에서 다음 메서드를 호출하여 확장 파일이 이미 기기에 존재하는지 확인합니다.

    Kotlin

    fun expansionFilesDelivered(): Boolean {
        xAPKS.forEach { xf ->
            Helpers.getExpansionAPKFileName(this, xf.isBase, xf.fileVersion).also { fileName ->
                if (!Helpers.doesFileExist(this, fileName, xf.fileSize, false))
                    return false
            }
        }
        return true
    }
    

    Java

    boolean expansionFilesDelivered() {
        for (XAPKFile xf : xAPKS) {
            String fileName = Helpers.getExpansionAPKFileName(this, xf.isBase,
                xf.fileVersion);
            if (!Helpers.doesFileExist(this, fileName, xf.fileSize, false))
                return false;
        }
        return true;
    }
    

    이 경우 각 XAPKFile 객체에는 알려진 확장 파일의 버전 번호와 파일 크기 및 이 확장 파일이 기본 확장 파일인지에 관한 부울 값이 포함됩니다. 자세한 내용은 샘플 앱의 SampleDownloaderActivity 클래스를 참조하세요.

    이 메서드에서 false를 반환하면 앱이 다운로드를 시작해야 합니다.

  2. 정적 메서드 DownloaderClientMarshaller.startDownloadServiceIfRequired(Context c, PendingIntent notificationClient, Class<?> serviceClass)를 호출하여 다운로드를 시작합니다.

    이 메서드에는 다음 매개변수가 사용됩니다.

    • context: 앱의 Context입니다.
    • notificationClient: 기본 활동을 시작하기 위한 PendingIntent입니다. 이 매개변수는 DownloaderService에서 다운로드 진행률을 표시하기 위해 만드는 Notification에 사용됩니다. 사용자가 알림을 선택하면 시스템에서 여기에 제공된 PendingIntent를 호출하며 다운로드 진행률을 표시하는 활동(일반적으로 다운로드를 시작한 것과 동일한 활동)을 엽니다.
    • serviceClass: DownloaderService의 구현을 위한 Class 객체로 서비스를 시작하고 필요한 경우 다운로드를 시작하는 데 필요합니다.

    이 메서드는 다운로드가 필요한지를 나타내는 정수를 반환합니다. 가능한 값은 다음과 같습니다.

    • NO_DOWNLOAD_REQUIRED: 파일이 이미 존재하거나 다운로드가 이미 진행 중인 경우 반환됩니다.
    • LVL_CHECK_REQUIRED: 확장 파일 URL을 획득하기 위해 라이선스 인증이 필요한 경우 반환됩니다.
    • DOWNLOAD_REQUIRED: 확장 파일 URL을 이미 알고 있지만 다운로드되지 않은 경우 반환됩니다.

    LVL_CHECK_REQUIREDDOWNLOAD_REQUIRED의 동작은 기본적으로 동일하며 일반적으로 개발자가 걱정할 필요가 없습니다. startDownloadServiceIfRequired()를 호출하는 기본 활동에서 응답이 NO_DOWNLOAD_REQUIRED인지만 확인하면 됩니다. 응답이 NO_DOWNLOAD_REQUIRED아닌 경우 다운로드 프로그램 라이브러리에서 다운로드를 시작하며 개발자는 다운로드 진행률을 표시하도록 활동 UI를 업데이트해야 합니다(다음 단계 참조). 응답이 NO_DOWNLOAD_REQUIRED이면 파일을 사용할 수 있으며 앱을 시작할 수 있습니다.

    예:

    Kotlin

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
    
        // Check if expansion files are available before going any further
        if (!expansionFilesDelivered()) {
            val pendingIntent =
                    // Build an Intent to start this activity from the Notification
                    Intent(this, MainActivity::class.java).apply {
                        flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP
                    }.let { notifierIntent ->
                        PendingIntent.getActivity(
                                this,
                                0,
                                notifierIntent,
                                PendingIntent.FLAG_UPDATE_CURRENT
                        )
                    }
    
    
            // Start the download service (if required)
            val startResult: Int = DownloaderClientMarshaller.startDownloadServiceIfRequired(
                    this,
                    pendingIntent,
                    SampleDownloaderService::class.java
            )
            // If download has started, initialize this activity to show
            // download progress
            if (startResult != DownloaderClientMarshaller.NO_DOWNLOAD_REQUIRED) {
                // This is where you do set up to display the download
                // progress (next step)
                ...
                return
            } // If the download wasn't necessary, fall through to start the app
        }
        startApp() // Expansion files are available, start the app
    }
    

    Java

    @Override
    public void onCreate(Bundle savedInstanceState) {
        // Check if expansion files are available before going any further
        if (!expansionFilesDelivered()) {
            // Build an Intent to start this activity from the Notification
            Intent notifierIntent = new Intent(this, MainActivity.getClass());
            notifierIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK |
                                    Intent.FLAG_ACTIVITY_CLEAR_TOP);
            ...
            PendingIntent pendingIntent = PendingIntent.getActivity(this, 0,
                    notifierIntent, PendingIntent.FLAG_UPDATE_CURRENT);
    
            // Start the download service (if required)
            int startResult =
                DownloaderClientMarshaller.startDownloadServiceIfRequired(this,
                            pendingIntent, SampleDownloaderService.class);
            // If download has started, initialize this activity to show
            // download progress
            if (startResult != DownloaderClientMarshaller.NO_DOWNLOAD_REQUIRED) {
                // This is where you do set up to display the download
                // progress (next step)
                ...
                return;
            } // If the download wasn't necessary, fall through to start the app
        }
        startApp(); // Expansion files are available, start the app
    }
    
  3. startDownloadServiceIfRequired() 메서드에서 NO_DOWNLOAD_REQUIRED아닌 응답을 반환하면 DownloaderClientMarshaller.CreateStub(IDownloaderClient client, Class<?> downloaderService)를 호출하여 IStub의 인스턴스를 만듭니다. IStub에서는 활동에서 다운로드 진행률에 관한 콜백을 수신하도록 활동과 다운로드 프로그램 서비스 사이에 바인딩을 제공합니다.

    CreateStub()을 호출하여 IStub을 인스턴스화하려면 IDownloaderClient 인터페이스의 구현 및 DownloaderService 구현에 전달해야 합니다. 다운로드 진행률 수신에 관한 다음 섹션에서는 IDownloaderClient 인터페이스를 설명합니다. 이 인터페이스는 일반적으로 다운로드 상태가 변경될 때 활동 UI를 업데이트할 수 있도록 Activity 클래스에서 구현해야 합니다.

    startDownloadServiceIfRequired()가 다운로드를 시작한 후 활동의 onCreate() 메서드 중에 CreateStub()를 호출하여 IStub를 인스턴스화하는 것이 좋습니다.

    예를 들어 이전의 onCreate() 코드 샘플에서는 다음과 같이 startDownloadServiceIfRequired() 결과에 응답할 수 있습니다.

    Kotlin

            // Start the download service (if required)
            val startResult = DownloaderClientMarshaller.startDownloadServiceIfRequired(
                    this@MainActivity,
                    pendingIntent,
                    SampleDownloaderService::class.java
            )
            // If download has started, initialize activity to show progress
            if (startResult != DownloaderClientMarshaller.NO_DOWNLOAD_REQUIRED) {
                // Instantiate a member instance of IStub
                downloaderClientStub =
                        DownloaderClientMarshaller.CreateStub(this, SampleDownloaderService::class.java)
                // Inflate layout that shows download progress
                setContentView(R.layout.downloader_ui)
                return
            }
    

    Java

            // Start the download service (if required)
            int startResult =
                DownloaderClientMarshaller.startDownloadServiceIfRequired(this,
                            pendingIntent, SampleDownloaderService.class);
            // If download has started, initialize activity to show progress
            if (startResult != DownloaderClientMarshaller.NO_DOWNLOAD_REQUIRED) {
                // Instantiate a member instance of IStub
                downloaderClientStub = DownloaderClientMarshaller.CreateStub(this,
                        SampleDownloaderService.class);
                // Inflate layout that shows download progress
                setContentView(R.layout.downloader_ui);
                return;
            }
    

    onCreate() 메서드에서 반환한 후 활동에서 onResume()의 호출을 수신하며 그런 다음 IStub에서 connect()를 호출하고 앱의 Context를 전달해야 합니다. 반대로 활동의 onStop() 콜백에서는 disconnect()를 호출해야 합니다.

    Kotlin

    override fun onResume() {
        downloaderClientStub?.connect(this)
        super.onResume()
    }
    
    override fun onStop() {
        downloaderClientStub?.disconnect(this)
        super.onStop()
    }
    

    Java

    @Override
    protected void onResume() {
        if (null != downloaderClientStub) {
            downloaderClientStub.connect(this);
        }
        super.onResume();
    }
    
    @Override
    protected void onStop() {
        if (null != downloaderClientStub) {
            downloaderClientStub.disconnect(this);
        }
        super.onStop();
    }
    

    IStub에서 connect()를 호출하면 활동이 DownloaderService에 바인딩되어 IDownloaderClient 인터페이스를 통해 다운로드 상태의 변경사항에 관한 콜백을 수신하게 됩니다.

다운로드 진행률 수신

다운로드 진행률에 관한 업데이트를 수신하고 DownloaderService와 상호작용하려면 다운로드 프로그램 라이브러리의 IDownloaderClient 인터페이스를 구현해야 합니다. 일반적으로 다운로드 진행률을 표시하고 서비스에 요청을 보내려면 다운로드를 시작하기 위해 사용하는 활동에서 이 인터페이스를 구현해야 합니다.

IDownloaderClient에 필요한 인터페이스 메서드는 다음과 같습니다.

onServiceConnected(Messenger m)
활동에서 IStub을 인스턴스화한 후 이 메서드의 호출을 수신하게 되며 이 호출에서는 DownloaderService의 인스턴스와 연결된 Messenger 객체를 전달합니다. 서비스에 요청(예를 들어 다운로드를 일시중지하고 계속하기 위한 요청)을 보내려면 DownloaderServiceMarshaller.CreateProxy()를 호출하여 서비스에 연결된 IDownloaderService 인터페이스를 수신해야 합니다.

권장되는 구현은 다음과 같습니다.

Kotlin

private var remoteService: IDownloaderService? = null
...

override fun onServiceConnected(m: Messenger) {
    remoteService = DownloaderServiceMarshaller.CreateProxy(m).apply {
        downloaderClientStub?.messenger?.also { messenger ->
            onClientUpdated(messenger)
        }
    }
}

Java

private IDownloaderService remoteService;
...

@Override
public void onServiceConnected(Messenger m) {
    remoteService = DownloaderServiceMarshaller.CreateProxy(m);
    remoteService.onClientUpdated(downloaderClientStub.getMessenger());
}

IDownloaderService 객체를 초기화하면 다운로드 프로그램 서비스에 명령어(예를 들어 다운로드를 일시중지하고 계속하기 위한 명령어, requestPauseDownload()requestContinueDownload())를 보낼 수 있습니다.

onDownloadStateChanged(int newState)
다운로드 서비스에서는 다운로드가 시작되거나 완료되는 경우와 같이 다운로드 상태가 변경되면 이 메서드를 호출합니다.

newState 값은 IDownloaderClient 클래스의 STATE_* 상수 중 하나에 의해 지정되는 여러 가능한 값 중 하나입니다.

사용자에게 유용한 메시지를 제공하기 위해 Helpers.getDownloaderStringResourceIDFromState()를 호출하여 각 상태에 상응하는 문자열을 요청할 수 있습니다. 이렇게 하면 다운로드 프로그램 라이브러리와 번들된 문자열 중 하나의 리소스 ID가 반환됩니다. 예를 들어 '로밍 중이어서 다운로드가 일시중지됨' 문자열은 STATE_PAUSED_ROAMING에 상응합니다.

onDownloadProgress(DownloadProgressInfo progress)
다운로드 서비스에서는 이 메서드를 호출하여 DownloadProgressInfo 객체를 제공합니다. 이 객체는 개발자가 다운로드 진행률 UI를 업데이트할 수 있도록 남은 예상 시간, 현재 속도, 전체 진행률, 합계 등 다운로드 진행률에 관한 다양한 정보를 설명합니다.

팁: 다운로드 진행률 UI를 업데이트하는 이러한 콜백의 예는 APK 확장 패키지와 함께 제공되는 샘플 앱의 SampleDownloaderActivity를 참조하세요.

IDownloaderService 인터페이스의 유용한 공개 메서드는 다음과 같습니다.

requestPauseDownload()
다운로드를 일시중지합니다.
requestContinueDownload()
일시중지된 다운로드를 계속합니다.
setDownloadFlags(int flags)
네트워크 유형에 따라 파일을 다운로드할 수 있는 사용자 환경설정을 지정합니다. 현재 구현에서는 FLAGS_DOWNLOAD_OVER_CELLULAR 플래그 하나를 지원하지만 다른 플래그를 추가할 수 있습니다. 기본적으로 이 플래그는 사용 설정되지 않으므로 확장 파일을 다운로드하려면 사용자가 Wi-Fi에 연결되어 있어야 합니다. 이동통신망을 통한 다운로드가 가능한 사용자 환경설정을 제공하는 것이 좋습니다. 이 경우 다음을 호출할 수 있습니다.

Kotlin

remoteService = DownloaderServiceMarshaller.CreateProxy(m).apply {
    ...
    setDownloadFlags(IDownloaderService.FLAGS_DOWNLOAD_OVER_CELLULAR)
}

Java

remoteService
    .setDownloadFlags(IDownloaderService.FLAGS_DOWNLOAD_OVER_CELLULAR);

APKExpansionPolicy 사용

Google Play 다운로드 프로그램 라이브러리를 사용하는 대신 자체 다운로드 프로그램 서비스를 빌드하는 경우에도 라이선스 인증 라이브러리에 제공되는 APKExpansionPolicy를 사용해야 합니다. APKExpansionPolicy 클래스는 (Google Play 라이선스 인증 라이브러리에서 사용할 수 있는) ServerManagedPolicy와 거의 동일하지만 APK 확장 파일 추가 응답의 처리 기능이 추가로 포함되어 있습니다.

참고: 이전 섹션에 설명된 대로 다운로드 프로그램 라이브러리사용하는 경우 라이브러리에서 APKExpansionPolicy와 모든 상호작용을 실행하므로 이 클래스를 직접 사용하지 않아도 됩니다.

이 클래스에는 사용 가능한 확장 파일에 관한 필수 정보를 얻는 데 필요한 메서드가 포함되어 있습니다.

  • getExpansionURLCount()
  • getExpansionURL(int index)
  • getExpansionFileName(int index)
  • getExpansionFileSize(int index)

다운로드 프로그램 라이브러리를 사용하지 않는 경우 APKExpansionPolicy를 사용하는 방법에 관한 자세한 내용은 현재 문서와 같이 라이선스 정책을 구현하는 방법을 설명하는 앱에 라이선스 추가에 관한 문서를 참조하세요.

확장 파일 읽기

APK 확장 파일이 기기에 저장된 후 파일을 읽는 방법은 개발자가 사용한 파일 형식에 따라 다릅니다. 개요에 설명된 대로 확장 파일의 종류에는 제한이 없으며 특정한 파일 이름 형식을 사용하여 이름이 바뀌고 <shared-storage>/Android/obb/<package-name>/에 저장됩니다.

파일을 읽는 방법과 관계없이 항상 외부 저장소에서 파일을 읽을 수 있는지 먼저 확인해야 합니다. 사용자가 USB를 통해 저장소를 컴퓨터에 마운트했거나 실제로 SD 카드를 삭제했을 가능성이 있습니다.

참고: 앱이 시작되면 항상 외부 저장공간이 사용 가능하며 getExternalStorageState()를 호출하여 읽을 수 있는지 확인해야 합니다. 이 메서드에서는 외부 저장소의 상태를 나타내는 가능한 여러 문자열 중 하나를 반환합니다. 앱에서 읽을 수 있으려면 반환 값이 MEDIA_MOUNTED이어야 합니다.

파일 이름 가져오기

개요에 설명된 대로 APK 확장 파일은 특정한 파일 이름 형식을 사용하여 저장됩니다.

[main|patch].<expansion-version>.<package-name>.obb

확장 파일의 위치와 이름을 가져오려면 getExternalStorageDirectory()getPackageName() 메서드를 사용하여 파일의 경로를 구성해야 합니다.

다음 메서드를 사용하면 앱에서 두 확장 파일의 전체 경로가 포함된 배열을 가져올 수 있습니다.

Kotlin

fun getAPKExpansionFiles(ctx: Context, mainVersion: Int, patchVersion: Int): Array<String> {
    val packageName = ctx.packageName
    val ret = mutableListOf<String>()
    if (Environment.getExternalStorageState() == Environment.MEDIA_MOUNTED) {
        // Build the full path to the app's expansion files
        val root = Environment.getExternalStorageDirectory()
        val expPath = File(root.toString() + EXP_PATH + packageName)

        // Check that expansion file path exists
        if (expPath.exists()) {
            if (mainVersion > 0) {
                val strMainPath = "$expPath${File.separator}main.$mainVersion.$packageName.obb"
                val main = File(strMainPath)
                if (main.isFile) {
                    ret += strMainPath
                }
            }
            if (patchVersion > 0) {
                val strPatchPath = "$expPath${File.separator}patch.$mainVersion.$packageName.obb"
                val main = File(strPatchPath)
                if (main.isFile) {
                    ret += strPatchPath
                }
            }
        }
    }
    return ret.toTypedArray()
}

Java

// The shared path to all app expansion files
private final static String EXP_PATH = "/Android/obb/";

static String[] getAPKExpansionFiles(Context ctx, int mainVersion,
      int patchVersion) {
    String packageName = ctx.getPackageName();
    Vector<String> ret = new Vector<String>();
    if (Environment.getExternalStorageState()
          .equals(Environment.MEDIA_MOUNTED)) {
        // Build the full path to the app's expansion files
        File root = Environment.getExternalStorageDirectory();
        File expPath = new File(root.toString() + EXP_PATH + packageName);

        // Check that expansion file path exists
        if (expPath.exists()) {
            if ( mainVersion > 0 ) {
                String strMainPath = expPath + File.separator + "main." +
                        mainVersion + "." + packageName + ".obb";
                File main = new File(strMainPath);
                if ( main.isFile() ) {
                        ret.add(strMainPath);
                }
            }
            if ( patchVersion > 0 ) {
                String strPatchPath = expPath + File.separator + "patch." +
                        mainVersion + "." + packageName + ".obb";
                File main = new File(strPatchPath);
                if ( main.isFile() ) {
                        ret.add(strPatchPath);
                }
            }
        }
    }
    String[] retArray = new String[ret.size()];
    ret.toArray(retArray);
    return retArray;
}

이 메서드는 앱 Context 및 원하는 확장 파일의 버전을 전달하여 호출할 수 있습니다.

확장 파일 버전 번호를 확인하는 데는 여러 가지 방법이 있습니다. 한 가지 간단한 방법은 다운로드가 시작되면 APKExpansionPolicy 클래스의 getExpansionFileName(int index) 메서드로 확장 파일 이름을 쿼리하여 버전을 SharedPreferences 파일에 저장하는 것입니다. 그런 다음 확장 파일에 액세스하려고 할 때 SharedPreferences 파일을 읽어 버전 코드를 가져올 수 있습니다.

공유 저장공간에서 파일을 읽는 방법에 관한 자세한 내용은 데이터 저장소 문서를 참조하세요.

APK 확장 Zip 라이브러리 사용

Google Market Apk 확장 패키지에는 <sdk>/extras/google/google_market_apk_expansion/zip_file/에 ZIP 파일로 저장된 확장 파일을 읽는 데 도움이 되는 APK 확장 Zip 라이브러리라는 선택적 라이브러리가 포함되어 있습니다. 이 라이브러리를 사용하면 ZIP 확장 파일의 리소스를 가상 파일 시스템으로 쉽게 읽을 수 있습니다.

APK 확장 Zip 라이브러리에는 다음과 같은 클래스 및 API가 포함되어 있습니다.

APKExpansionSupport
확장 파일 이름 및 ZIP 파일에 액세스하는 메서드를 제공합니다.
getAPKExpansionFiles()
두 확장 파일의 전체 파일 경로를 반환하는 메서드로, 위에 나와 있습니다.
getAPKExpansionZipFile(Context ctx, int mainVersion, int patchVersion)
기본 파일과 패치 파일의 합을 나타내는 ZipResourceFile을 반환합니다. 즉 mainVersionpatchVersion을 모두 지정하는 경우 모든 데이터 및 기본 파일 위에 병합된 패치 파일 데이터의 읽기 액세스를 제공하는 ZipResourceFile이 반환됩니다.
ZipResourceFile
공유 저장공간에 있는 ZIP 파일을 나타내며 ZIP 파일을 기반으로 가상 파일 시스템을 제공하기 위한 모든 작업을 실행합니다. APKExpansionSupport.getAPKExpansionZipFile()을 사용하거나 ZipResourceFile로 확장 파일의 경로를 전달하여 인스턴스를 가져올 수 있습니다. 이 클래스에는 유용한 메서드가 많지만 일반적으로 대부분의 메서드에 액세스할 필요가 없습니다. 중요한 메서드는 다음과 같습니다.
getInputStream(String assetPath)
ZIP 파일 내의 파일을 읽기 위한 InputStream을 제공합니다. assetPath는 ZIP 파일 콘텐츠의 루트에 상대적인 원하는 파일의 경로여야 합니다.
getAssetFileDescriptor(String assetPath)
ZIP 파일 내 파일의 AssetFileDescriptor를 제공합니다. assetPath는 ZIP 파일 콘텐츠의 루트에 상대적인 원하는 파일의 경로여야 합니다. 이 메서드는 MediaPlayer API와 같이 AssetFileDescriptor가 필요한 특정 Android API에 유용합니다.
APEZProvider
대부분의 앱에서는 이 클래스를 사용할 필요가 없습니다. 이 클래스는 미디어 파일에 대한 Uri 액세스가 필요한 특정 Android API에 파일 액세스를 제공하기 위해 콘텐츠 제공업체 Uri를 통해 ZIP 파일의 데이터를 마샬링하는 ContentProvider를 정의합니다. 예를 들어 이 클래스는 VideoView.setVideoURI()로 동영상을 재생하려는 경우에 유용합니다.

미디어 파일의 ZIP 압축 건너뛰기

확장 파일을 사용하여 미디어 파일을 저장하는 경우에도 ZIP 파일을 통해 오프셋 컨트롤 및 길이 컨트롤(예: MediaPlayer.setDataSource()SoundPool.load())을 제공하는 Android 미디어 재생 호출을 사용할 수 있습니다. 이 작업을 실행하려면 ZIP 패키지를 만들 때 미디어 파일을 추가로 압축해서는 안 됩니다. 예를 들어 zip 도구를 사용하는 경우 -n 옵션을 사용하여 압축하지 말아야 하는 파일 접미사를 지정해야 합니다.

zip -n .mp4;.ogg main_expansion media_files

ZIP 파일에서 읽기

APK 확장 Zip 라이브러리를 사용하는 경우 ZIP에서 파일을 읽으려면 일반적으로 다음 코드가 필요합니다.

Kotlin

// Get a ZipResourceFile representing a merger of both the main and patch files
val expansionFile =
        APKExpansionSupport.getAPKExpansionZipFile(appContext, mainVersion, patchVersion)

// Get an input stream for a known file inside the expansion file ZIPs
expansionFile.getInputStream(pathToFileInsideZip).use {
    ...
}

Java

// Get a ZipResourceFile representing a merger of both the main and patch files
ZipResourceFile expansionFile =
    APKExpansionSupport.getAPKExpansionZipFile(appContext,
        mainVersion, patchVersion);

// Get an input stream for a known file inside the expansion file ZIPs
InputStream fileStream = expansionFile.getInputStream(pathToFileInsideZip);

위의 코드에서는 기본 확장 파일과 패치 확장 파일에서 모든 파일의 병합된 맵을 읽어 기본 확장 파일 또는 패치 확장 파일에 존재하는 모든 파일의 액세스를 제공합니다. 앱 android.content.Context 및 기본 확장 파일과 패치 확장 파일의 버전 번호만 있으면 getAPKExpansionFile() 메서드를 제공할 수 있습니다.

특정 확장 파일에서 읽으려면 ZipResourceFile 생성자를 원하는 확장 파일의 경로와 함께 사용하세요.

Kotlin

// Get a ZipResourceFile representing a specific expansion file
val expansionFile = ZipResourceFile(filePathToMyZip)

// Get an input stream for a known file inside the expansion file ZIPs
expansionFile.getInputStream(pathToFileInsideZip).use {
    ...
}

Java

// Get a ZipResourceFile representing a specific expansion file
ZipResourceFile expansionFile = new ZipResourceFile(filePathToMyZip);

// Get an input stream for a known file inside the expansion file ZIPs
InputStream fileStream = expansionFile.getInputStream(pathToFileInsideZip);

이 라이브러리를 확장 파일에 사용하는 방법에 관한 자세한 내용은 CRC를 사용하여 다운로드된 파일을 확인하는 추가 코드가 포함된 샘플 앱의 SampleDownloaderActivity 클래스를 참조하세요. 이 샘플을 자체 구현의 기반으로 사용하는 경우 xAPKS 배열에 확장 파일의 바이트 크기를 선언해야 합니다.

확장 파일 테스트

앱을 게시하기 전에 확장 파일 읽기와 파일 다운로드, 두 가지를 테스트해야 합니다.

파일 읽기 테스트

Google Play에 앱을 업로드하기 전에 앱이 공유 저장공간에서 파일을 읽는 기능을 테스트해야 합니다. 기기 공유 저장공간의 적절한 위치에 파일을 추가하고 앱을 실행하기만 하면 됩니다.

  1. 기기에서 Google Play가 파일을 저장할 공유 저장소에 적절한 디렉터리를 만듭니다.

    예를 들어 패키지 이름이 com.example.android이면 공유 저장공간에 Android/obb/com.example.android/ 디렉터리를 만들어야 합니다. (테스트 기기를 컴퓨터에 연결하여 공유 저장공간을 마운트하고 이 디렉터리를 수동으로 만듭니다.)

  2. 이 디렉터리에 확장 파일을 수동으로 추가합니다. 파일의 이름을 Google Play에서 사용할 파일 이름 형식과 일치하도록 바꿔야 합니다.

    예를 들어 파일 형식과 관계없이 com.example.android 앱의 기본 확장 파일은 main.0300110.com.example.android.obb여야 합니다. 원하는 값을 버전 코드로 사용할 수 있습니다. 다음 사항을 기억하세요.

    • 기본 확장 파일은 항상 main으로 시작하고 패치 파일은 patch로 시작합니다.
    • 패키지 이름은 항상 Google Play에서 파일이 첨부된 APK의 이름과 일치합니다.
  3. 이제 확장 파일이 기기에 추가되었으므로 앱을 설치하고 실행하여 확장 파일을 테스트할 수 있습니다.

다음은 확장 파일을 처리할 때 기억해야 할 사항입니다.

  • .obb 확장 파일을 삭제하거나 이름을 바꾸지 않습니다(데이터를 다른 위치에 압축해제하는 경우에도). 삭제하거나 이름을 바꾸면 Google Play(또는 앱 자체)에서 반복적으로 확장 파일을 다운로드합니다.
  • obb/ 디렉터리에 다른 데이터를 저장하지 않습니다. 일부 데이터를 압축해제해야 하는 경우 getExternalFilesDir()에 의해 지정된 위치에 데이터를 저장하세요.

파일 다운로드 테스트

앱이 처음 열릴 때 수동으로 확장 파일을 다운로드해야 하는 경우가 있으므로 이 프로세스를 테스트하여 앱에서 URL을 쿼리하고, 파일을 다운로드하여 기기에 저장할 수 있는지 확인하는 것이 중요합니다.

앱의 수동 다운로드 절차 구현을 테스트하려면 승인된 테스터만 사용할 수 있도록 앱을 내부 테스트 트랙에 게시하세요. 모든 것이 예상대로 작동하면 기본 활동이 시작하는 즉시 앱에서 확장 파일을 다운로드하기 시작합니다.

참고: 전에는 게시되지 않은 '초안' 버전을 업로드하여 앱을 테스트할 수 있었습니다. 이 기능은 더 이상 지원되지 않습니다. 대신 내부의 비공개 또는 공개 테스트 트랙에 앱을 게시해야 합니다. 자세한 내용은 초안 앱이 더 이상 지원되지 않음을 참조하세요.

앱 업데이트

Google Play에서 확장 파일을 사용하는 경우 큰 이점 중 하나는 원래 저작물을 모두 다시 다운로드하지 않고도 앱을 업데이트할 수 있는 기능입니다. Google Play에서는 각 APK에 확장 파일 두 개를 제공할 수 있으므로 두 번째 파일을 업데이트 및 새로운 저작물을 제공하는 '패치'로 사용할 수 있습니다. 이렇게 하면 용량이 크고 사용자 입장에서 비용이 많이 드는 기본 확장 파일을 다시 다운로드할 필요가 없습니다.

패치 확장 파일은 기술적으로 기본 확장 파일과 동일하며 Android 시스템과 Google Play는 모두 기본 확장 파일과 패치 확장 파일 사이에 실제 패칭을 실행하지 않습니다. 앱 코드에서 직접 필요한 패치를 실행해야 합니다.

ZIP 파일을 확장 파일로 사용하는 경우 APK 확장 패키지에 포함된 APK 확장 Zip 라이브러리에 패치 파일을 기본 확장 파일과 병합하는 기능이 포함됩니다.

참고: 패치 확장 파일만 변경해야 하는 경우에도 APK를 업데이트해야 Google Play에서 업데이트를 실행할 수 있습니다. 앱에서 코드를 변경할 필요가 없는 경우 매니페스트에서 versionCode를 업데이트하면 됩니다.

Play Console에서 APK와 연결된 기본 확장 파일을 변경하지 않는 한 이전에 앱을 설치한 사용자는 기본 확장 파일을 다운로드하지 않게 됩니다. 기존 사용자는 업데이트된 APK와 새 패치 확장 파일만 수신합니다(이전의 기본 확장 파일은 유지됩니다).

다음은 확장 파일의 업데이트와 관련하여 기억해야 할 사항입니다.

  • 앱의 확장 파일은 한 번에 두 개만 있을 수 있습니다. 기본 확장 파일 1개와 패치 확장 파일 1개입니다. 파일을 업데이트하는 동안 Google Play에서 이전 버전을 삭제하며 따라서 수동 업데이트를 실행할 때 앱을 삭제해야 합니다.
  • 패치 확장 파일을 추가할 때 Android 시스템에서 앱이나 기본 확장 파일을 실제로 패치하지 않습니다. 패치 데이터를 지원하도록 앱을 설계해야 합니다. 하지만 APK 확장 패키지에는 ZIP 파일을 확장 파일로 사용하기 위한 라이브러리가 포함되며 이 라이브러리가 패치 파일의 데이터를 기본 확장 파일에 병합하므로 모든 확장 파일 데이터를 쉽게 읽을 수 있습니다.