업적 인터페이스

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

목차

업적 인터페이스(Achievements Interface) 를 통해 개발자는 플레이어의 에픽 온라인 서비스 업적 데이터를 얻고, 플레이어의 업적을 잠금해제하고, 애플리케이션에 속한 모든 에픽 온라인 서비스 업적 데이터를 얻을 수 있습니다.

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

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

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

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

에픽 온라인 서비스 업적 데이터를 얻거나 수동으로 잠금해제하려면, 먼저 개발자 포털(Developer Portal) 에서 에픽 온라인 서비스 업적을 정의해야 합니다.

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

  • 최신 집계 타입을 사용하는 통계는 계속 생성할 수 있습니다.

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

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

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

EOS_Achievements_DefinitionV2

파라미터

설명

ApiVersion

EOS_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)'을 사용하고 설명에는 빈 스트링을 사용합니다. 하지만 이 구조 안에서 LockedDisplayName 및 LockedDescription 의 값은 변함이 없습니다.

StatThresholdsCount

이 업적의 진행상황을 모니터링할 때 사용하는 통계 한계치의 개수입니다.

StatThresholds

해당 에픽 온라인 서비스 업적을 잠금해제하기 위해 충족해야 하는 EOS_Achievements_StatThresholds 배열입니다. 이름(Name)과 한계치(Threshold Value)로 구성됩니다.

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

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

에픽 온라인 서비스 업적 데이터를 얻거나 수동으로 잠금해제하려면, 먼저 개발자 포털(Developer Portal) 에서 에픽 온라인 서비스 업적을 정의해야 합니다.

쿼리가 완료되면 에픽 온라인 서비스 업적 정의가 함수를 통해 반환되는 것이 아니라 로컬에 캐시됩니다. 그런 다음에는 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 구조입니다.

ClientData

CompletionDelegate 에서 나에게 다시 전달되는 임의의 데이터입니다.

CompletionDelegate

작업 완료 시 호출되는 함수로, EOS_Achievements_OnQueryDefinitionsCompleteCallback 과 일치하는 서명을 사용합니다.

EOS_Achievements_QueryDefinitionsOptions

ApiVersion

EOS_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

ApiVersion

EOS_ACHIEVEMENTS_COPYDEFINITIONV2BYINDEX_API_LATEST

AchievementIndex

캐시에서 구하려는 업적 정의 인덱스입니다.

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

ID로 업적 정의 복사하기

EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId 함수는 지정된 AchievementId 와 일치하는 업적을 업적 캐시에서 검색한 다음, 출력 파라미터 OutDefinition 을 통해 그 데이터 사본을 출력합니다. 이 함수는 다음과 같은 파라미터를 받습니다.

EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId

파라미터

설명

Handle

유효한 EOS_HAchievements 핸들입니다.

Options

캐시를 검색할 업적 ID가 포함된 EOS_Achievements_CopyAchievementDefinitionV2ByAchievementIdOptions 구조입니다.

OutDefinition

요청된 EOS_Achievements_DefinitionV2 의 사본이 포함된 출력 파라미터입니다. OutDefinition 에 유효한 데이터가 있으면, 이 데이터에 EOS_Achievements_DefinitionV2_Release 를 호출하여 데이터를 메모리에서 릴리즈해야 합니다.

CopyAchievementDefinitionV2ByAchievementIdOptions

ApiVersion

EOS_ACHIEVEMENTS_COPYDEFINITIONV2BYACHIEVEMENTID_API_LATEST 로 설정합니다.

AchievementId

캐시에서 정의를 복사할 때 찾아볼 업적 ID입니다.

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

복사한 업적 정의에서 메모리 릴리즈하기

EOS_Achievements_CopyAchievementDefinitionV2ByIndex 또는 EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId 의 OutDefinition 으로 복사된 정보는 EOS_Achievements_DefinitionV2_Release 함수를 사용하여 메모리에서 릴리즈되어야 합니다. 이 함수는 AchievementDefinition 이라고 하는 단일 EOS_Achievements_DefinitionV2 에 대한 포인터를 받습니다.

플레이어 업적 진행상황 데이터

플레이어 업적 진행상황 데이터는 EOS_Achievements_PlayerAchievement 라고 하는 구조에 포함되어 있습니다. EOS_Achievements_AchievementDefinition 에는 백엔드의 에픽 온라인 서비스 업적에 대한 일반 정보가 포함되어 있지만, EOS_Achievements_PlayerAchievement 는 특정 플레이어의 에픽 온라인 서비스 업적 잠금해제 진행상황, 잠금해제 시간(이미 잠금해제한 경우), 잠금해제 관련 통계 정보를 추적합니다. EOS_Achievements_PlayerAchievement 의 파라미터는 다음과 같습니다.

EOS_Achievements_PlayerAchievement

파라미터

설명

ApiVersion

EOS_ACHIEVEMENTS_PLAYERACHIEVEMENT_API_LATEST 로 설정합니다.

AchievementId

업적 식별에 사용되는 고유 식별자입니다.

Progress

이 업적을 완료하기까지의 진행상황을 백분율로 표시합니다.

UnlockTime

업적이 잠금해제된 POSIX 타임 스탬프입니다. 업적이 잠금해제되지 않은 경우, 이 값은 EOS_ACHIEVEMENTS_ACHIEVEMENT_UNLOCKTIME_UNDEFINED입니다.

StatInfoCount

이 업적과 관련된 플레이어 통계 정보 항목의 수입니다.

StatInfo

업적 잠금해제에 사용된 통계 한계치와 플레이어의 이러한 통계의 현재 값에 대한 정보가 포함된 EOS_Achievements_PlayerStatInfo 구조 배열입니다.

DisplayName

EOS_Achievements_QueryPlayerAchievements

Description

EOS_Achievements_QueryPlayerAchievements

IconURL

EOS_Achievements_QueryPlayerAchievements

FlavorText

게임에서 임의로 사용할 수 있는 현지화된 플레이버 텍스트입니다. 개발자 포털에 구성된 데이터가 없으면 이 값은 null일 수 있습니다.

EOS_Achievements_PlayerStatInfo

ApiVersion

EOS_ACHIEVEMENTS_PLAYERSTATINFO_API_LATEST 로 설정합니다.

Name

통계 이름입니다.

CurrentValue

현재 통계 값입니다.

ThresholdValue

통계의 한계치 값입니다.

플레이어 통계에 대한 자세한 정보는 통계 인터페이스(Stats Interface) 페이지를 참조하세요.

플레이어 업적 진행상황 쿼리하기

에픽 온라인 서비스 업적 데이터를 얻거나 수동으로 잠금해제하려면, 먼저 개발자 포털(Developer Portal) 에서 에픽 온라인 서비스 업적을 정의해야 합니다.

비동기 함수인 EOS_Achievements_QueryPlayerAchievements 를 사용하여 플레이어의 업적 진행상황 데이터를 얻을 수 있습니다. 쿼리가 완료되면 요청 데이터가 로컬로 캐시된 목록에 저장됩니다. 그런 다음, EOS_Achievements_CopyPlayerAchievementByIndex 또는 EOS_Achievements_CopyPlayerAchievementByAchievementId 를 통해 데이터에 액세스하여 원하는 데이터의 사본을 얻을 수 있습니다. 이 작업이 완료되면, EOS_Achievements_PlayerAchievement_Release 를 호출하여 복사한 정보를 메모리에서 릴리즈해야 합니다.

EOS_Achievements_QueryPlayerAchievements 의 파라미터는 다음과 같습니다.

EOS_Achievements_QueryPlayerAchievements

파라미터

설명

Handle

유효한 EOS_HAchievements 핸들입니다.

Options

정보를 쿼리하는 타깃 플레이어의 UserId 가 포함된 EOS_Achievements_QueryPlayerAchievementsOptions 구조입니다.

ClientData

CompletionDelegate 에서 나에게 다시 전달되는 임의의 데이터입니다.

CompletionDelegate

작업 완료 시 호출되는 함수로, EOS_Achievements_OnQueryPlayerAchievementsCompleteCallback 과 일치하는 서명을 사용합니다.

EOS_Achievements_QueryPlayerAchievementsOptions

ApiVersion

EOS_ACHIEVEMENTS_QUERYPLAYERACHIEVEMENTS_API_LATEST 로 설정합니다.

UserId

업적 진행상황 데이터를 구할 타깃 사용자의 계정 ID입니다.

쿼리 플레이어 업적 완료 콜백

EOS_Achievements_OnQueryPlayerAchievementsCompleteCallback 콜백 함수는 쿼리 플레이어 업적(Query Player Achievements) 작업이 완료되면 호출되며, EOS_Achievements_OnQueryPlayerAchievementsCompleteCallbackInfo 구조를 반환합니다. 콜백 정보에는 ResultCode , EOS_Achievements_QueryDefinitionsOptions 에 설정된 모든 클라이언트 데이터, 데이터를 소유한 플레이어의 사용자 ID가 포함됩니다.

플레이어 업적 진행상황 복사하기

플레이어 업적 데이터는 로컬에 캐시됩니다. EOS_Achievements_GetPlayerAchievementCount 를 사용하면 캐시된 에픽 온라인 서비스 업적의 개수를 얻을 수 있습니다.

EOS_Achievements_CopyPlayerAchievementByIndex 함수와 EOS_Achievements_CopyPlayerAchievementByAchievementId 함수를 사용하여 EOS_Achievements_PlayerAchievement 의 사본을 획득할 수 있습니다. EOS_Achievements_PlayerAchievement_Release 를 사용하여 이 사본 데이터와 관련된 메모리를 릴리즈해야 합니다.

인덱스로 플레이어 업적 복사하기

EOS_Achievements_CopyPlayerAchievementByIndex 함수는 캐시된 업적 목록 내의 인덱스 값을 사용하여 로컬 캐시에서 EOS_Achievements_PlayerAchievement 구조 사본을 얻은 다음, 출력 파라미터인 OutAchievement 를 통해 사본을 출력합니다. 이 함수는 다음과 같은 파라미터를 받습니다.

EOS_Achievements_CopyPlayerAchievementByIndex

파라미터

설명

Handle

유효한 EOS_HAchievements 핸들입니다.

Options

캐시에서 복사할 요청 인덱스가 포함된 EOS_Achievements_CopyPlayerAchievementByIndexOptions 구조입니다.

OutAchievement

요청한 EOS_Achievements_PlayerAchievement 사본이 포함된 출력 파라미터입니다. OutAchievement 에 유효한 데이터가 있으면, 이 데이터에 EOS_Achievements_PlayerAchievement_Release 를 호출하여 데이터를 메모리에서 릴리즈해야 합니다.

EOS_Achievements_CopyPlayerAchievementByIndexOptions

ApiVersion

EOS_ACHIEVEMENTS_COPYPLAYERACHIEVEMENTBYINDEX_API_LATEST 로 설정합니다.

UserId

업적을 복사하는 사용자의 계정 ID를 나타내는 유효한 EOS_ProductUserId 입니다.

AchievementIndex

캐시에서 구하려는 플레이어 업적 데이터의 인덱스입니다.

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

ID별로 플레이어 업적 복사하기

EOS_Achievements_CopyPlayerAchievementByAchievementId 함수는 지정된 AchievementId 와 일치하는 업적을 로컬 플레이어 업적 캐시에서 검색한 다음, 출력 파라미터 OutAchievement 를 통해 그 데이터 사본을 출력합니다. 이 함수는 다음과 같은 파라미터를 받습니다.

EOS_Achievements_CopyPlayerAchievementByAchievementId

파라미터

설명

Handle

유효한 EOS_HAchievements 핸들입니다.

Options

캐시를 검색할 업적 ID가 포함된 EOS_Achievements_CopyPlayerAchievementByAchievementIdOptions 구조입니다.

OutAchievement

요청한 EOS_Achievements_PlayerAchievement 사본이 포함된 출력 파라미터입니다. OutAchievement 에 유효한 데이터가 있으면, 이 데이터에 EOS_Achievements_PlayerAchievement_Release 를 호출하여 데이터를 메모리에서 릴리즈해야 합니다.

EOS_Achievements_CopyPlayerAchievementByAchievementIdOptions

ApiVersion

EOS_ACHIEVEMENTS_COPYPLAYERACHIEVEMENTBYACHIEVEMENTID_API_LATEST 로 설정합니다.

UserId

업적을 복사하는 사용자의 계정 ID를 나타내는 유효한 EOS_ProductUserId 입니다.

AchievementId

캐시에서 정의를 복사할 때 찾아볼 업적 ID입니다.

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

복사한 플레이어 업적에서 메모리 릴리즈하기

EOS_Achievements_CopyPlayerAchievementByIndex 또는 EOS_Achievements_CopyPlayerAchievementByAchievementId 의 OutAchievement 로 복사된 정보는 EOS_Achievements_PlayerAchievement_Release 함수를 사용하여 메모리에서 릴리즈되어야 합니다. 이 함수는 Achievement 라고 하는 단일 EOS_Achievements_PlayerAchievement 에 대한 포인터를 받습니다.

에픽 온라인 서비스 업적 잠금해제하기

에픽 온라인 서비스 업적은 업적과 연결된 통계(stats) 가 수집되면 자동으로 잠금해제할 수도 있고 EOS_Achievements_UnlockAchievements 함수를 호출하여 수동으로 잠금해제할 수도 있습니다.

통계를 통해 에픽 온라인 서비스 업적 잠금해제하기

에픽 온라인 서비스 업적은 통계 한계치 세트로 정의되며, 이러한 세트는 통계 이름과 에픽 업적을 잠금해제하기 위해 도달해야 하는 통계 양으로 구성됩니다. 필수 한계치가 모두 충족되면 업적이 잠금해제되며 진행상황(Progress) 이 1.0으로 설정됩니다.

통계 수집 작업으로 통계를 업데이트 하는 자세한 방법은 통계 인터페이스 페이지를 확인하세요.

수동으로 에픽 온라인 서비스 업적 잠금해제하기

EOS_Achievements_UnlockAchievements 함수는 사용자의 에픽 온라인 서비스 업적을 하나 이상 잠금해제할 수 있습니다. 이 함수의 파라미터는 다음과 같습니다.

EOS_Achievements_UnlockAchievements

파라미터

설명

Handle

유효한 EOS_HAchievements 핸들입니다.

Options

잠금해제할 에픽 온라인 서비스 업적과 그 타깃 플레이어에 대한 정보가 포함된 EOS_Achievements_UnlockAchievementsOptions 구조입니다.

ClientData

CompletionDelegate 에서 나에게 다시 전달되는 임의의 데이터입니다.

CompletionDelegate

작업 완료 시 호출되는 함수로, EOS_Achievements_OnUnlockAchievementsCompleteCallback 과 일치하는 서명을 사용합니다.

EOS_Achievements_UnlockAchievementsOptions

ApiVersion

EOS_ACHIEVEMENTS_UNLOCKACHIEVEMENTS_API_LATEST 로 설정합니다.

UserId

잠금해제할 업적을 가진 사용자 계정 ID를 나타내는 EOS_ProductUserId 입니다.

AchievementIds

잠금해제할 업적 ID의 목록입니다.

AchievementsCount

잠금해제할 업적의 개수입니다.

EOS_Achievements_OnUnlockAchievementsCompleteCallback 콜백 함수는 EOS_Achievements_UnlockAchievements 작업이 완료되면 실행됩니다. 이 함수는 작업에서 데이터를 반환하는 작업을 담당합니다. 그 파라미터는 다음과 같습니다.

EOS_Achievements_OnUnlockAchievementsCompleteCallback

파라미터

설명

ResultCode

작업 상태를 나타내는 EOS_EResult 입니다. 결과가 EOS_Success 이면 작업에 성공했다는 뜻입니다. 다른 모든 결과는 오류를 나타냅니다.

ClientData

EOS_Achievements_UnlockAchievements 에 전달된 컨텍스트입니다.

UserId

이 요청을 개시한 사용자의 계정 ID를 나타내는 EOS_ProductUserId 입니다.

AchievementsCount

잠금해제할 업적 개수입니다.

SDK는 업적 상태를 로컬이나 오프라인으로 저장하지 않습니다. 서비스 중단 시 통계 서비스가 에픽 온라인 서비스 업적 잠금해제를 백업하지 않는 문제를 완화하려면 다음 수단을 고려해 보세요.

  1. 항상 로그인할 때 사용자 업적 상태를 다운로드합니다.

  2. 잠금해제 상태를 백업 통계/데이터와 비교하고 조건이 일치하면 업적을 잠금해제합니다.

이 프로세스는 업데이트 때 도입된 새 에픽 온라인 서비스 업적을 완료했을 수 있는 사용자에게도 적용됩니다.

EOS_Achievements_UnlockAchievements 를 여러 번 호출해도 되고, 매번 실행할 때마다 호출해도 괜찮습니다. 다만, 적절한 재시도율은 꼭 준수해야 하며 다시 시도하기 전에 완료 상태가 반환되기를 기다려야 합니다.

에픽 온라인 서비스 업적 알림

에픽 온라인 서비스 업적이 잠금해제되면 알려주는 알림(Notifications) 을 사용할 수 있습니다. 업적 알림은 통계를 수집하거나 수동으로 업적을 잠금해제함으로써 트리거될 수 있습니다.

EOS_Achievements_AddNotifyAchievementsUnlockedV2 함수는 에픽 온라인 서비스 업적이 잠금해제되면 알려주는 알림을 구독할 수 있습니다. EOS_Achievements_AddNotifyAchievementsUnlockedV2Options 구조 및 EOS_Achievements_OnAchievementsUnlockedCallbackV2 와 서명이 일치하는 함수에 대한 레퍼런스를 사용하여 옵션(Options) 파라미터를 받습니다. 업적이 잠금해제될 때마다 해당 콜백 함수가 호출됩니다. ClientData 를 사용하면 콜백에 임의의 컨텍스트 데이터를 전달할 수 있습니다.

EOS_Achievements_AddNotifyAchievementsUnlockedV2Options 구조에는 ApiVersion 이 포함되며 이 ApiVersion 은 EOS_ACHIEVEMENTS_ADDNOTIFYACHIEVEMENTSUNLOCKEDV2_API_LATEST 로 설정되어야 합니다.

EOS_Achievements_OnAchievementsUnlockedCallbackV2 콜백 함수는 EOS_Achievements_OnAchievementsUnlockedCallbackV2Info 구조를 반환합니다. 이 콜백 정보는 잠금해제된 업적의 AchievementId 및 UnlockTime 을 포함합니다. 여기에는 EOS_Achievements_AddNotifyAchievementsUnlockedV2 를 통해 전달된 ClientData 와 에픽 온라인 서비스 업적을 가진 사용자의 UserId 도 포함됩니다.

RemoveNotifyAchievementsUnlocked 를 사용하면 알림 구독을 해지할 수 있습니다.

사용 제한

업적 인터페이스를 통해 개발자는 플레이어의 에픽 온라인 서비스 업적 데이터를 얻고, 플레이어의 에픽 온라인 서비스 업적을 잠금해제하고, 애플리케이션에 속한 모든 에픽 온라인 서비스 업적 데이터를 얻을 수 있습니다. 스로틀링, 할당량 사용, 최선의 방법에 대한 일반 정보를 보려면 서비스 사용 제한(Service Usage Limitations)을 참조하세요.

디플로이에서 에픽 온라인 서비스 업적을 사용할 때 전체적으로 다음과 같은 제한이 적용됩니다.

기능

제한

총 업적 수

1,000

업적당 통계 수

3

업적 ID 길이

256글자

업적당 현지화 텍스트 베리에이션

19

현지화 텍스트 길이

256글자

업적 아이콘 파일 크기

1.02MB

업적 아이콘 해상도

1024x1024픽셀

업적 아이콘 파일 유형

PNG, JPG, BMP, GIF(애니메이션 없음)

에픽 온라인 서비스 업적을 정의할 때 EOS_Achievements_DefinitionV2 의 AchievementId 파라미터에 다음 기호를 사용할 수 없습니다.

, { ^ } % ` ] > [ ~ < # | & $ @ = ; : + ? ! \ ( ) * /

이 기호들은 정의를 임포트/익스포트할 때 문제를 일으킬 수 있습니다.

사용자 또는 디플로이별로 적용되는 사용률 제한도 있습니다. 사용자별 제한은 게임을 플레이하고 기존 업적과 상호작용하는 개별 사용자에 적용되며, 디플로이별 제한은 플레이어가 보고 잠금해제할 수 있는 업적을 구성하는 호출에 적용됩니다.

기능

사용자별 제한

디플로이별 제한

모든 업적 정의 가져오기

분당 요청 10회

한 업적 정의 가져오기

분당 요청 100회

한 플레이어의 업적 가져오기

분당 요청 100회

업적 잠금해제

분당 요청 100회

업적 생성

분당 요청 100회

업적 삭제

분당 요청 100회

에픽 온라인 서비스 업적 테스트

디플로이의 에픽 온라인 서비스 업적을 테스트 샌드박스 중 한 곳에서 테스트할 수 있습니다. 업적을 라이브 환경에 디플로이하기 전에 테스트를 진행하여 업적 정의 시 발생할 수 있는 오류를 점검하고, 플레이어가 에픽 온라인 서비스 업적을 성공적으로 잠금해제하도록 해야 합니다. 제품의 테스트 샌드박스 생성에 관한 정보는 제품, 샌드박스, 디플로이 ID를 참조하세요.