Android Developer Console API로 패키지 이름 등록

Android Developer Console API는 앱 배포자와 개별 개발자가 Android Developer Console에서 프로그래매틱 방식으로 패키지 이름을 등록할 수 있도록 설계된 공개 인터페이스입니다.

다음과 같은 서버 간 기능:

앱 배포자 개인 개발자
스토어에 앱을 게시하는 개발자를 대신하여 패키지 이름-키를 등록합니다. 스토어 관리 키로 패키지 이름을 등록합니다. 패키지 이름과 연결된 키의 소유권을 증명합니다. 지속적 배포 워크플로의 핵심인 패키지 이름을 등록합니다. 패키지 이름과 연결된 키의 소유권을 증명합니다.

시작하기 전에

시작하기 전에 다음이 필요합니다.

  1. Google Cloud 프로젝트에 대한 관리 액세스 권한
  2. 다음에 관한 기본 이해:

다음 용어도 알고 있어야 합니다.

용어 정의
개발자 계정 하나 이상의 패키지 이름을 소유할 수 있는 Android Developer Console 계정을 나타냅니다. 여기에는 인증 상태 (NOT_VERIFIED 또는 VERIFIED)가 포함됩니다.
패키지 이름 개발자 계정 내의 특정 Android 패키지 이름 (예: com.example.app)으로, 하나 이상의 키와 연결할 수 있습니다. 등록 상태 (DRAFT, IN_REVIEW, REGISTERED 또는 PENDING_TRANSFER)를 포함합니다.
키 Android 패키지 이름에 서명하는 데 사용되는 특정 공개 인증서/키입니다. SHA-256 해시와 현재 등록 상태 (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED 또는 PENDING_TRANSFER)를 포함합니다.

시작하기

Android Developer Console API에 액세스하려면 다음 단계를 완료하세요.

Google Cloud 프로젝트 만들기

  1. 아직 계정이 없다면 Google Cloud 계정을 만듭니다.
  2. Google Cloud 콘솔을 엽니다. 
  3. Google Cloud 프로젝트를 만듭니다.

Google Cloud 프로젝트에서 API 사용 설정

  1. Google Cloud 콘솔을 엽니다. 
  2. 탐색 메뉴 (☰)에서 API 및 서비스 > 라이브러리를 선택합니다.
  3. 프로젝트 드롭다운 메뉴에서 API를 사용 설정할 Google Cloud 프로젝트를 선택합니다.
  4. API 및 서비스 검색창을 사용하여 Android Developer Console API를 선택합니다.
  5. API를 사용 설정합니다.
    1. 검색 결과에서 API를 선택하여 API의 개요 페이지로 이동합니다.
    2. 파란색 사용 설정 버튼을 클릭합니다. Google Cloud가 선택한 프로젝트에 API를 활성화합니다. 이 작업은 일반적으로 잠시 후에 완료됩니다. 사용 설정되면 사용을 시작할 수 있습니다.

API 인증

Android Developer Console API를 호출하려면 OAuth 2.0을 사용하여 요청을 인증해야 합니다.

OAuth 2.0으로 인증

Android Developer Console API는 개발자 계정 리소스 및 패키지 이름에 대한 액세스를 승인하기 위해 OAuth 2.0 인증이 필요합니다. 개발자 계정 데이터는 Google Cloud 프로젝트가 아닌 사용자의 Google 계정에 연결되므로 서비스 계정, 워크로드 아이덴티티 제휴, API 키를 사용하여 API 요청을 인증할 수 없습니다.

OAuth 2.0 범위

모든 작업에는 다음 범위가 필요합니다.

OAuth 2.0 범위 설명
https://www.googleapis.com/auth/androiddeveloperconsole Android Developer Console 계정에서 패키지 이름과 데이터 조회 및 관리

OAuth 2.0 웹 서버 흐름 구현

Android Developer Console API와 통합하려면 애플리케이션에서 OAuth 2.0 웹 서버 흐름을 사용해야 합니다. 애플리케이션 유형 및 자동화 요구사항에 따라 두 가지 기본 사용자 인증 정보 관리 전략 중에서 선택할 수 있습니다.

옵션 A (권장): 오프라인 / 자동 액세스 (CI/CD 및 서버 통합) 옵션 B: 임시 / 대화형 액세스
이 전략을 사용하면 자동화된 프로세스 (예:CI/CD 파이프라인)가 사람의 개입 없이 백그라운드에서 실행될 수 있습니다.

일회성 사용자 동의 설정: 초기 설정 중에 개발자 또는 계정 소유자가 브라우저에서 일회성 동의 절차를 완료합니다. 애플리케이션이 API 범위와 함께 오프라인 액세스 (access_type=offline)를 요청합니다. Google에서 승인 코드를 반환하면 애플리케이션은 이를 초기 액세스 토큰 및 장기 갱신 토큰으로 교환합니다.

백그라운드 실행: 배포 환경 또는 보안 비밀 관리자 (예: GitHub Actions Secrets, Google Secret Manager)에 refresh_token를 안전하게 저장합니다. 이후 API 호출의 경우 자동화된 워크플로에서 저장된 갱신 토큰을 사용하여 필요에 따라 새로운 단기 액세스 토큰을 가져오므로 수동 로그인 또는 2단계 인증 프롬프트를 우회할 수 있습니다. 		환경에 장기 갱신 토큰을 저장하지 않으려는 경우 또는 애플리케이션이 대화형 사용자 컨텍스트에서 실행되는 경우:

실행 시 프롬프트: 오프라인 액세스를 요청하거나 갱신 토큰을 저장하지 않습니다. 도구 또는 애플리케이션이 실행될 때마다 사용자를 브라우저의 Google OAuth 동의 페이지로 리디렉션하여 인증하라는 메시지를 표시합니다.

단기 액세스: 사용자가 로그인하고 동의하면 애플리케이션이 단기 액세스 토큰을 직접 (또는 승인 코드 교환을 사용하여) 수신합니다. 이 액세스 토큰은 API 호출을 수행하는 데 사용되며 실행 후 삭제됩니다. 향후 실행 시 사용자가 다시 인증해야 합니다.

패키지 이름 등록

패키지 이름 등록은 키를 패키지 이름에 연결하는 프로세스입니다. 키 등록 방법은 Android에서 새 패키지 이름에 키를 등록하는지 아니면 기존 패키지 이름에 키를 등록하는지에 따라 다릅니다.

새 패키지 이름 등록

Android에서 사용된 적이 없는 새 패키지 이름의 경우 앱의 서명 키 쌍에서 공개키 인증서를 제공할 수 있습니다.

기존 패키지 이름 등록

기존 패키지 이름을 등록하려면 알려진 비공개 서명 키의 소유권을 증명해야 합니다. 신규 등록과 달리 API는 등록할 수 있는 알려진 공개 인증서 지문 목록을 반환합니다. 이러한 키는 직접 등록에 사용할 수 있습니다.

등록하려는 키가 '근거 필요'로 표시된 경우에도 등록할 수 있지만, 소유권 증명을 완료하는 것 외에도 개발자는 패키지 이름을 사용하는 근거를 제출해야 합니다.

주요 자격 요건

자격 요건을 충족하는 키 목록은 패키지 이름 공유를 최소화하도록 설계된 패키지 이름 등록 요건 규칙에 따라 결정됩니다 (Android 개발자 인증의 일환으로 도입됨).

패키지 이름을 여러 개발자가 사용하거나 서명 키가 여러 개인 시나리오에서는 자격 요건이 다음과 같이 결정됩니다.

시나리오 직접 등록 규칙 다른 개발자를 위한 규칙
다수 키 보유자 알려진 총 설치 수의 50%를 초과하는 키가 우선순위를 차지합니다. 그 외 개발자는 타당한 이유를 제공해야 합니다.
50회 초과 설치 총 설치 수의 50%를 초과하는 단일 키가 없는 경우 설치 수가 50회 이상인 모든 키가 자격 요건을 충족합니다. 설치 수가 50회 미만인 키를 보유한 개발자는 근거를 제공해야 합니다.
설치 수 50회 미만 설치 수가 50회 이상인 키가 없는 경우 모든 키를 선착순으로 등록할 수 있습니다. 한 개발자가 등록하면 다른 개발자는 사유를 제공해야 합니다.

키 소유권 확인

기존 패키지 이름의 인증을 완료하기 위해 API는 인증 문자열을 제공합니다. 이 인증 문자열은 앱의 애셋 폴더 내에 있는 adi-registration.properties라는 새 파일에 포함되어야 합니다. 그런 다음 등록하는 공개 키에 해당하는 비공개 키를 사용하여 APK에 서명하고 업로드해야 합니다.

키 등록 정당화

키 등록에 근거가 필요한 경우 개발자는 자세한 비즈니스 근거를 제출해야 합니다. Google에서 이 사유를 검토하며 패키지 이름 등록 승인에는 최대 24시간이 걸릴 수 있습니다.

사용자 환경 권장사항

Android Developer Console API를 사용하는 애플리케이션은 원활한 통합을 위해 이러한 패턴을 따르는 것이 좋습니다.

명확한 OAuth 승인 컨텍스트 설정

OAuth 승인을 요청하기 전에 명시적인 컨텍스트를 제공하면 개발자가 계정 액세스가 필요한 이유를 이해하는 데 도움이 됩니다. 사용자를 효과적으로 안내하려면 OAuth 동의 화면을 실행하기 전에 예상되는 기능에 대한 명확한 설명을 제공하세요.

다음 형식을 사용하여 승인 컨텍스트를 구성합니다.

  • 제목: 'Android Developer Console 계정 연결'
  • 요약: '[application-name] 내에서 Android 개발자 인증을 위한 패키지 이름 등록 관리'
  • 작업 버튼: 'Google 계정으로 계속' 또는 'Google 계정으로 로그인' 버튼
계정 연결을 위한 OAuth 승인 컨텍스트를 보여주는 대화상자
그림 1. Android Developer Console 계정을 연결합니다.

개발자 계정 식별

  1. ListDeveloperAccounts API 메서드와 통합하여 액세스가 승인된 모든 개발자 계정을 검색하고 나열합니다.
  2. 개발자가 원하는 개발자 계정을 선택할 수 있도록 계정 선택 도구를 제공합니다.
  3. name 필드의 계좌 번호를 보조 정보로 사용하여 계좌 displayName를 눈에 띄게 표시합니다.
  4. 계정 인증 상태 (verificationState)를 표시합니다.
    • VERIFIED: 긍정적인 시각적 단서 (예: 녹색 체크표시)를 사용하여 확인된 개발자 ID를 확인합니다.
    • NOT_VERIFIED: 인증이 완료되지 않았음을 나타내고 계정의 패키지 등록을 제한합니다. 원하는 경우 계정을 선택할 때 개발자를 Android Developer Console로 안내하는 기본 CTA 버튼을 제공합니다.
개발자 계정 이름과 인증 상태를 보여주는 계정 선택 도구
그림 2. 개발자 계정 및 인증 상태를 표시하는 계정 선택 도구

Google 계정과 연결된 개발자 계정이 없어 빈 응답이 수신되면 기본 CTA 버튼을 사용하여 개발자를 Android Developer Console로 안내합니다.

패키지 이름 관리

  1. ListAndroidPackages API 엔드포인트와 통합하여 개발자 계정과 연결된 모든 패키지 이름을 가져옵니다. 개발자에게 목록이나 표와 같은 중앙 집중식 인터페이스를 제공하여 패키지 상태를 효과적으로 모니터링할 수 있도록 합니다.
  2. packageName를 현재 등록 상태(DRAFT, IN_REVIEW, REGISTERED 또는 PENDING_TRANSFER)와 함께 표시하고 각 상태에 고유한 시각적 표시기를 적용합니다. 생성 중에 '친숙한 이름'이 제공되고 저장된 경우 선택적으로 디스플레이에 포함할 수 있습니다.
등록된 패키지 이름과 상태를 표시하는 인터페이스
그림 3. 패키지 이름 및 등록 상태를 관리하는 인터페이스입니다.

키 관리

  1. ListAndroidPackageKeys API 엔드포인트를 호출하여 패키지 이름에 연결된 모든 키를 가져옵니다. 그러면 개발자에게 등록 상태를 모니터링할 수 있는 구조화된 개요 (예: 표 또는 목록)가 제공됩니다.
  2. 각 키의 certificateFingerprintSha256를 등록 상태 (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED_ACTIVE, PENDING_TRANSFER)와 함께 표시하고, 고유한 시각적 표시기를 사용하여 상태를 구분합니다.
인증서 지문 및 키 등록 상태 목록입니다.
그림 4. 키 및 등록 상태 개요
  1. CreateAndroidPackageKey API 메서드와 통합하여 개발자가 기존 패키지 이름으로 추가 키를 등록할 수 있도록 합니다.

패키지 이름 등록

  1. 개발자가 텍스트 입력란에 패키지 이름을 입력하는 양식 기반 레이아웃을 사용합니다. 단, 이 정보가 애플리케이션에서 아직 수집되지 않은 경우 (예: 이전 프롬프트를 통해)에만 해당합니다.
  2. CreateAndroidPackage API 메서드를 호출하여 개발자 계정에 패키지 이름을 등록하고 GetAndroidPackageRegistrationPolicy API 메서드를 호출하여 적용 가능한 키 자격 요건 규칙을 확인합니다.
  3. 패키지 이름에 지정된 keySelectionStrategy에 따라 개발자에게 다음 중 하나를 수행하라는 메시지를 표시합니다.
    • keySelectionStrategy가 SELECT_KEY_FROM_LIST로 설정된 경우: 개발자가 제공된 knownKeys 목록(SHA-256 인증서 지문 포함)에서 등록할 키를 선택하도록 합니다(예: 라디오 버튼 사용). 이 흐름에는 키 소유권 확인이 필요합니다 (아래의 키 소유권 확인 참고).
    • keySelectionStrategyUSE_ANY_KEY 이 경우 키 소유권 확인은 필요하지 않습니다.
  4. CreateAndroidPackageKey API 메서드를 호출하여 선택한 키를 새 패키지 이름과 연결합니다.
패키지 이름을 등록하고 서명 키를 선택하는 양식
그림 5. 패키지 이름을 등록하고 키를 선택하는 흐름

또는 애플리케이션이 업로드된 앱에서 패키지 이름이나 키를 자동으로 감지하고 추출할 수 있습니다.

키 소유권 확인

keySelectionStrategy가 SELECT_KEY_FROM_LIST로 설정된 경우 개발자는 비공개 서명 키의 소유권을 증명해야 합니다. 소유권을 증명하려면 API에서 생성된 verificationToken를 통합하는 서명된 APK를 제출해야 합니다.

키 소유권 확인을 지원하려면 VerifyAndroidPackageKeyOwnership API 메서드를 통합하고 다음 사용자 인터페이스 구성요소를 빌드합니다.

  • 토큰 표시 구성요소: 코드 스니펫 블록 내에 verificationToken를 눈에 띄게 표시하고 편리한 '클립보드에 복사' 버튼을 포함합니다.
  • 개발자 설정 안내: 개발자에게 verificationToken가 포함된 adi-registration.properties 파일을 앱의 애셋 폴더에 배치하도록 안내하는 자세한 안내를 제공합니다.
  • APK 제출 드롭 영역: 서명된 APK를 수신할 수 있는 전용 파일 업로드 드롭 영역을 제공합니다.
키 소유권 확인을 위한 드롭 영역 및 토큰 표시
그림 6. 서명된 APK 업로드로 키 소유권을 확인하는 UI 구성요소입니다.

키 등록 근거 제시

알려진 키의 justificationRequired 필드가 REQUIRED로 설정된 경우, 패키지 이름과 함께 해당 키를 등록하려면 개발자가 철저한 비즈니스 근거를 제출해야 합니다.

JustifyAndroidPackageKeyRegistration API 메서드를 호출하여 이 근거를 제출합니다. 애플리케이션의 사용자 인터페이스에 개발자의 근거를 수집하는 전용 텍스트 입력 영역이 있어야 하며, 키 등록 요청을 제출하기 전에 근거를 제공해야 한다고 개발자에게 알려야 합니다. Google은 제출된 근거를 검토하며, 이 과정은 패키지 이름 등록이 완료되기 전에 승인하는 데 최대 24시간이 걸릴 수 있습니다.

관리 키의 키 확인 자동화

애플리케이션에서 개발자의 서명 키를 관리하는 경우 개발자는 소유권 확인을 위해 APK에 수동으로 서명할 수 없습니다. 대신 사용자를 대신하여 VerifyAndroidPackageKeyOwnership API 호출을 자동으로 실행해야 합니다.

토큰 포함 및 APK 업로드 프로세스를 자동으로 처리하면 애플리케이션에서 이러한 수동 단계를 삭제할 수 있습니다. 시스템에 저장된 키를 사용하여 애플리케이션에서 키 소유권 확인을 원활하게 관리한다는 사실을 개발자에게 알리세요.

브랜드 가이드라인 준수

사용자 신뢰를 유지하고 투명성을 보장하기 위해 Android Developer Console API와 통합되는 모든 애플리케이션은 다음 브랜드 가이드라인을 준수해야 합니다.

용어 및 대문자 사용

사용자 대상 자료 또는 문서에서 제품을 언급할 때는 항상 전체 이름인 Android Developer Console을 사용하세요. 'ADC'라는 약어를 사용하지 마세요.

이 프로그램은 Android 개발자 인증이라고 지칭해야 합니다. 모든 문맥에서 이 대소문자 및 철자를 정확하게 따르세요.

APK 또는 AAB와의 모호성을 방지하려면 '패키지'가 아닌 '패키지 이름'이라는 용어를 구체적으로 사용하세요.

패키지 이름을 추가하는 프로세스를 설명할 때는 '패키지 이름 소유권 주장' 대신 '패키지 이름 등록'이라는 문구를 사용합니다.

'로그인' 클릭 유도 문구 사용

Android Developer Console을 사용한 OAuth 2.0 인증은 Google ID 서비스를 사용합니다. Google 아이덴티티 서비스 브랜드 가이드라인을 준수하려면 승인 버튼에 'Google 계정으로 계속' 또는 'Google 계정으로 로그인' 클릭 유도 문구를 사용해야 합니다. 이 텍스트는 사용자가 자신의 Google 사용자 인증 정보를 사용하여 애플리케이션이 자신의 Google 계정에 액세스하도록 승인한다는 것을 이해할 수 있도록 하기 위한 것이므로 필수이며 수정할 수 없습니다.

브랜드 아이덴티티 및 무결성 유지

Android Developer Console 로고를 애플리케이션 인터페이스에 통합할 때는 시각적 정체성과 브랜드 무결성을 유지하기 위해 다음 사양을 따라야 합니다.

  • 로고 배치 및 계층 구조: 공식적으로 승인된 Android Developer Console 로고만 사용하세요. 애플리케이션이 공식 Google 제품으로 오인되지 않도록 로고는 항상 애플리케이션의 기본 브랜딩 요소보다 부차적인 요소로 유지되어야 합니다.
공식 Android Developer Console 로고 파일을 저장하려면 클릭합니다.
그림 7. 공식 Android Developer Console 로고 이미지를 클릭하여 파일을 저장합니다.
  • 시각적 스타일 및 왜곡: 애셋은 항상 가로세로 비율이 완전히 제한된 상태로 렌더링되어야 합니다. 로고의 구성요소를 왜곡, 확장, 비틀기, 자르기, 뒤집기 또는 수정해서는 안 됩니다. 공식 색상 팔레트를 변경하거나, 전경색 또는 배경색을 바꾸거나, 그림자, 발광 효과, 장식용 그라데이션을 적용하지 마세요.
  • 사용 제한: Google 소유의 브랜딩 요소를 자체 애플리케이션 애셋에 통합하지 마세요. Android Developer Console 로고 애셋은 활성 통합을 명시적으로 나타내기 위해 애플리케이션 레이아웃 컨텍스트 내에서만 사용할 수 있습니다.

추가 리소스