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

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

다음과 같은 서버 간 기능이 있습니다.

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

시작하기 전에

시작하기 전에 다음이 있어야 합니다.

1. Google Cloud 프로젝트에 대한 관리 액세스 권한
2. 다음 사항에 대한 기본적인 이해
   • RESTful API
   • APK 구조
   • Android 앱 서명
   • SHA-256 다이제스트 생성

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

용어	정의
개발자 계정	하나 이상의 패키지 이름을 소유할 수 있는 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 계정이 없는 경우 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에서 애플리케이션이 초기 액세스 토큰 및 사용 기간이 긴 갱신 토큰으로 교환하는 승인 코드를 반환합니다. 백그라운드 실행: 배포 환경 또는 Secret Manager (예: 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는 인증 문자열을 제공합니다. 이 인증 문자열은 앱의 assets 폴더 내에 있는 adi-registration.properties라는 새 파일 내에 포함되어야 합니다. 그런 다음 등록하려는 공개 키에 해당하는 비공개 키를 사용하여 APK에 서명하고 업로드해야 합니다.

키 등록 근거

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

사용자 환경 권장사항

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

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

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

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

• 제목: 'Android Developer Console 계정 연결'
• 요약: '[애플리케이션 이름] 내에서 Android 개발자 인증을 위한 패키지 이름 등록 관리'
• 작업 버튼: 'Google로 계속' 또는 'Google 계정으로 로그인' 버튼

개발자 계정 식별

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

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

패키지 이름 관리

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

키 관리

1. ListAndroidPackageKeys API 엔드포인트를 호출하여 패키지 이름과 연결된 모든 키를 가져와 개발자에게 등록 상태를 모니터링할 수 있는 구조화된 개요 (예: 표 또는 목록)를 제공합니다.
2. 등록 상태 (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED_ACTIVE 또는 PENDING_TRANSFER)와 함께 모든 키의 certificateFingerprintSha256을 표시하고 상태를 구분하기 위해 고유한 시각적 표시기를 사용합니다.

1. CreateAndroidPackageKey API 메서드와 통합하여 개발자가 기존 패키지 이름으로 추가 키를 등록할 수 있도록 합니다.

패키지 이름 등록

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

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

키 소유권 확인

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

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

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

키 등록 근거

알려진 키의 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 ID 서비스 브랜딩 가이드라인을 준수하려면 승인 버튼에 'Google로 계속' 또는 'Google로 로그인' 작업 버튼을 사용해야 합니다. 이 텍스트는 사용자가 Google 사용자 인증 정보를 사용하여 애플리케이션이 Google 계정에 액세스하도록 승인하고 있음을 이해하도록 보장하므로 필수이며 수정할 수 없습니다.

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

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

• 로고 배치 및 계층 구조: 공식 승인된 Android Developer Console 로고만 사용하세요. 로고는 애플리케이션을 공식 Google 제품으로 잘못 표현하지 않도록 항상 자체 애플리케이션의 기본 브랜딩 요소에 종속되어야 합니다.

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

추가 리소스

• Android 개발자 ID 상태 API로 앱 등록 상태 확인
• Android Developer Console에 등록
• Google Play Console에 등록
• 앱 서명하기