Achievements Interface

사용자별로 에픽 온라인 서비스 업적을 확인하고 잠금해제하는 인터페이스입니다.

17 분 소요

업적 인터페이스(Achievements Interface) 를 활용하여 다음 작업을 수행합니다.

  • 특정 플레이어의 업적 상태 데이터 가져오기
  • 호출을 통해 업적을 수동으로 잠금해제
  • 애플리케이션에 속한 모든 업적에 대한 데이터 가져오기

자세한 전체 내용은 API 레퍼런스 문서 EOS 업적 인터페이스 API 레퍼런스를 참조하세요.

업적 인터페이스에서 정의한 업적은 에픽 온라인 서비스 업적 이라고 합니다. 제품에서 사용하는 플랫폼이나 스토어프론트에 구애받지 않고 제품을 추가할 수 있습니다.

EOS SDK 버전 1.8부터 업적 아이콘의 처리 방식을 업데이트했습니다. 버전 1.7에서 1.8로 업데이트하면 특별한 문제는 없겠지만, 일부 아이콘이 기본 상태로 돌아갈 수도 있습니다. 이런 현상이 발생하면 테크니컬 어카운트 매니저에게 지원을 요청하세요.

에픽게임즈 스토어에 제품 을 퍼블리싱할 때 에픽게임즈 스토어 업적으로 제품의 사용자 경험을 향상할 수 있습니다. 에픽게임즈 스토어 업적은 에픽 온라인 서비스 업적에서 확장되어 에픽 플레이어 계정에서 누릴 수 있는 경험(XP)와 기타 혜택을 사용자에게 보상해 줍니다. 자세한 내용은 에픽게임즈 스토어 업적을 참조하세요.

업적 인터페이스에 액세스하기

업적 인터페이스에 액세스하려면 EOS_Platform_GetAchievementsInterface 함수를 호출하여 EOS_HAchievements 핸들을 획득해야 합니다. 다른 모든 인터페이스와 마찬가지로 EOS_HPlatform 핸들의 틱이 실행되고 있어야 요청 완료 시 적절한 콜백이 트리거될 수 있습니다.

에픽 온라인 서비스 업적 정의

에픽 온라인 서비스 업적을 정의할 때 더 이상 최신(LATEST) 집계 타입을 지원하지 않습니다. 이로 인한 영향은 다음과 같습니다.

  • 최신 집계 타입을 사용하는 통계는 계속 생성할 수 있습니다.
  • 하지만, 최신 집계 타입을 사용하는 통계를 참조하는 에픽 온라인 서비스 업적은 생성할 수 없습니다.
  • 최신 집계 타입을 사용하는 통계를 참조하는 에픽 온라인 서비스 업적이 이미 있는 경우 편집할 수는 있습니다.

에픽 온라인 서비스 업적 정의 데이터를 얻을 때 EOS_Achievements_DefinitionV2 구조에 포함되며, 다음과 같은 파라미터를 가집니다.

EOS_Achievements_DefinitionV2:

파라미터설명
ApiVersionEOS_ACHIEVEMENTS_DEFINITIONV2_API_LATEST
AchievementId업적을 고유하게 식별하는 데 사용되는 업적 ID입니다.
UnlockedDisplayName업적이 잠금해제되었을 때 나타나는 현지화된 업적 표시명입니다.
UnlockedDescription업적이 잠금해제되었을 때 나타나는 현지화된 업적 설명입니다.
LockedDisplayName업적이 잠겨 있을 때 나타나는 현지화된 업적 표시명입니다.
LockedDescription업적이 잠겨 있을 때 나타나는 현지화된 업적 설명입니다.
FlavorText게임에서 임의로 사용할 수 있는 현지화된 플레이버 텍스트입니다. 개발자 포털에 구성된 데이터가 없으면 이 값은 null일 수 있습니다.
UnlockedIconURL업적이 잠금해제되었을 때 나타나는 업적 아이콘의 URL입니다. 개발자 포털에 구성된 데이터가 없으면 이 값은 null이 되며, 소셜 오버레이에서 기본 이미지를 사용합니다.
LockedIconURL업적이 잠기거나 숨겨져 있을 때 나타나는 업적 아이콘의 URL입니다. 개발자 포털에 구성된 데이터가 없으면 이 값은 null이 되며, 소셜 오버레이에서 기본 이미지를 사용합니다.
bIsHidden업적이 숨겨진 상태면 EOS_TRUE , 그렇지 않으면 EOS_FALSE 입니다. EOS_TRUE 로 설정하는 경우, 소셜 오버레이는 업적이 잠겨 있는 동안 표시명으로 ‘숨겨진 업적(Hidden Achievement)’을 사용하고 설명에는 빈 스트링을 사용합니다. 하지만 이 구조 안에서 LockedDisplayNameLockedDescription 의 값은 변함이 없습니다.
StatThresholdsCount이 업적의 진행상황을 모니터링할 때 사용하는 통계 한계치의 개수입니다.
StatThresholds해당 에픽 온라인 서비스 업적을 잠금해제하기 위해 충족해야 하는 EOS_Achievements_StatThresholds 배열입니다. 이름(Name)과 한계치(Threshold Value)로 구성됩니다.

에픽 온라인 서비스 업적 정의 쿼리하기

EOS_Achievements_QueryDefinitions 함수를 사용하면 애플리케이션용으로 개발자 포털에 생성한 모든 에픽 온라인 서비스 업적 정의 배열을 얻을 수 있습니다.

쿼리가 완료되면 에픽 온라인 서비스 업적 정의가 함수를 통해 반환되는 것이 아니라 로컬에 캐시됩니다. 그런 다음에는 EOS_Achievements_CopyAchievementDefinitionV2ByIndex 또는 EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId 를 사용하여 업적 정의에 액세스하여 EOS_Achievements_DefinitionV2 의 사본을 얻을 수 있습니다. 이렇게 복사한 정의를 저장하려면 EOS_Achievements_DefinitionV2_Release 를 사용하여 메모리를 릴리즈해야 합니다. 에픽 온라인 서비스 업적 복사에 대한 자세한 내용은 아래 캐시된 업적 정의 복사하기 섹션에서 확인하세요.

EOS_Achievements_QueryDefinitions 는 다음과 같은 파라미터를 받습니다.

EOS_Achievements_QueryDefinitions

파라미터설명
Handle유효한 EOS_HAchievements 핸들입니다.
Options현지화된 텍스트 얻기와 관련된 데이터뿐만 아니라 반환할 데이터 종류에 대한 옵션도 포함하는 EOS_Achievements_QueryDefinitionsOptions 구조입니다.
ClientDataCompletionDelegate 에서 나에게 다시 전달되는 임의의 데이터입니다.
CompletionDelegate작업 완료 시 호출되는 함수로, EOS_Achievements_OnQueryDefinitionsCompleteCallback 과 일치하는 서명을 사용합니다.

EOS_Achievements_QueryDefinitionsOptions

파라미터설명
ApiVersionEOS_ACHIEVEMENTS_QUERYDEFINITIONS_API_LATEST 로 설정합니다.
LocalUserId정의를 쿼리하는 사용자의 제품 사용자 ID입니다.
EpicUserId폐기된 파라미터입니다. null로 설정되어야 합니다.
HiddenAchievementIds폐기된 파라미터입니다. null로 설정되어야 합니다.
HiddenAchievementsCount폐기된 파라미터입니다. 0으로 설정되어야 합니다.

쿼리에 성공하면 이 함수는 EOS_EResult 값을 EOS_Success 로 반환합니다. 다른 결과가 나오면 오류가 발생했거나 파라미터가 잘못됐다는 뜻입니다.

쿼리는 LocalUserId 를 사용하여 사용자의 로케일(locale) 을 결정하며, 이는 사용자에게 연동된 에픽 온라인 서비스 계정 ID가 있는 경우 현지화된 텍스트를 반환하는 데 사용됩니다 또한, EOS_Platform_SetOverrideLocaleCode 를 호출해서 사용자가 원하는 로케일을 사용하여 에픽 온라인 서비스 업적 정보를 얻도록 시스템에 강제할 수도 있습니다.

정의 쿼리 완료 콜백

정의 쿼리 작업이 완료되고 EOS_Achievements_OnQueryDefinitionsCompleteCallbackInfo 구조를 반환하면 EOS_Achievements_OnQueryDefinitionsCompleteCallback 콜백 함수가 호출됩니다. 콜백 정보에는 ClientData 파라미터를 사용하여 EOS_Achievements_QueryDefinitionsOptions 에 설정된 모든 클라이언트 데이터와 ResultCode 가 포함됩니다.

캐시된 에픽 온라인 서비스 업적 정의 복사하기

EOS_Achievements_QueryDefinitions 작업이 완료되면 에픽 온라인 서비스 업적 정의가 로컬에 캐시됩니다. 그런 다음에는 EOS_Achievements_CopyAchievementDefinitionV2ByIndex 또는 EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId 를 사용하여 EOS_Achievements_DefinitionV2 의 사본을 얻을 수 있습니다.

캐시된 에픽 온라인 서비스 업적 수 얻기

GetAchievementDefinitionCount 함수를 사용하여 이용할 수 있는 캐시된 에픽 온라인 서비스 업적 수를 얻을 수 있습니다. 이 함수는 개수를 정수로 반환하고 EOS_Achievements_GetAchievementDefinitionCountOptions 구조를 파라미터로 가져옵니다.

EOS_Achievements_GetAchievementDefinitionCountOptions 구조 자체는 ApiVersion 파라미터만 취하는데, 이는 EOS_ACHIEVEMENTS_GETACHIEVEMENTDEFINITIONCOUNT_API_LATEST 값으로 설정되어야 합니다.

인덱스로 에픽 온라인 서비스 업적 정의 복사하기

EOS_Achievements_CopyAchievementDefinitionV2ByIndex 함수는 캐시된 에픽 온라인 서비스 업적 목록 내의 인덱스 값을 사용하여 EOS_Achievements_DefinitionV2 사본을 얻은 다음, 출력 파라미터인 OutDefinition 을 통해 사본을 출력합니다. 이 함수는 다음과 같은 파라미터를 받습니다.

EOS_Achievements_CopyAchievementDefinitionV2ByIndex

파라미터설명
Handle유효한 EOS_HAchievements 핸들입니다.
Options캐시에서 복사할 요청 인덱스가 포함된 EOS_Achievements_CopyAchievementDefinitionV2ByIndexOptions 구조입니다.
OutDefinition요청된 EOS_Achievements_DefinitionV2 의 사본이 포함된 출력 파라미터입니다. OutDefinition 에 유효한 데이터가 있으면, 이 데이터에 EOS_Achievements_DefinitionV2_Release 를 호출하여 데이터를 메모리에서 릴리즈해야 합니다.

EOS_Achievements_CopyAchievementDefinitionV2ByIndexOptions

파라미터설명
ApiVersionEOS_ACHIEVEMENTS_COPYDEFINITIONV2BYINDEX_API_LATEST
AchievementIndex캐시에서 구하려는 업적 정의 인덱스입니다.

정보를 이용할 수 있고 OutDefinition 에서 출력을 전달한 경우, 함수는 EOS_EResult 값을 EOS_Success 로 반환합니다. 출력 파라미터에 대해 null 포인터를 전달하면 EOS_InvalidParameters 를 반환합니다. 요청된 업적 정의를 찾을 수 없으면 EOS_NotFound 를 반환합니다.

ID로 업적 정의 복사하기