업적 통합

이 문서에서는 Google Play Console 또는 API 호출을 사용하여 게임에 업적을 통합하는 방법을 설명합니다. 업적의 필수 요소와 상태를 다루고 업적을 만들고 가져오고 관리하는 방법을 설명합니다.

시작하기 전에

새 업적 만들기 또는 가져오기

업적을 처음부터 구현하려면 다음 단계를 따르세요.

업적 추가

Google Play Console을 사용하여 처음으로 업적을 만드는 방법에는 두 가지가 있습니다.

  • 업적 만들기: 각 업적의 정의와 메타데이터를 한 번에 하나씩 추가합니다.
  • 업적 가져오기: 한 번에 여러 업적의 정의 및 기타 메타데이터를 함께 가져옵니다.

업적 만들기

게시되지 않은 새 게임의 업적을 만들려면 다음 단계를 완료하세요.

  1. Google Play Console에서 게임을 선택합니다.
  2. Play 게임즈 서비스 - 업적 페이지(성장 > Play 게임즈 서비스 > 설정 및 관리 > 업적)에서 업적 만들기를 선택합니다.
  3. 업적 추가 페이지에서 양식을 작성합니다.
  4. 초안으로 저장을 클릭합니다.
  5. 업적을 만든 후에는 업적을 게시해야 합니다.
업적 가져오기

게임에 여러 업적을 한 번에 추가하려면 다음 단계를 따르세요.

  1. 업적이 포함된 ZIP 파일을 만듭니다.
  2. 파일을 업로드합니다.

ZIP 파일에 관한 자세한 내용은 ZIP 파일 가이드라인을 참고하세요.

업적을 가져오려면 다음 단계를 따르세요.

  1. Google Play Console에서 게임을 선택합니다.
  2. Play 게임즈 서비스 - 업적 페이지(성장 > Play 게임즈 서비스 > 설정 및 관리 > 업적)에서 업적 가져오기를 선택합니다.
  3. 업적 가져오기 페이지에서 업로드를 클릭합니다.
  4. 업로드할 ZIP 파일을 선택합니다.
  5. 초안으로 저장을 클릭합니다.
  6. 업적을 가져온 후에는 게임을 게시해야 합니다.

ZIP 파일 가이드라인

ZIP 파일을 사용하여 여러 업적을 한 번에 가져올 수 있습니다. ZIP 파일에 사용할 정확한 파일 이름은 표를 참고하세요.

파일 이름 필수 또는 선택사항 허용되는 값
AchievementsMetadata.csv 필수 각 업적의 메타데이터입니다. 속성을 참고하세요.
AchievementsLocalizations.csv 선택사항 업적 이름 및 설명의 번역을 제공합니다.
AchievementsIconMappings.csv 선택사항 업적을 아이콘 파일에 매핑합니다.
아이콘 파일 선택사항 PNG, JPEG 또는 JPG 형식의 아이콘입니다.

ZIP 파일 요구사항:

  • 하위 디렉터리가 없습니다.
  • 고유한 파일 이름이 있습니다.
  • CSV, PNG, JPEG 또는 JPG 파일만 사용할 수 있습니다.
  • CSV 파일에 헤더 행이 없어야 합니다.
  • 각 파일의 크기는 1MB 미만이어야 합니다.
  • ZIP 파일에는 203개 이상의 파일이 포함되어서는 안 됩니다.
  • 총 ZIP 파일 크기는 200MB 미만이어야 합니다.
AchievementsMetadata.csv 형식

AchievementsMetadata.csv 파일에는 각 업적의 메타데이터가 포함되어 있습니다. 다음 순서로 쉼표로 구분된 값으로 정보를 포함해야 합니다.

    Name,Description,Incremental value,Steps Needed,Initial State,Points,List Order

이러한 필드는 다음 표에 설명되어 있습니다.

CSV 열 헤더 필수 또는 선택사항 허용되는 값
이름 필수 최대 100자(영문 기준)
설명 선택사항 최대 500자(영문 기준)
증분 값 선택사항 True 또는 False
필요한 단계 수 Incremental ValueTrue.인 경우 필수 숫자(분수 또는 소수점 없음)
초기 상태 필수 Hidden 또는 Revealed
포인트 필수 5의 배수이며 값은 5~200 사이여야 함
목록 순서 선택사항 숫자(소수점 또는 분수가 없음, 0보다 큼)

AchievementsMetadata.csv 파일 요구사항:

  • 각 행에는 7개의 값이 있어야 합니다. 값을 생략하려면 비워 둡니다.
  • NameDescription 필드는 기본 언어로 사용됩니다.
  • Name 필드는 모든 업적에서 고유해야 합니다.
  • NameDescription 필드에는 쉼표가 포함되어서는 안 됩니다.

샘플 AchievementsMetadata.csv 파일:

  Achievement1,Achievement One,True,100,Hidden,5,20
  Achievement2,Achievement Two,False,,Revealed,10,30
AchievementsLocalizations.csv 형식

AchievementsLocalizations.csv 파일은 각 업적을 여러 언어의 사용자에게 설명하는 데 필요한 모든 데이터를 설정하는 선택적 파일입니다. 업적은 게임에 지정된 언어에 따라 번역됩니다.

다음 순서로 쉼표로 구분된 값으로 정보를 포함해야 합니다.

   Name, Localized name, Localized description, locale

이러한 필드는 다음 표에 설명되어 있습니다.

CSV 열 헤더 필수 또는 선택사항 설명 허용되는 값
이름 필수 AchievementsMetadata.csvName 열과 일치해야 합니다. 최대 100자(영문 기준)
현지화된 이름 필수 업적의 현지화된 이름입니다. 최대 100자(영문 기준)
현지화된 설명 선택사항 지정된 언어로 현지화된 업적 설명입니다. 최대 500자(영문 기준)
언어 필수 언어 코드(예: en-US) 언어를 지정하기 전에 게임에 번역을 추가합니다. 기본 언어는 지정할 수 없습니다.

지원되는 언어 코드는 지원되는 언어 목록에서 확인할 수 있습니다.

AchievementsLocalizations.csv 파일 요구사항:

  • 게임 내 업적 이름은 언어별로 고유해야 합니다.

    예를 들어 게임에서 en-US 및 fr-FR 언어를 모두 지원하는 경우 en-US의 'Achievement1'이라는 업적 이름은 fr-FR에서도 'Achievement1'로 지정할 수 있습니다.

  • 각 행에는 4개의 값이 있어야 합니다. 현지화된 설명 값을 생략하려면 비워 둡니다.

샘플 AchievementsLocalizations.csv 파일:

Achievement1,Achievement One,This is the description of achievement one in English.,en-US
Achievement1,Achievement Un,Voici la description de l'achievement un en français.,fr-FR
Achievement2,Achievement Two,Description of achievement two.,en-US
Achievement2,Logro Dos,Descripción del logro dos.,es-ES
Achievement3,Achievement Three,,en-US
Achievement3,Erfolg Drei,,de-DE
AchievementsIconMappings.csv 형식

AchievementsIconMappings.csv 파일은 업적을 지정된 아이콘에 매핑하는 데 사용되는 선택적 파일입니다. 다음 순서로 쉼표로 구분된 값으로 정보를 포함해야 합니다.

Name, icon filename

이러한 필드는 다음 표에 설명되어 있습니다.

CSV 열 헤더 필수 또는 선택사항 설명
이름 필수 AchievementsMetadata.csvName 열과 일치해야 합니다.
아이콘 파일 이름 필수 아이콘 파일의 이름입니다.

AchievementsIconMappings.csv 파일 요구사항:

  • 각 행에는 두 개의 값이 있어야 합니다.
  • 아이콘 파일은 PNG 또는 JPEG 형식만 사용할 수 있습니다.

샘플 AchievementsIconMappings.csv 파일:

Valid Achievement,valid-achievement-icon.png
Incremental Achievement,incremental-achievement-icon.jpeg
No Description,no-description-icon.png
Hidden Initial State,hidden-initial-state-icon.png
Large Point Value,large-point-value-icon.jpeg

아이콘 가이드라인

아이콘은 512x512 PNG, JPEG 또는 JPG 파일로 만들어야 합니다. 달성한 업적의 아이콘만 제공하면 됩니다. 공개된 아이콘의 그레이 스케일 버전이 자동으로 생성됩니다. 따라서 업적 아이콘에 다채로운 요소를 포함하여 사용자가 공개 업적과 달성 업적을 구별할 수 있도록 하는 것이 좋습니다.

업적 아이콘이 Android [토스트][a]에 표시되면 아이콘이 동그라미와 겹쳐지면서 바깥쪽 모서리가 숨겨집니다. 이러한 상황에서도 아이콘이 보기 좋게 표시되는지 확인하세요.

샘플 업적 아이콘
샘플 업적 아이콘

모든 언어에서 동일한 아이콘이 사용되므로 아이콘에 텍스트나 현지화된 콘텐츠를 포함하지 않는 것이 좋습니다.

아이콘 파일

AchievementsIconMappings.csv 파일에서 참조하는 아이콘은 현재 가져온 ZIP 파일에 있어야 합니다.

기존 업적이 있는 게임 업데이트

Google Play Console에서 게임에 업적을 추가하고 기존 업적을 업데이트할 수 있습니다.

업적 추가

기존 업적이 있고 더 추가하려면 다음 단계를 따르세요.

  1. Google Play Console에서 게임을 선택합니다.
  2. Play 게임즈 서비스 - 업적 페이지(성장 > Play 게임즈 서비스 > 설정 및 관리 > 업적)에서 업적 추가를 선택합니다.
업적 수정

기존 업적이 있고 수정하려면 다음 단계를 따르세요.

  1. Google Play Console에서 게임을 선택합니다.
  2. Play 게임즈 서비스 - 업적 페이지(성장 > Play 게임즈 서비스 > 설정 및 관리 > 업적)에서 업적을 선택합니다.
  3. 필드를 수정할 수 있습니다.
  4. 초안으로 저장을 클릭합니다.
  5. Play 게임즈 서비스 - 업적 페이지에서 수정된 업적은 '테스터에게 제공됨' 상태입니다.
  6. 업적을 테스트한 후 검토 및 게시를 클릭합니다.

    이렇게 하면 업데이트된 모든 업적과 함께 게임이 다시 게시됩니다.

업적 삭제

게시된 업적은 삭제할 수 없습니다. 사전 게시된 상태의 업적만 삭제할 수 있습니다.

  1. Play 게임즈 서비스 - 업적 페이지에서 업적을 선택합니다.
  2. 업적을 삭제하려면 업적 삭제를 클릭합니다.
업적 재설정

초안 업적의 플레이어 진행 상황 데이터만 재설정할 수 있습니다.

  1. Play 게임즈 서비스 - 업적 페이지에서 업적을 선택합니다.
  2. 업적을 재설정하려면 진행 상황 재설정을 클릭합니다.
  3. 프로그래매틱 방식으로 업적 데이터를 재설정하려면 Management API Achievements 메서드를 호출하세요.

업적에 관한 번역 추가

게임과 연결된 업적에 관한 자체 번역을 지정할 수 있습니다. 이렇게 하려면 먼저 게임에 번역 추가에 설명된 단계를 완료해야 합니다.

게임에 번역을 추가하는 방법에는 두 가지가 있습니다.

  • 업적 가져오기 옵션을 사용하여 여러 개의 새로운 업적 번역을 한 번에 업로드할 수 있습니다. 이미 존재하는 업적의 번역을 업로드하는 데는 이 옵션을 사용할 수 없습니다.

  • 게임의 각 업적에 번역을 추가할 수 있습니다. 각 업적에 나만의 번역을 추가하려면 다음 단계를 따르세요.

    1. Google Play Console에서 게임의 업적 탭을 열고 기존 업적을 선택합니다.
    2. 업적 세부정보 페이지에서 이전에 게임 세부정보 탭에 추가한 언어의 탭을 선택합니다.
    3. 해당 언어의 업적 세부정보 페이지에서 해당 업적의 번역으로 양식을 수정합니다.
    4. 저장을 클릭하여 번역된 업적 세부정보를 저장합니다.

클라이언트 구현

플랫폼의 업적을 구현하는 방법은 다음 리소스를 참고하세요.

업적 테스트

업적이 의도한 대로 작동하는지 확인하려면 다음 단계에 따라 테스트하세요.

  • 내부 테스트 트랙을 설정합니다.
  • 테스터를 위해 게임 프로젝트에 테스트 계정을 추가합니다.
  • Play 게임즈 앱을 사용하여 테스트 계정 중 하나의 Play 게임즈 서비스 프로필을 만듭니다.
  • Play 게임즈 서비스 프로필을 만든 것과 동일한 테스트 계정을 사용하여 게임을 엽니다.
  • 게임 실행 시 자동 인증이 성공했음을 확인하는 Play 게임즈 서비스 '환영 토스트'가 화면에 표시되는지 확인합니다.
  • 게임을 플레이하고 필요한 단계를 완료하여 업적을 달성합니다.
  • 업적을 확인하려면 다음 단계를 따르세요.

    • 업적이 완료되면 화면에 '업적 달성' 팝업이 표시되는지 확인합니다.

    • Play 스토어 앱을 열고 내 페이지의 업적 섹션에 완료된 업적과 진행 중인 업적이 진행률 세부정보와 함께 표시되는지 확인합니다.

Play Console에서 업적 실적 추적하기

개별 업적에 대한 간단한 통계를 확인하는 방법은 다음과 같습니다.

  • Google Play Console
  • 설정> 게임 프로젝트로 이동합니다.
  • 게임을 선택합니다.
  • 왼쪽 메뉴에서 업적을 클릭합니다.
  • 업적 페이지에서 플레이어가 업적을 달성하는지 여부를 파악할 수 있는 통계를 확인할 수 있습니다. 업적을 숨기지 않은 사용자의 경우 업적을 달성한 비율을 확인할 수 있습니다. 초기 단계 업적의 경우 잠금 해제 비율이 일반적으로 100%에 가깝습니다.

성장 > Play 게임즈 서비스 > 게임 통계 페이지에서 업적의 시계열 실적을 추적할 수도 있습니다.

업적 게시

테스트를 완료한 후에는 게임을 게시해야 합니다. 게임의 모든 업적이 함께 게시됩니다. 업적을 게시하는 것은 업적이 제대로 작동하는 데 필요한 단계입니다.

게시하려면 다음 단계를 따르세요.

  1. Google Play Console에서 게임을 선택합니다.
  2. Play 게임즈 서비스 - 업적 페이지(성장 > Play 게임즈 서비스 > 설정 및 관리 > 업적)에서 검토 및 게시를 클릭합니다.
  3. Play 게임즈 서비스 - 게시 페이지(성장 > Play 게임즈 서비스 > 설정 및 관리 > 게시)에서 작업을 검토하고 문제를 해결합니다.
  4. 게시를 클릭합니다.

    게임의 모든 업적이 게시됩니다.

피해야 할 일반적인 실수

이러한 사항은 게임에서 업적을 구현할 때 피해야 할 일반적인 실수를 강조합니다. 이들은 다음의 중요성을 강조합니다.

  • Play Console에서 성장 > Play 게임즈 서비스 > 설정 및 관리 > 업적으로 이동합니다.

    • 게시하기 전에 Play Console에서 구성된 업적이 '초안' 상태가 아닌지 확인하세요.
    • Play Console의 업적 ID 값을 게임 코드에 추가하지 마세요. 대신 클라이언트 구현을 사용하세요.
  • 클라이언트에서 잠금 해제 로직도 구현했는지 확인합니다.

    • 플레이어는 잠금 해제 API가 호출되는 트리거 단계를 건너뛸 수 없습니다. 예를 들어 튜토리얼을 완료하는 것은 업적이지만 플레이어는 튜토리얼 자체를 건너뛸 수 있습니다.