클라이언트 업데이트

클라이언트 업데이트 확인 메서드로 현재 앱 버전에 업데이트가 필요한지 확인합니다.

1. Hive 콘솔에서 클라이언트 업데이트 설정

클라이언트 업데이트를 사용하려면 먼저 콘솔에 업데이트 항목을 등록하세요. Hive 콘솔 > 서비스 접근 제어 > 서비스 접근 제어에서 프로젝트를 선택하고 검색을 누른 뒤 새 서비스 접근 제어에서 유형을 클라이언트 업데이트로 고릅니다. 등록 화면의 입력 항목은 서비스 접근 제어 항목을 참조하세요. 등록하기 전에 App ID와 앱 지원 언어를 준비하세요. 준비 방법은 App ID와 앱 메타 정보를 참조하세요.

2. 호출 파라미터값 준비

호출 전에 업데이트 필요 여부를 판단할 ClientVersion과 허용 목록 적용 여부를 확인할 PlayerId를 준비합니다.

ClientVersion

ClientVersion은 현재 실행 중인 앱 클라이언트 버전입니다. 서버는 이 값을 콘솔에 등록한 대상 버전과 비교해 업데이트 필요 여부를 판단합니다.

서버는 버전 범위나 표기 차이를 해석하지 않고 문자열이 정확히 같은지만 비교합니다. 예를 들어 1.2와 1.2.0은 서로 다른 버전으로 봅니다. 콘솔에 등록한 버전 표기 그대로 전달하세요. 빈 문자열이나 공백 문자가 들어간 값은 전달할 수 없습니다.

PlayerId

PlayerId는 사용자가 허용 목록에 등록된 대상인지 확인할 때 사용하는 Player ID입니다. 서버가 요청을 처리할 때 허용 목록을 자동으로 적용하므로 앱에서 허용 목록을 따로 조회할 필요는 없습니다. 접속 IP나 PlayerId가 허용 목록에 있으면 적용 중인 업데이트 항목이 있어도 Data.UpdateRequired는 false입니다. 클라이언트 업데이트에서는 허용 목록 항목에 앱 버전을 지정했다면 요청의 ClientVersion이 그 버전과 같을 때만 해당 항목이 적용됩니다. 허용 목록에 일치하는 항목이 없으면 PlayerId는 결과에 영향을 주지 않습니다.

로그인 전에는 Player ID가 없으므로 생략하고, 로그인한 뒤 다시 확인할 때 지정합니다. 로그인한 사용자의 Player ID는 ISessionManager의 PlayerId로 확인합니다.

3. 클라이언트 업데이트 확인 메서드 호출

CheckClientUpdateAsync

CheckClientUpdateAsync()를 호출해 현재 앱 버전이 적용 중인 클라이언트 업데이트 항목의 대상인지 확인합니다. 업데이트가 필요하면 강제 업데이트 여부와 스토어 안내 URL을 함께 반환합니다. 앱은 이 결과에 따라 강제 또는 선택 업데이트를 처리하고 필요하면 스토어 이동을 구현합니다.

로그인 전에도 호출할 수 있습니다. 다만 부정 사용 가능성을 고려해 로그인한 뒤 PlayerId를 담아 호출하는 것을 권장합니다.

호출 파라미터

필드명	타입	필수 여부	설명
request	CheckClientUpdateRequest	Required	클라이언트 업데이트 조회 요청
context	ApiCallContext	Optional	호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

App ID와 안내 문구 언어는 모듈 설치 및 초기화에서 설정한 값을 SDK가 자동으로 전달하므로 요청에 따로 담지 않습니다.

CheckClientUpdateRequest

필드명	타입	필수 여부	설명
`ClientVersion`	string	Required	현재 앱 클라이언트 버전. 빈 문자열이나 공백 문자가 들어간 값은 지정할 수 없습니다.
`PlayerId`	long?	Optional	허용 목록 적용 여부를 확인할 Player ID. 로그인 전에는 생략합니다.

호출 예시

CheckClientUpdateAsync() 호출 예제에서는 Success, Failure, UnknownOutcome를 구분해 처리합니다. 공통 실패(Failure)의 결과 모델과 처리 원칙은 공통 오류 처리를 참조하세요.

Unity

using Hive.Axyl.ServiceAccess;
using Hive.Axyl.Core;

IServiceAccessService service = HiveCore.Resolve<IServiceAccessService>();

var request = new CheckClientUpdateRequest {
    ClientVersion = Application.version,  // 현재 앱 버전
    // PlayerId   = HiveCore.Resolve<ISessionManager>().PlayerId,  // 로그인한 뒤 호출할 때 지정
};

ServiceAccessCheckClientUpdateResult result = await service.CheckClientUpdateAsync(request);

switch (result)
{
    case ServiceAccessCheckClientUpdateResult.Success success:
        if (success.Data.UpdateRequired)
        {
            // 업데이트 필요. ForceUpdate면 강제, 아니면 선택 유도. RedirectUrl로 스토어 이동
            Debug.Log($"업데이트 필요(강제={success.Data.ForceUpdate}): {success.Data.RedirectUrl}");
        }
        else
        {
            // 업데이트 불필요 -> 정상 진행
        }
        break;

    // 공통 실패 처리 (네트워크·서버 오류, 요청 값 오류)
    case ServiceAccessCheckClientUpdateResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}/{err.ExternalCode}] {err.Message} (trace: {err.TraceId})");
        break;

    // 이 SDK 버전에서 정의하지 않은 결과와 서버 내부 오류(UnknownOutcome)는 실패로 처리합니다.
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 데이터

성공하면 ServiceAccessCheckClientUpdateResult.Success의 Data(CheckClientUpdateResponseData)에 결과가 담깁니다. Data.UpdateRequired가 true이면 업데이트 안내에 필요한 제목, 본문, 리다이렉트 URL, 대상 버전 목록을 함께 반환합니다. 현재 버전에 해당하는 업데이트 항목이 여러 개이면 가장 최근에 등록한 항목의 안내 문구와 대상 버전 목록을 반환합니다.

필드명	타입	필수 여부	설명
`Data.UpdateRequired`	bool	Required	업데이트 필요 여부
`Data.Id`	long?	Optional	적용된 클라이언트 업데이트 항목의 ID. 업데이트가 필요 없으면 `null`
`Data.ForceUpdate`	bool	Required	강제 업데이트 여부. `false`이면 선택 업데이트이며, 업데이트가 필요 없어도 `false`
`Data.Title`	string	Required	업데이트 안내 제목. 업데이트가 필요 없으면 빈 문자열
`Data.Content`	string	Required	업데이트 안내 본문. 업데이트가 필요 없으면 빈 문자열
`Data.RedirectUrl`	string	Required	스토어 등 업데이트 안내 URL. 콘솔에 설정하지 않았거나 업데이트가 필요 없으면 빈 문자열
`Data.Versions`	`IReadOnlyList<ClientUpdateVersion>`	Required	적용된 항목에서 요청한 App ID에 지정한 업데이트 대상 버전 목록. 업데이트가 필요 없으면 빈 목록. 항목 구조는 아래 `ClientUpdateVersion` 참고
`Data.AlwaysOn`	bool	Required	상시 적용 여부
`Data.StartAt`·`Data.EndAt`	DateTimeOffset?	Optional	업데이트 안내 적용 기간. 업데이트가 필요 없으면 둘 다 `null`이고, 시작 시각을 지정하지 않은 항목이면 `StartAt`이, 종료 시점이 없는 상시 적용이면 `EndAt`이 `null`
`Data.Timezone`	`TimeZoneInfoNullable`	Optional	`StartAt`과 `EndAt`을 해석하는 기준 시간대. 업데이트가 필요 없으면 `null`. 항목 구조는 아래 `TimeZoneInfoNullable` 참고

ClientUpdateVersion

필드명	타입	필수 여부	설명
`AppId`	string	Required	업데이트 대상 App ID
`ClientVersion`	string	Required	업데이트 대상 클라이언트 버전

TimeZoneInfoNullable

Data.Timezone은 Data.StartAt과 Data.EndAt을 해석하는 시간대 정보입니다. 서버는 접속 IP로 판별한 국가를 기준으로 시간대를 정하므로 앱에서 시간대 정보를 따로 전달할 필요는 없습니다. 국가를 판별할 수 없으면 UTC를 사용합니다. 업데이트가 필요 없어 적용할 항목이 없으면 Data.Timezone은 null입니다.

StartAt과 EndAt의 시차는 각 시각에 이 시간대에서 적용되는 값입니다. 따라서 두 시각 사이에 서머타임 전환이 있으면 두 시각의 시차가 서로 다릅니다. UtcOffset, OffsetSeconds, Dst는 StartAt을 기준으로 계산하며, StartAt이 null이면 EndAt을, 둘 다 null이면 현재 시각을 기준으로 계산합니다.

필드명	타입	필수 여부	설명
`Id`	string	Required	IANA 시간대 식별자. 예: `Asia/Seoul`
`UtcOffset`	string	Required	`±HH:MM` 형식의 UTC 기준 시차. 서머타임을 반영하며, 시차가 0이면 `+00:00`
`OffsetSeconds`	int	Required	초 단위의 UTC 기준 시차
`Dst`	bool	Required	서머타임 적용 여부
`IsInEuropeanUnion`	bool	Required	시간대를 정한 국가의 유럽 연합 소속 여부. UTC를 사용하면 `false`
`Name`	string	Optional	요청 언어로 표기한 국가 이름. 요청 언어 태그의 이름이 없으면 언어 부분만 남긴 태그, 영어, 제공되는 다른 언어 순으로 찾은 이름. 예를 들어 요청 언어가 `pt-BR`이면 `pt-BR`, `pt`, `en` 순. 국가 이름이 없거나 UTC를 사용하면 `null`
`Names`	`IReadOnlyDictionary<string, string>`	Required	언어 태그별 국가 이름. UTC를 사용하면 비어 있음

Warning

Data.UpdateRequired가 false이면 안내 제목, 본문, 리다이렉트 URL이 모두 빈 문자열이고 대상 버전 목록도 비어 있습니다. 안내 화면을 띄우기 전에 먼저 Data.UpdateRequired를 확인하세요. 실제 업데이트 유도와 진입 제한은 앱 클라이언트가 직접 구현해야 합니다.

응답 헤더

성공하면 ServiceAccessCheckClientUpdateResult.Success의 Headers(CheckClientUpdateResponseHeaders)에 응답 헤더 값이 담깁니다.

필드명	타입	필수 여부	설명
`Headers.XTraceId`	string	Optional	서버가 응답마다 발급하는 요청 추적 식별자. 문제를 문의하거나 로그를 조회할 때 사용합니다.

응답 예시