App Store Review API 개발자 가이드

App Store Review API를 사용하면 Google Play의 서드 파티 앱 스토어 프로그램을 통해 Google Play에 등록된 서드 파티 앱 스토어가 스토어에 호스팅된 앱에 필요한 세부정보를 제공할 수 있습니다. 여기에는 앱 메타데이터, 등록정보, APK 바이너리, 정책 준수 선언이 포함됩니다.

엔드포인트, 메서드, 리소스 스키마의 전체 목록은 App Store Review API 참조를 참고하세요.

시작하기 전에

App Store Review API를 호출하려면 먼저 기본 시작 가이드를 완료하여 API 액세스, 서비스 사용자 인증 정보, Google Cloud 프로젝트를 설정해야 합니다. App Store Review API는 앱 스토어당 분당 최대 300개의 요청을 예상합니다.

API 설계 및 아키텍처

App Store Review API는 원자 스냅샷 패턴으로 작동합니다. 트랜잭션 세션을 사용하는 대신 파일을 개별적으로 업로드한 다음, 단일 원자 호출에서 전체 상태를 커밋합니다.

개별 파일과 애셋(APK, 이미지, 정책 파일)을 별도의 직접 호출로 업로드합니다.
반환된 ID를 해당 파일에 대해 캐시합니다.
호스팅된 앱 상태 전체를 원자적으로 커밋하기 위해 단일 최종 UpdateAppStoreHostedApp 요청을 제출합니다.

1. 등록

호스팅된 앱을 등록하려면 앱의 패키지 이름과 스토어의 패키지 이름을 지정하여 createappstorehostedapp 메서드를 호출합니다. 요청 및 응답 스키마에 대한 자세한 내용은 API 참조를 참고하세요.

2. 바이너리 및 애셋 업로드

호스팅된 앱이 등록되면 특수 업로드 엔드포인트를 사용하여 애셋을 업로드해야 합니다.

APK: uploadapk를 사용하여 적극적으로 배포되는 앱의 모든 APK 바이너리.
이미지: 앱 아이콘, 스크린샷과 같은 이미지 확장 소재 (uploadimage 사용).
정책: (관련된 경우) 정책 관련 문서(uploadappstoreapppolicydeclarationfile 사용).

애셋 캐싱 및 재사용

대역폭과 성능을 최적화하려면 동일한 애셋을 다시 업로드하지 마세요. 반환된 모든 apkId, imageId, fileId 토큰은 지속됩니다. 이러한 ID를 자체 백엔드 데이터베이스에 캐시한 다음 후속 호스팅된 앱 업데이트에서 재사용할 수 있습니다. 예를 들어 호스팅된 앱의 설명을 업데이트하되 앱 아이콘과 스크린샷은 변경하지 않은 상태로 유지할 경우, 다음 업데이트 호출에서 캐시된 imageId 토큰을 사용하세요.

3. 어셈블 및 커밋

모든 애셋을 업로드하고 각 ID를 가져온 후에는 호스팅된 앱 상태 전체를 어셈블하고 updateappstorehostedapp 메서드를 사용하여 이를 커밋해야 합니다. 이 메서드는 호스팅된 앱의 세부정보, 현지화된 스토어 등록정보, 활성 APK 세트, 안전 선언의 완전한 원자 표현을 허용합니다.

이 호출은 이전에 활성 상태였던 상태를 요청에 설명된 새 상태로 대체합니다.

요청 본문 예

다음은 모든 주요 요소를 보여주는 사실적이고 구문상 유효한 JSON 요청 본문입니다.

{
  "appStorePackageName": "com.example.thirdparty.store",
  "packageName": "com.example.hostedapp.game",
  "appDetails": {
    "developerName": "Adventure Games Studio Ltd.",
    "contactEmail": "support@adventuregames.example.com",
    "developerWebsite": "https://adventuregames.example.com"
  },
  "activeLocalizedStoreListings": [
    {
      "languageCode": "en-US",
      "appName": "Super Quest Legends",
      "shortDescription": "An epic fantasy RPG adventure.",
      "fullDescription": "Super Quest Legends is an immersive action RPG featuring real-time battles, customizable classes, and a deep fantasy narrative. Journey through a magical realm, fight epic bosses, and team up with friends in dungeon raids.",
      "appIconId": "987123",
      "screenshotId": [
        "102938",
        "475869",
        "384756"
      ],
      "videoLink": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    },
    {
      "languageCode": "es-ES",
      "appName": "Super Quest Leyendas",
      "shortDescription": "Una aventura épica de RPG fantástico.",
      "fullDescription": "Super Quest Leyendas es un RPG de acción inmersivo con batallas en tiempo real, clases personalizables y una profunda narrativa de fantasía. Viaja a través de un reino mágico, lucha contra jefes épicos y únete a amigos en incursiones.",
      "appIconId": "987123",
      "screenshotId": [
        "102938",
        "475869",
        "384756"
      ]
    }
  ],
  "activeApks": {
    "activeApkSets": [
      {
        "baseApkId": "554433"
      },
      {
        "baseApkId": "990011"
      }
    ]
  },
  "policyDeclarations": [
    {
      "declarationId": "POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT",
      "responses": [
        {
          "questionId": "POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS",
          "multipleChoiceResponse": {
            "values": [
              "POLICY_RESPONSE_CHOICE_ID_TAC_AGE_EIGHTEEN_AND_ABOVE"
            ]
          }
        },
        // ... other responses for TAC
      ]
    },
    {
      "declarationId": "POLICY_DECLARATION_ID_ADVERTISING_ID",
      "responses": [
        {
          "questionId": "POLICY_QUESTION_ID_AD_ID_IS_USED",
          "booleanResponse": {
            "value": false
          }
        }
        // ... other responses for AD_ID
      ]
    }
    // ... other declarations
  ]
}

정책 선언

API를 사용하여 앱 정보를 제출하거나 업데이트할 경우 필수 정책 선언을 포함해야 합니다.

선언 요구사항

다음 선언이 범위에 포함됩니다.

모든 앱에서 추가 선언이 필요한지 확인해야 합니다.

건강 앱: 건강 앱 정책에서 앱이 충족해야 하는 요구사항을 파악할 수 있도록 앱에서 사용하는 건강 기능을 알려주세요.
금융 기능: 금융 기능을 제공하는 앱은 일부 국가 또는 지역의 특정 규정을 준수해야 할 수 있습니다. 제출하신 항목을 적합한 팀이 검토할 수 있도록 앱의 금융 기능에 관한 정확한 최신 정보를 제출해 주세요.
광고 ID: 앱에서 광고 ID를 사용하는지 알려주세요.
테스트 사용자 인증 정보(로그인 세부정보): 로그인 세부정보, 멤버십, 위치 또는 다른 형태의 인증을 기반으로 했을 때 앱의 일부가 제한되는 경우 앱에 액세스할 방법을 알려주세요.
개인정보처리방침: 앱의 개인정보처리방침으로 연결되는 링크와 세부정보입니다.
타겟층 및 콘텐츠: 앱의 타겟 연령대 및 콘텐츠 관련 기타 정보를 제공해야 합니다. 이러한 정보는 아동을 대상으로 하는 앱이 안전하고 적절한지 확인하는 데 도움이 됩니다.
광고: 앱에 광고가 포함되어 있는지 알려주세요.

조건부 필수:

정부 앱: 모든 유형의 정부 기관에서 사용하는 용도의 앱인지 알려주세요. 여기에는 국가, 주, 시 정부, 지역 당국이 포함됩니다. 이를 알려주시면 제출하신 항목을 Google에서 적합한 팀이 검토하는 데 도움이 됩니다. 이 선언을 작성하지 않으면 앱이 정부 앱이 아닌 것으로 간주됩니다.
아동 안전 표준: '소셜' 또는 '데이트' 카테고리에 속하는 앱의 경우 필수입니다. 소셜 또는 데이트 카테고리의 앱은 Google의 아동 안전 표준 정책을 준수하기 위해 게시된 안전 표준 및 연락처 정보를 제공해야 합니다.
뉴스 및 잡지 앱: '뉴스 및 잡지' 카테고리에 속하는 앱의 경우 필수입니다. 앱을 운영하는 법인에 대한 투명성을 제공하기 위해 뉴스 및 잡지 앱에 관한 세부정보를 추가하세요.

API 요청 구조

정책 선언은 UpdateAppStoreHostedAppRequest 본문의 policyDeclarations 배열 내에 제공됩니다. 이 배열의 각 항목은 AppStoreAppPolicyDeclaration 객체입니다.

AppStoreAppPolicyDeclaration 객체:

declarationId(문자열, 필수): 정책 선언의 고유 식별자입니다(예: POLICY_DECLARATION_ID_FINANCE, POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT).
responses(PolicyResponse 배열, 필수): 해당 특정 선언 내 질문에 대한 답변 목록입니다.

PolicyResponse 객체:

questionId(문자열, 필수): 답변이 제공되는 특정 질문의 고유 식별자입니다(예: POLICY_QUESTION_ID_FINANCIAL_PRODUCT_TYPES, POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS).
value(필수): 답변 자체입니다. 다음 유형 중 하나일 수 있습니다.
- booleanResponse: 예/아니요 질문에 사용됩니다.
  - value(불리언)
- stringResponse: URL을 포함한 일반 텍스트 답변입니다.
  - value(문자열)
- singleChoiceResponse: 목록에서 한 가지 옵션만 선택할 수 있는 경우입니다.
  - value(문자열): 선택한 응답 항목의 ID입니다.
- multipleChoiceResponse: 여러 옵션을 선택할 수 있는 경우입니다.
  - values(문자열 배열): 선택한 응답 항목의 ID입니다.
- documentResponse: 문서 업로드가 필요한 질문에 사용됩니다. 문서 업로드 처리를 참고하세요.
- groupResponse: 반복되는 중첩 질문 세트에 사용됩니다.
- keyedGroupResponse: 특정 키로 그룹화된 중첩 질문 세트에 사용됩니다.

선언의 예시 스니펫은 상세 가이드를 참고하세요.

문서 업로드 처리

일부 정책 질문에는 증빙 서류(예: 금융 기능에 대한 라이선스)를 제공해야 합니다. 문서는 UpdateAppStoreHostedAppRequest에 직접 삽입할 수 없습니다. 그 대신 다음과 같이 해야 합니다.

문서 업로드: UploadAppStoreAppPolicyDeclarationFile 엔드포인트를 사용합니다. 이 요청은 미디어 업로드 요청입니다. fileType은 DECLARATION_FILE_TYPE_DOCUMENT로 설정해야 합니다.
- 엔드포인트: POST /androidpublisher/v3/appstore/{appStorePackageName}/apps/{packageName}/policyDeclarationFiles:upload
- 업로드 성공 응답에는 fileId가 포함됩니다.
문서 ID 참조: 문서 질문의 PolicyResponse에서 documentResponse 유형을 사용합니다. 업로드 단계에서 가져온 fileId로 documentId 필드를 채웁니다.

PolicyDocumentResponse 객체:

documentId(문자열, 필수): UploadAppStoreAppPolicyDeclarationFile 엔드포인트에서 반환된 ID입니다.
expiryDate(날짜, 선택사항): 해당하는 경우 문서의 만료일입니다.
nonExpiring(불리언, 선택사항): 문서가 만료되지 않는 경우 true로 설정합니다.

문서 응답 예시:

// Inside a PolicyResponse object
{
  "questionId": "POLICY_QUESTION_ID_FINANCE_CRYPTO_US_FINCEN_LICENSE", // Example ID
  "documentResponse": {
    "documentId": "123456789", // The fileId from upload
    "expiryDate": {
      "year": 2027,
      "month": 6,
      "day": 1
    }
  }
}

4. 사용 가능 여부 제어

UpdateAppStoreHostedApp을 사용하여 호스팅된 앱 상태를 커밋하면 앱이 자동으로 처리되며 서드 파티 앱 스토어의 경우 Google Play에서 기본적으로 게시됨으로 표시됩니다.

앱이 커밋된 후 앱의 사용 가능 여부를 제어하려면 updateappstorehostedapppublishstatus 메서드를 호출하여 상태를 업데이트하세요.

앱 게시 취소: 호스팅된 앱을 사용할 수 없는 상태로 설정하려면 publishState 필드를 APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED로 설정합니다.
앱 다시 게시: 등록정보를 수정하거나 애셋을 다시 업로드하지 않고 이전에 게시되지 않은 앱을 다시 사용할 수 있는 상태로 설정하려면 publishState 필드를 APP_STORE_APP_PUBLISH_STATE_PUBLISHED로 설정합니다.