IServiceAccessService

앱 접속 제한이나 안내 화면 표시에 필요한 정보를 Hive Axyl 서버에서 조회하는 서비스입니다. 적용 중인 서버 점검 조회, 클라이언트 업데이트 필요 여부 확인, 서비스 국가 제한 여부 확인을 제공합니다. 서버는 콘솔에 등록한 항목과 안내 문구를 반환할 뿐 접속을 직접 막지 않습니다. 접속 제한, 안내 화면 표시, 스토어 이동은 앱이 결과에 따라 구현합니다.

• 인터페이스: IServiceAccessService
• 네임스페이스: Hive.Axyl.ServiceAccess
• 패키지: com.com2usplatform.hiveaxyl.serviceaccess

등록과 획득

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.ServiceAccess;

var config = CoreConfig.CreateBuilder("{appId}").Build();

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddServiceAccess();
});

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

메서드 요약

'인증' 열의 의미는 인증 요구 표기를 참조하세요.

메서드	인증	설명
GetActiveMaintenancesAsync	불필요	현재 적용 중인 서버 점검 목록을 조회합니다.
CheckClientUpdateAsync	불필요	앱 클라이언트 버전에 업데이트가 필요한지 확인합니다.
CheckCountryBlockAsync	불필요	국가 코드가 서비스 국가 제한 대상인지 확인합니다.

모든 메서드는 로그인 세션의 인증 토큰을 보내지 않습니다. 따라서 로그인 전에도 호출할 수 있고, 세션이 만료돼도 인증 오류가 발생하지 않습니다.

공통 파라미터

모든 메서드의 마지막 파라미터는 ApiCallContext? context = null입니다. 생략하면 기본값이 적용됩니다. 자세한 내용은 호출 컨텍스트를 참조하세요.

모든 메서드는 조회 조건을 request 파라미터로 받으며, request는 Required입니다. 아래 메서드 설명에서는 요청 타입만 표기하고 파라미터 표는 생략합니다. 각 요청 타입의 필드는 데이터 타입에서 확인하세요.

자동으로 전달되는 값

SDK는 요청마다 초기화에 사용한 App ID를 X-App-Id 헤더에, 요청 언어를 Accept-Language 헤더에 담아 자동으로 보냅니다. 따라서 요청 타입에는 두 값을 담는 필드가 없습니다. 요청 언어는 초기화 시점의 기기 언어이며, SetLanguage()로 바꿉니다.

안내 문구인 Title과 Content는 요청 언어로 반환됩니다. 콘솔에 그 언어의 문구가 없으면 기본 언어로 등록한 문구가, 기본 언어의 문구도 없으면 빈 문자열이 반환됩니다.

발생 예외

• ArgumentNullException: request가 null인 경우, CheckClientUpdateRequest의 ClientVersion이나 CheckCountryBlockRequest의 CountryCode에 null을 지정한 경우

공통 Failure 코드

아래 코드는 서버가 코드로 응답하지만 기능 관점의 결과가 아니므로 Outcome이 아닌 Failure로 분기합니다. 원인 코드는 Failure.Problem.ExternalCode에 담깁니다. 결과 갈래와 분기 방법은 Core 결과 모델을 참조하세요.

• invalid_parameter: 요청 파라미터 형식 오류
• missing_field: 필수 파라미터나 필수 헤더 누락

서버가 internal_error 코드로 응답한 내부 오류는 Failure가 아니라 UnknownOutcome으로 분기하며, 코드는 UnknownOutcome.Code에 담깁니다. UnknownOutcome도 실패로 처리하세요.

메서드

GetActiveMaintenancesAsync

현재 시각에 적용 중인 서버 점검 항목 목록을 조회합니다. Data.Items는 가장 최근에 등록한 항목부터 정렬되며, 적용 중인 점검이 없으면 빈 목록입니다. 접속 IP나 PlayerId가 허용 목록에 있으면 점검이 적용 중이어도 빈 목록을 반환합니다.

요청의 ServerCode와 ClientVersion에 따라 반환되는 점검이 달라집니다. 대상 서버와 대상 버전을 모두 지정하지 않은 점검은 두 필드의 값과 관계없이 반환됩니다. ClientVersion은 앱 버전을 지정한 허용 목록 항목의 적용 여부도 결정합니다.

요청 필드	지정한 경우	지정하지 않은 경우
ServerCode	이 서버를 대상으로 하는 점검과 대상 서버를 지정하지 않은 점검을 반환합니다.	대상 서버와 관계없이 점검을 반환합니다.
ClientVersion	대상 버전을 지정하지 않은 점검과, 요청한 App ID와 이 버전을 대상으로 하는 점검을 반환합니다. 버전은 범위나 표기 차이를 해석하지 않고 문자열이 정확히 같은지만 비교합니다. 앱 버전을 지정한 허용 목록 항목은 이 버전과 같을 때만 적용됩니다.	대상 버전을 지정한 점검은 반환하지 않습니다. 허용 목록 항목은 앱 버전을 지정하지 않은 항목만 적용됩니다.

Unity

Task<ServiceAccessGetActiveMaintenancesResult> GetActiveMaintenancesAsync(GetActiveMaintenancesRequest request, ApiCallContext? context = null);

• 요청: GetActiveMaintenancesRequest
• 응답: GetActiveMaintenancesResponseData
• 응답 헤더: GetActiveMaintenancesResponseHeaders
• 인증: 불필요

결과 케이스 — ServiceAccessGetActiveMaintenancesResult

결과 케이스	와이어 코드	설명
Success	—	조회에 성공했습니다. 점검 목록은 Data.Items에, 응답 헤더 값은 Headers에 담깁니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 서버 점검을 참조하세요.

---

CheckClientUpdateAsync

요청의 ClientVersion에 업데이트가 필요한지 확인합니다. 버전은 범위나 표기 차이를 해석하지 않고 문자열이 정확히 같은지만 비교합니다. 적용 중인 클라이언트 업데이트 항목 중 요청한 App ID와 이 버전을 대상으로 하는 항목이 있으면 Data.UpdateRequired가 true이며, 강제 업데이트 여부와 안내 문구를 함께 반환합니다. 해당하는 항목이 여러 개이면 가장 최근에 등록한 항목을 반환하고, 적용할 항목이 없으면 Data.UpdateRequired가 false입니다.

접속 IP나 PlayerId가 허용 목록에 있으면 적용 중인 항목과 관계없이 업데이트가 필요하지 않은 결과를 반환합니다. 앱 버전을 지정한 허용 목록 항목은 요청의 ClientVersion과 같은 버전일 때만 적용됩니다.

Unity

Task<ServiceAccessCheckClientUpdateResult> CheckClientUpdateAsync(CheckClientUpdateRequest request, ApiCallContext? context = null);

• 요청: CheckClientUpdateRequest
• 응답: CheckClientUpdateResponseData
• 응답 헤더: CheckClientUpdateResponseHeaders
• 인증: 불필요

결과 케이스 — ServiceAccessCheckClientUpdateResult

결과 케이스	와이어 코드	설명
Success	—	확인에 성공했습니다. 업데이트 필요 여부는 Data.UpdateRequired에, 응답 헤더 값은 Headers에 담깁니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 클라이언트 업데이트를 참조하세요.

---

CheckCountryBlockAsync

요청의 CountryCode가 서비스 국가 제한 대상인지 확인합니다. 국가 코드는 대소문자를 구분하지 않고 비교합니다. 요청한 App ID에서 이 국가를 차단하는 서비스 국가 제한 항목이 적용 중이면 Data.Blocked가 true이며, 안내 문구와 이 App ID의 차단 국가 목록을 함께 반환합니다. 해당하는 항목이 여러 개이면 가장 최근에 등록한 항목을 반환합니다. 적용할 항목이 없으면 Data.Blocked가 false입니다.

접속 IP나 PlayerId가 허용 목록에 있으면 적용 중인 항목과 관계없이 차단되지 않은 결과를 반환합니다. 허용 목록 항목에 앱 버전을 지정했더라도 버전과 관계없이 해당 항목이 적용됩니다.

Unity

Task<ServiceAccessCheckCountryBlockResult> CheckCountryBlockAsync(CheckCountryBlockRequest request, ApiCallContext? context = null);

• 요청: CheckCountryBlockRequest
• 응답: CheckCountryBlockResponseData
• 응답 헤더: CheckCountryBlockResponseHeaders
• 인증: 불필요

결과 케이스 — ServiceAccessCheckCountryBlockResult

결과 케이스	와이어 코드	설명
Success	—	확인에 성공했습니다. 차단 여부는 Data.Blocked에, 응답 헤더 값은 Headers에 담깁니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 서비스 국가 제한을 참조하세요.

데이터 타입

여러 타입이 공유하는 필드는 의미가 같습니다.

• PlayerId: 허용 목록 적용 여부를 판별할 Player ID
• Id: 콘솔에 등록한 서비스 접근 제어 항목의 ID
• StartAt: 같은 객체의 Timezone 시간대로 표기한 항목의 적용 시작 시각. 시작 시각이 없는 항목이면 null
• EndAt: 같은 객체의 Timezone 시간대로 표기한 항목의 적용 종료 시각. 상시 사용 항목처럼 종료 시각이 없으면 null
• AlwaysOn: 콘솔에서 상시 사용으로 등록한 항목 여부
• Title: 사용자에게 표시할 요청 언어의 안내 제목. 언어 선택 방식은 자동으로 전달되는 값 참조
• Content: Title과 같은 언어의 안내 본문
• RedirectUrl: 사용자를 상세 안내 페이지나 스토어로 보낼 URL 또는 딥링크. 콘솔에 등록하지 않았으면 빈 문자열
• Timezone: StartAt과 EndAt의 시간대 정보. 필드는 TimeZoneInfo 참조
• Meta: 응답 부가 정보. 서비스 접근 제어 응답에서는 null

로그인 전에는 Player ID가 없으므로 PlayerId를 생략하고, 로그인한 뒤 다시 확인할 때 지정하세요. 로그인한 사용자의 Player ID는 ISessionManager의 PlayerId로 확인합니다. 허용 목록에 일치하는 항목이 없는 Player ID를 지정하면 결과는 달라지지 않습니다.

CheckClientUpdateRequest

클라이언트 업데이트 확인 요청입니다.

필드	타입	필수 여부	설명
ClientVersion	string	Required	확인할 앱 클라이언트 버전입니다. 콘솔에 등록한 버전과 같은 형식으로 지정합니다. 빈 문자열이거나 공백 문자가 들어간 값은 지정할 수 없습니다. 예: 1.2.0
PlayerId	long?	Optional	허용 목록 적용 여부를 판별할 Player ID입니다.

CheckClientUpdateResponseData

클라이언트 업데이트 확인 결과입니다. UpdateRequired가 false이면 적용할 항목이 없거나 허용 목록에 해당하는 경우이며, 나머지 필드에는 아래 값이 담깁니다.

• ForceUpdate, AlwaysOn: false
• Title, Content, RedirectUrl: 빈 문자열
• Versions: 빈 목록
• Id, StartAt, EndAt, Timezone: null

UpdateRequired를 먼저 확인한 뒤 나머지 필드를 사용하세요.

필드	타입	필수 여부	설명
Id	long?	Optional	적용된 클라이언트 업데이트 항목의 ID입니다.
UpdateRequired	bool	Required	업데이트가 필요하면 true입니다.
ForceUpdate	bool	Required	강제 업데이트이면 true, 선택 업데이트이면 false입니다. 콘솔의 강제 업데이트 설정을 따릅니다.
StartAt	DateTimeOffset?	Optional	적용 시작 시각입니다.
EndAt	DateTimeOffset?	Optional	적용 종료 시각입니다.
AlwaysOn	bool	Required	상시 사용 항목 여부입니다.
Title	string	Required	업데이트 안내 제목입니다.
Content	string	Required	업데이트 안내 본문입니다.
RedirectUrl	string	Required	스토어 같은 업데이트 안내 이동 경로입니다.
Timezone	TimeZoneInfoNullable?	Optional	StartAt과 EndAt의 시간대 정보입니다. 적용할 항목이 없으면 null입니다.
Versions	IReadOnlyList<ClientUpdateVersion>	Required	적용된 항목에 지정된 업데이트 대상 버전 중 요청한 App ID의 버전 목록입니다.
Meta	ResponseMeta?	Optional	응답 부가 정보입니다.

CheckCountryBlockRequest

서비스 국가 제한 확인 요청입니다.

필드	타입	필수 여부	설명
CountryCode	string	Required	확인할 국가의 ISO 3166-1 alpha-2 국가 코드입니다. 영문 두 글자로 지정하며, 대소문자는 구분하지 않습니다. 예: KR
PlayerId	long?	Optional	허용 목록 적용 여부를 판별할 Player ID입니다.

CheckCountryBlockResponseData

서비스 국가 제한 확인 결과입니다. Blocked가 false이면 적용할 항목이 없거나 허용 목록에 해당하는 경우이며, 나머지 필드에는 아래 값이 담깁니다.

• AlwaysOn: false
• Title, Content, RedirectUrl: 빈 문자열
• Countries: 빈 목록
• Id, StartAt, EndAt, Timezone: null

Blocked를 먼저 확인한 뒤 나머지 필드를 사용하세요.

필드	타입	필수 여부	설명
Id	long?	Optional	적용된 서비스 국가 제한 항목의 ID입니다. 차단 대상이 아니면 null입니다.
Blocked	bool	Required	요청한 국가가 차단 대상이면 true입니다.
StartAt	DateTimeOffset?	Optional	차단 시작 시각입니다.
EndAt	DateTimeOffset?	Optional	차단 종료 시각입니다.
AlwaysOn	bool	Required	상시 사용 항목 여부입니다.
Title	string	Required	차단 안내 제목입니다.
Content	string	Required	차단 안내 본문입니다.
RedirectUrl	string	Required	차단 안내 이동 경로입니다.
Timezone	TimeZoneInfoNullable?	Optional	StartAt과 EndAt의 시간대 정보입니다. 요청의 CountryCode가 아니라 접속 IP로 판별한 국가를 기준으로 정합니다. 차단 대상이 아니면 null입니다.
Countries	IReadOnlyList<CountryBlockCountry>	Required	적용된 항목에 지정된 차단 국가 중 요청한 App ID의 차단 국가 목록입니다.
Meta	ResponseMeta?	Optional	응답 부가 정보입니다.

ClientUpdateVersion

클라이언트 업데이트 항목에 지정된 대상 버전입니다. App ID와 버전을 한 쌍으로 담습니다.

필드	타입	필수 여부	설명
AppId	string	Required	대상 App ID입니다.
ClientVersion	string	Required	대상 앱 클라이언트 버전입니다.

CountryBlockCountry

서비스 국가 제한 항목에 지정된 차단 국가입니다. App ID와 국가 코드를 한 쌍으로 담습니다.

필드	타입	필수 여부	설명
AppId	string	Required	차단을 적용하는 App ID입니다.
CountryCode	string	Required	차단 국가의 ISO 3166-1 alpha-2 국가 코드입니다.

GetActiveMaintenancesRequest

서버 점검 조회 요청입니다. 모든 필드를 생략할 수 있으며, ServerCode와 ClientVersion에 빈 문자열을 지정하면 생략한 것과 같습니다.

필드	타입	필수 여부	설명
ServerCode	string?	Optional	조회할 앱 서버의 서버 ID입니다. 콘솔의 앱 서버에 등록한 값을 지정합니다.
ClientVersion	string?	Optional	앱 클라이언트 버전입니다. 콘솔에 등록한 버전과 같은 형식으로 지정합니다.
PlayerId	long?	Optional	허용 목록 적용 여부를 판별할 Player ID입니다.

GetActiveMaintenancesResponseData

서버 점검 조회 결과입니다.

필드	타입	필수 여부	설명
Items	IReadOnlyList<Maintenance>	Required	적용 중인 서버 점검 목록입니다. 적용 중인 점검이 없으면 빈 목록입니다.
Meta	ResponseMeta?	Optional	응답 부가 정보입니다.

Maintenance

적용 중인 서버 점검 항목입니다.

필드	타입	필수 여부	설명
Id	long	Required	서버 점검 항목의 ID입니다.
StartAt	DateTimeOffset?	Optional	점검 시작 시각입니다. 시작 시각 없이 등록한 상시 사용 항목에서만 null입니다.
EndAt	DateTimeOffset?	Optional	점검 종료 시각입니다. 상시 사용 항목처럼 종료 시각이 없으면 null입니다.
AlwaysOn	bool	Required	상시 사용 항목 여부입니다.
Title	string	Required	점검 안내 제목입니다.
Content	string	Required	점검 안내 본문입니다.
RedirectUrl	string	Required	점검 안내 이동 경로입니다.
Timezone	TimeZoneInfo	Required	StartAt과 EndAt의 시간대 정보입니다.
Servers	IReadOnlyList<string>	Required	점검 대상 서버 ID 목록입니다. 대상 서버를 지정하지 않은 점검이면 빈 목록입니다.
Versions	IReadOnlyList<MaintenanceVersion>	Required	점검 대상 버전 중 요청한 App ID의 버전 목록입니다. 대상 버전을 지정하지 않은 점검이면 빈 목록입니다.

MaintenanceVersion

서버 점검 항목에 지정된 대상 버전입니다. App ID와 버전을 한 쌍으로 담습니다.

필드	타입	필수 여부	설명
AppId	string	Required	대상 App ID입니다.
ClientVersion	string	Required	대상 앱 클라이언트 버전입니다.

ResponseMeta

응답 부가 정보입니다. 서비스 접근 제어 서버는 응답의 Meta를 null로 보내므로, 문의나 로그 조회에는 응답 헤더의 XTraceId를 사용하세요.

필드	타입	필수 여부	설명
RequestId	string?	Optional	문의나 로그 조회에 사용하는 요청 ID입니다.
Timestamp	DateTimeOffset?	Optional	서버가 응답을 만든 시각입니다.

TimeZoneInfo, TimeZoneInfoNullable

TimeZoneInfo와 TimeZoneInfoNullable은 응답의 StartAt과 EndAt을 해석하는 시간대 정보이며, 필드가 같습니다. Maintenance.Timezone은 항상 값이 담기는 TimeZoneInfo이고, 클라이언트 업데이트와 서비스 국가 제한 확인 결과의 Timezone은 적용할 항목이 없으면 null이 되는 TimeZoneInfoNullable입니다.

서버는 요청 값과 관계없이 접속 IP로 판별한 국가를 기준으로 시간대를 정하며, 국가를 판별할 수 없으면 UTC를 사용합니다. 따라서 앱에서 시간대 정보를 따로 전달할 필요는 없습니다. StartAt과 EndAt의 시차는 각 시각에 이 시간대에서 적용되는 값이므로, 두 시각 사이에 서머타임 전환이 있으면 두 시각의 시차가 서로 다릅니다.

System.TimeZoneInfo와 이름이 같습니다

System 네임스페이스에도 같은 이름의 TimeZoneInfo가 있습니다. 한 파일에서 using System;과 using Hive.Axyl.ServiceAccess;를 함께 선언한 뒤 TimeZoneInfo를 그대로 쓰면 어느 타입인지 모호해 컴파일 오류가 발생합니다. 이런 파일에서는 using AccessTimeZoneInfo = Hive.Axyl.ServiceAccess.TimeZoneInfo;처럼 별칭을 지정하거나 전체 이름을 쓰세요.

필드	타입	필수 여부	설명
Id	string	Required	IANA 시간대 식별자입니다. 예: Asia/Seoul
UtcOffset	string	Required	±HH:MM 형식의 UTC 기준 시차이며 서머타임을 반영합니다. 기준 시각은 StartAt이고, StartAt이 null이면 EndAt, 둘 다 null이면 현재 시각입니다. 시차가 0이면 +00:00입니다. 예: +09:00
OffsetSeconds	int	Required	초 단위의 UTC 기준 시차입니다. UtcOffset과 같은 기준 시각으로 계산합니다. 예: 32400
Dst	bool	Required	UtcOffset의 기준 시각에 서머타임이 적용되면 true입니다.
IsInEuropeanUnion	bool	Required	시간대를 정한 국가가 유럽 연합 회원국이면 true입니다. UTC를 사용하면 false입니다.
Name	string?	Optional	요청 언어로 표기한 국가 이름입니다. 요청 언어 태그의 이름이 없으면 언어 부분만 남긴 태그, 영어, 제공되는 다른 언어 순으로 이름을 찾습니다. 예를 들어 요청 언어가 pt-BR이면 pt-BR, pt, en 순입니다. 국가 이름이 없거나 UTC를 사용하면 null입니다.
Names	IReadOnlyDictionary<string, string>	Required	언어 태그별 국가 이름입니다. 기본으로 제공하는 언어 태그는 de, en, es, fr, ja, pt-BR, ru, zh-CN, ko, vi, fil이며, 이름이 있는 언어만 담깁니다. UTC를 사용하면 비어 있습니다.

응답 헤더 타입

CheckClientUpdateResponseHeaders, CheckCountryBlockResponseHeaders, GetActiveMaintenancesResponseHeaders는 각 메서드의 Success.Headers로 전달되는 응답 헤더 값이며, 필드가 같습니다.

필드	타입	필수 여부	설명
XTraceId	string?	Optional	서버가 모든 응답에 담아 보내는 32자리 16진수 추적 ID입니다. SDK가 요청마다 만든 추적 ID와 같은 값입니다. 문제를 문의하거나 로그를 조회할 때 사용합니다.