Core 설정

SDK 초기화에 사용하는 설정 타입입니다. CoreConfig는 앱 식별자, 토큰 자동 갱신, 로그, 네트워크 정책을 담으며 CoreConfigBuilder로 만듭니다. 한 번 만든 설정은 변경할 수 없습니다.

설정 항목

설정	지정 메서드	타입	기본값	설명
앱 식별자	`CreateBuilder()`	`string`	— (필수)	Hive 플랫폼에 등록한 앱 식별자입니다.
토큰 자동 갱신	`SetAutoRefresh()`	`bool`	`true`	401 응답을 받았을 때 토큰을 자동으로 갱신할지 여부입니다.
최소 로그 레벨	`SetMinLevel()`	LogLevel	`LogLevel.Info`	이 레벨 이상인 로그만 출력합니다.
콘솔 출력	`SetEnableConsole()`	`bool`	`true`	엔진 콘솔에 로그를 출력할지 여부입니다.
PII 마스킹	`SetEnablePiiMasking()`	`bool`	`true`	로그의 개인 정보를 가릴지 여부입니다.
마스킹 예외 키	`SetAllowlist()`	`params string[]`	기본 10개	마스킹에서 제외할 추가 키입니다.
요청 제한 시간	`SetTimeoutMillis()`	`int`	`30000`	요청 제한 시간(밀리초)입니다. `0`보다 커야 합니다.
최대 재시도 횟수	`SetMaxRetries()`	`int`	`3`	일시적 실패에 재시도할 최대 횟수입니다. `0` 이상이어야 합니다.
백오프 기준 지연	`SetBackoffBaseMs()`	`int`	`1000`	지수 백오프의 기준 지연 시간(밀리초)입니다. `0`보다 커야 합니다.
`Retry-After` 최대 대기	`SetRetryAfterMaxWaitMs()`	`int`	`60000`	서버가 보낸 `Retry-After` 값을 기다리는 최대 시간(밀리초)입니다. 이 값을 넘으면 기다리지 않고 즉시 실패합니다. `0`보다 커야 합니다.

기본값을 그대로 쓰면 되는 항목이 대부분이므로, 바꿀 항목만 지정하세요.

Unity

using Hive.Axyl.Core;

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

CoreConfig

class — 네임스페이스 Hive.Axyl.Core

CoreConfigBuilder가 만든 읽기 전용 설정 객체입니다.

CreateBuilder

지정한 앱 식별자로 새 CoreConfigBuilder를 만듭니다.

Unity

static CoreConfigBuilder CreateBuilder(string appId)

파라미터	타입	필수 여부	설명
`appId`	`string`	Required	Hive 플랫폼에 등록한 앱 식별자입니다. 모든 서버 요청의 `X-App-Id` 헤더로 전송되며, 기기 보안 저장소의 영역을 구분하는 데에도 사용합니다. 빈 문자열이나 공백일 수 없습니다.

스토어 번들 식별자가 아닙니다

appId는 Hive 플랫폼 등록값입니다. 같은 앱이라도 플랫폼별 빌드가 각각 별도의 앱으로 등록되므로, 등록한 값과 정확히 일치해야 합니다. 스토어 번들 식별자는 SDK가 서버에 따로 보고합니다.

반환: CoreConfigBuilder

프로퍼티

설정 값은 네 그룹으로 나뉘어 담깁니다.

프로퍼티	타입	담고 있는 값
`App`	`AppOptions`	`AppId`
`Auth`	`AuthOptions`	`AutoRefresh`
`Log`	`LogOptions`	`MinLevel`, `EnableConsole`, `EnablePiiMasking`, `Allowlist`
`Network`	`NetworkOptions`	`TimeoutMillis`, `MaxRetries`, `BackoffBaseMs`, `RetryAfterMaxWaitMs`

각 그룹 타입은 모두 읽기 전용이며, 프로퍼티 이름과 의미는 설정 항목 표와 같습니다.

Unity

string appId = config.App.AppId;
int timeout = config.Network.TimeoutMillis;

CoreConfigBuilder

class — 네임스페이스 Hive.Axyl.Core

CoreConfig를 만드는 빌더입니다. 모든 SetXxx() 메서드는 자기 자신을 반환하므로 이어서 호출할 수 있습니다. 지정할 수 있는 항목과 기본값은 설정 항목을 참조하세요.

Build

모든 설정을 검증하고 CoreConfig를 만듭니다.

Unity

CoreConfig Build()

반환: CoreConfig

발생 예외

ArgumentException: appId가 null이거나 빈 문자열이거나 공백인 경우
ArgumentOutOfRangeException: 숫자 설정이 유효 범위를 벗어난 경우. 범위는 설정 항목의 설명을 참조하세요.

열거형

LogLevel

로그의 심각도입니다. 값이 클수록 심각하며, MinLevel 이상인 로그만 출력합니다.

C# 멤버	값	설명
`Debug`	0	개발 중 확인하는 상세 진단 정보입니다.
`Info`	1	일반적인 정보성 메시지입니다.
`Warn`	2	주의가 필요한 상황입니다.
`Error`	3	오류가 발생했지만 SDK가 계속 동작할 수 있는 상황입니다.
`Fatal`	4	SDK 동작을 중단시킬 수 있는 심각한 오류입니다.

로그 수집 연결

SDK 로그를 엔진 콘솔 외의 대상으로 보내려면 ILogSink를 구현해 등록합니다. 앱의 오류 수집 도구나 파일 로거에 SDK 로그를 함께 남길 때 사용합니다.

로그는 PII 마스킹과 최소 레벨 필터를 거친 뒤에 전달됩니다.

Unity

using Hive.Axyl.Core;

sealed class FileLogSink : ILogSink
{
    public void Emit(LogEntry entry)
    {
        // entry.Level, entry.Category, entry.Message ...
    }
}

// HiveBootstrap.Initialize 이후에 호출합니다.
HiveCore.AddLogSink(new FileLogSink());

ILogSink

interface — 네임스페이스 Hive.Axyl.Core

로그를 특정 대상으로 내보내는 인터페이스입니다.

Emit은 어느 스레드에서든 호출될 수 있으므로 구현체가 직접 스레드 안전성을 보장해야 합니다. UI를 갱신해야 한다면 구현 안에서 메인 스레드로 넘기세요.

void Emit(LogEntry entry): 로그 항목 하나를 이 대상으로 내보내는 메서드. PII 마스킹과 최소 레벨 필터를 거친 뒤 호출됩니다.

LogEntry

struct — 네임스페이스 Hive.Axyl.Core

Emit에 전달되는 로그 항목입니다. 생성 후 변경할 수 없습니다.

프로퍼티	타입	필수 여부	설명
`TimestampMs`	`long`	Required	로그를 만든 시각입니다. Unix epoch 밀리초(UTC)입니다.
`Level`	LogLevel	Required	이 항목의 심각도입니다.
`Category`	`string`	Required	로그를 만든 하위 시스템 이름입니다. 예: `Transport`, `Auth`, `Session`.
`Message`	`string`	Required	사람이 읽을 수 있는 로그 메시지입니다. 영문입니다.
`Context`	`IReadOnlyDictionary<string, object>?`	Optional	항목에 덧붙은 키-값 정보입니다. 추가 정보가 없으면 `null`입니다.
`TraceId`	`string?`	Optional	요청을 추적하는 식별자입니다.

PII 마스킹

EnablePiiMasking이 true이면 Context의 값 중 허용 목록에 없는 키의 값이 ***로 바뀐 뒤 Emit에 전달됩니다. 키 이름은 대소문자를 구분하지 않습니다.

기본 허용 목록은 아래 열 개이며, SetAllowlist()로 키를 추가할 수는 있지만 기본 항목을 제거할 수는 없습니다.

errorCode, errorMessage, category, timestamp, traceId, requestId, durationMs, method, url, statusCode