콘텐츠로 이동

이용 제한

Method

GetBlockStatusAsync

운영 정책을 어긴 사용자의 앱 진입을 막으려면 GetBlockStatusAsync()를 호출해 현재 로그인한 사용자의 이용 제한 여부를 확인하세요. 제재 대상이면 제재 유형과 기간, 사용자에게 보여줄 안내 문구가 함께 반환됩니다.

제재 대상 등록과 해제는 Hive 콘솔의 이용 제한에서만 처리합니다. 앱은 이용 제한 여부를 조회만 합니다. 조회 결과에 따라 안내 문구를 보여 주고 앱 진입을 막는 화면은 앱 클라이언트에서 직접 구현하세요.

이용 제한 여부는 오류가 아니라 성공 응답의 데이터로 전달됩니다. 제재 대상이어도 메서드 호출 자체는 성공하므로, Data.IsBlocked 값을 확인해 진입 여부를 결정하세요.

호출 시점은 로그인으로 세션을 등록한 직후, 사용자가 앱의 주요 화면으로 들어가기 직전입니다. 이 메서드는 현재 세션의 액세스 토큰으로 사용자를 식별하므로 별도의 요청 값이 필요하지 않습니다.

Note

로그인 응답의 Data.IsBlock으로도 제재 대상 여부를 알 수 있습니다. 다만 로그인 응답에는 제재 유형과 기간, 안내 문구가 담기지 않으므로 사용자에게 사유를 안내하려면 이 메서드를 호출해야 합니다.

호출 파라미터

필드명 타입 필수 여부 설명
context ApiCallContext Optional 호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

호출 예시

GetBlockStatusAsync()의 반환 객체 AuthGetBlockStatusResult는 성공, 기능별 결과인 Outcome, 호출을 마치지 못한 Failure로 나뉩니다. 이 메서드는 예외를 던지지 않고 모든 처리 결과를 반환 객체로 전달하므로, try/catch 대신 switch 구문으로 분기해 처리하세요.

using Hive.Axyl.Auth;
using Hive.Axyl.Core;
using UnityEngine;

IAuthService auth = HiveCore.Resolve<IAuthService>();

AuthGetBlockStatusResult result = await auth.GetBlockStatusAsync();

switch (result)
{
    case AuthGetBlockStatusResult.Success success when success.Data.IsBlocked:
        // 제재 대상 → 안내 문구를 그대로 노출하고 앱 진입을 막습니다.
        BlockDetail block = success.Data.Block;
        bool isPermanent = block.EndAt == null;
        Debug.LogWarning($"이용 제한: {block.Name} / 영구 여부: {isPermanent}");
        ShowBlockPopup(block.Message);
        break;

    case AuthGetBlockStatusResult.Success:
        // 제한 없음 → 앱 진입을 계속 진행합니다.
        break;

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

    // 안전망: 처리하지 않은 결과 및 알 수 없는 신규 결과(UnknownOutcome)
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 데이터

성공 시 AuthGetBlockStatusResult.Success의 Data에 결과가 담깁니다.

변수명 타입 필수 여부 설명
Data.IsBlocked bool Required 이용 제한 여부입니다. true이면 Data.Block에 상세 정보가 담깁니다.
Data.Block BlockDetail Optional 이용 제한 상세 정보입니다. 제한이 없으면 null입니다.

BlockDetail

변수명 타입 필수 여부 설명
Code int Required 100~999 범위의 이용 제한 유형 코드입니다. Hive 콘솔의 이용 제한 유형에 등록한 코드와 같은 값입니다.
Name string Required 이용 제한 유형 이름
Message string Required 사용자에게 보여줄 안내 문구입니다. 기기 언어 또는 SetLanguage로 지정한 언어로 요청한 문구가 담기며, 그 언어의 문구가 비어 있거나 앱이 지원하지 않는 언어이면 앱의 기본 언어 문구가 담깁니다. 앱 클라이언트는 받은 값을 그대로 노출합니다.
StartAt DateTimeOffset Required 이용 제한 시작 시각. UTC 기준입니다.
EndAt DateTimeOffset? Optional 이용 제한 종료 시각. UTC 기준이며 null이면 영구 제한입니다.

응답 예시

// 제한 없음
// success.Data.IsBlocked = false
// success.Data.Block     = null

// 기간 제한
// success.Data.IsBlocked = true
// success.Data.Block.Code    = 101
// success.Data.Block.Name    = "Abusive Language"
// success.Data.Block.Message = "욕설 사용으로 7일간 이용이 제한되었습니다."
// success.Data.Block.StartAt = 2026-04-01T09:00:00+00:00
// success.Data.Block.EndAt   = 2026-04-08T09:00:00+00:00

// 영구 제한
// success.Data.IsBlocked = true
// success.Data.Block.Code    = 102
// success.Data.Block.Name    = "Permanent Ban"
// success.Data.Block.Message = "계정이 영구적으로 제한되었습니다."
// success.Data.Block.StartAt = 2026-04-01T09:00:00+00:00
// success.Data.Block.EndAt   = null

응답 상태

반환 객체 AuthGetBlockStatusResult는 아래 케이스 중 하나로 분기됩니다. 이용 제한 여부는 별도 케이스가 아니라 Success의 Data.IsBlocked 값으로 전달됩니다.

응답 케이스 설명 앱 클라이언트 대응
Success 조회 성공. Data.IsBlocked와 Data.Block에 제한 여부와 상세가 담깁니다. Data.IsBlocked 값에 따라 진입 또는 차단
BlockTypeNotFound 이용 제한 유형 정보를 찾을 수 없는 경우 콘솔의 이용 제한 유형 등록 상태 확인
BlockTypeContentNotFound 이용 제한 유형은 있지만 기본 언어의 안내 문구를 찾을 수 없는 경우 콘솔의 이용 제한 유형에서 기본 언어 안내 문구 입력 상태 확인
AppNotFound · TerminateService 앱 정보를 찾을 수 없거나 서비스가 종료된 앱인 경우 콘솔의 App ID 등록 상태와 서비스 운영 상태 확인
AppIdMismatch · InvalidGatewayContext 요청의 App ID가 인증 토큰의 프로젝트와 다르거나 인증 컨텍스트가 유효하지 않은 경우 SDK 초기화에 사용한 App ID와 세션 상태 확인
UnknownOutcome 이 SDK 버전이 알지 못하는 신규 결과 로깅 후 보수적으로 처리
Failure 공통 Failure입니다. 필수 파라미터 누락·형식 오류(invalid_parameter), 필수 필드 누락(missing_field), X-App-Id 헤더 누락(missing_app_id)도 여기로 분기하며 원인은 Failure.Problem.ExternalCode에 담깁니다. 공통 오류 처리를 참조하세요. 공통 오류 처리 기준에 따라 처리

연관 문서