서비스 국가 제한

서비스 국가 제한 확인 메서드로 앱이 전달한 사용자 국가 코드가 콘솔에 등록한 차단 국가에 해당하는지 확인합니다.

1. Hive 콘솔에서 서비스 국가 제한 설정

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

2. 호출 파라미터값 준비

호출 전에 차단 여부를 판단할 CountryCode와 허용 목록 적용 여부를 확인할 PlayerId를 준비합니다.

CountryCode

CountryCode는 사용자의 국가를 나타내는 ISO 3166-1 alpha-2 국가 코드입니다. 예를 들어 대한민국은 KR입니다. 서버는 대소문자를 구분하지 않고 이 값을 콘솔에 등록한 차단 국가와 비교해 차단 여부를 판정합니다.

PlayerId

PlayerId는 사용자가 허용 목록에 등록된 대상인지 확인할 때 사용하는 Player ID입니다. 서버가 요청을 처리할 때 허용 목록을 자동으로 적용하므로 앱에서 허용 목록을 따로 조회할 필요는 없습니다. 접속 IP나 PlayerId가 허용 목록에 있으면 적용 중인 차단 항목이 있어도 Data.Blocked는 false입니다. 서비스 국가 제한에서는 허용 목록 항목에 앱 버전을 지정했더라도 버전과 관계없이 해당 항목이 적용됩니다. 허용 목록에 일치하는 항목이 없으면 PlayerId는 결과에 영향을 주지 않습니다.

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

3. 서비스 국가 제한 확인 메서드 호출

CheckCountryBlockAsync

CheckCountryBlockAsync()를 호출해 요청에 담은 CountryCode가 적용 중인 서비스 국가 제한 항목의 차단 국가에 해당하는지 확인합니다. 차단 대상이면 안내 제목, 본문, 리다이렉트 URL을 함께 반환합니다. 앱은 이 결과에 따라 진입 차단이나 안내 화면 노출 여부를 결정합니다. 로그인 전에도 호출할 수 있으며 보통 앱 시작 시점에 실행합니다.

호출 파라미터

필드명	타입	필수 여부	설명
request	CheckCountryBlockRequest	Required	국가 차단 조회 요청
context	ApiCallContext	Optional	호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

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

CheckCountryBlockRequest

필드명	타입	필수 여부	설명
`CountryCode`	string	Required	국가 코드(ISO 3166-1 alpha-2). 서버는 대소문자를 구분하지 않고 이 값을 콘솔에 등록한 차단 국가와 비교합니다.
`PlayerId`	long?	Optional	허용 목록 적용 여부를 확인할 Player ID. 로그인 전에는 생략합니다.

호출 예시

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

Unity

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

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

var request = new CheckCountryBlockRequest {
    CountryCode = "CN",   // 사용자 국가 코드 (ISO 3166-1 alpha-2)
    // PlayerId = HiveCore.Resolve<ISessionManager>().PlayerId,  // 로그인한 뒤 확인할 때 지정
};

ServiceAccessCheckCountryBlockResult result = await service.CheckCountryBlockAsync(request);

switch (result)
{
    case ServiceAccessCheckCountryBlockResult.Success success:
        if (success.Data.Blocked)
        {
            // 차단 대상 -> 안내 화면 노출 또는 리다이렉트 (실제 차단은 앱이 구현)
            Debug.Log($"접속 차단: {success.Data.Title} ({success.Data.RedirectUrl})");
        }
        else
        {
            // 접속 허용
        }
        break;

    // 공통 실패 처리 (네트워크·서버 오류, 요청 값 오류)
    case ServiceAccessCheckCountryBlockResult.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;
}

응답 데이터

성공하면 ServiceAccessCheckCountryBlockResult.Success의 Data(CheckCountryBlockResponseData)에 결과가 담깁니다. Data.Blocked가 true이면 앱은 안내 UI 노출과 리다이렉트를 직접 구현해야 합니다. 요청한 국가에 해당하는 차단 항목이 여러 개이면 가장 최근에 등록한 항목의 안내 문구와 차단 국가 목록을 반환합니다.

필드명	타입	필수 여부	설명
`Data.Blocked`	bool	Required	전달한 국가 코드의 차단 여부
`Data.Id`	long?	Optional	적용된 서비스 국가 제한 항목의 ID. 차단 대상이 아니면 `null`
`Data.Title`	string	Required	차단 시 노출할 안내 제목. 차단 대상이 아니면 빈 문자열
`Data.Content`	string	Required	차단 시 노출할 안내 본문. 차단 대상이 아니면 빈 문자열
`Data.RedirectUrl`	string	Required	차단 시 이동시킬 안내 URL. 콘솔에 설정하지 않았거나 차단 대상이 아니면 빈 문자열
`Data.Countries`	`IReadOnlyList<CountryBlockCountry>`	Required	적용된 항목에서 요청한 App ID에 지정한 차단 국가 목록. 차단 대상이 아니면 빈 목록. 항목 구조는 아래 `CountryBlockCountry` 참고
`Data.AlwaysOn`	bool	Required	상시 차단 여부
`Data.StartAt`·`Data.EndAt`	DateTimeOffset?	Optional	차단 적용 기간. 차단 대상이 아니면 둘 다 `null`이고, 시작 시각을 지정하지 않은 항목이면 `StartAt`이, 종료 시점이 없는 상시 차단이면 `EndAt`이 `null`
`Data.Timezone`	`TimeZoneInfoNullable`	Optional	`StartAt`과 `EndAt`을 해석하는 기준 시간대. 차단 대상이 아니면 `null`. 항목 구조는 아래 `TimeZoneInfoNullable` 참고

CountryBlockCountry

필드명	타입	필수 여부	설명
`AppId`	string	Required	차단 대상 App ID
`CountryCode`	string	Required	차단 국가 코드(ISO 3166-1 alpha-2)

TimeZoneInfoNullable

Data.Timezone은 Data.StartAt과 Data.EndAt을 해석하는 시간대 정보입니다. 서버는 요청에 담은 CountryCode와 관계없이 접속 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.Blocked가 false이면 안내 제목, 본문, 리다이렉트 URL이 모두 빈 문자열입니다. 안내 화면을 띄우기 전에 먼저 Data.Blocked를 확인하세요. 실제 접속 차단과 안내 화면 노출은 앱 클라이언트가 직접 구현해야 합니다.

응답 헤더

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

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

응답 예시