Core 모듈

모든 Hive Axyl SDK 모듈이 공통으로 의존하는 런타임입니다. SDK 초기화, 사용할 모듈의 등록과 조회, 세션 보관, 호출 정책, 결과와 오류 모델을 제공합니다. 다른 모듈을 하나라도 설치하면 Core가 함께 설치되므로 따로 추가할 필요가 없습니다.

모듈 정보

패키지: com.com2usplatform.hiveaxyl.core
네임스페이스: Hive.Axyl.Core, Hive.Axyl.Core.Unity
지원 플랫폼: 전체
최소 사양: Unity 6000.0+

Windows 빌드 요구 사항

com.com2usplatform.hiveaxyl.core는 네이티브 플러그인을 포함합니다. Windows에서는 Microsoft Visual C++ 2015-2022 재배포 가능 패키지(x64)가 설치되어 있어야 하며, 없으면 초기화 단계에서 DllNotFoundException이 발생합니다. 빌드한 플레이어뿐 아니라 Windows 에디터에서도 마찬가지입니다.

레퍼런스 구성

Core 모듈의 레퍼런스는 아래 페이지로 나뉩니다.

이 페이지: HiveBootstrap, HiveCore, IHiveBuilder
설정: CoreConfig, CoreConfigBuilder, 설정 항목과 기본값, 로그 관련 타입
세션: ISessionManager, SessionSnapshot
호출 컨텍스트: ApiCallContext, RequestOptions, CallCredential
결과 모델: IAxylResult와 결과 분기에 사용하는 마커 인터페이스
오류: HiveError, HiveErrorCode, RegistrationNotFoundException

초기화 흐름

설정을 만들고, 사용할 모듈을 등록하고, 인터페이스를 가져오는 세 단계입니다.

Unity

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

void Start()
{
    // 1. 설정을 만듭니다.
    var config = CoreConfig.CreateBuilder("{appId}").Build();

    // 2. 사용할 모듈을 등록하며 초기화합니다.
    HiveBootstrap.Initialize(config, builder =>
    {
        builder.AddAuth()
               .AddToken();
    });

    // 3. 등록한 인터페이스를 가져옵니다.
    IAuthService auth = HiveCore.Resolve<IAuthService>();
}

스레드 모델

SDK가 발생시키는 이벤트는 모두 엔진 메인 스레드에서 호출되므로 이벤트 핸들러 안에서 엔진 API를 사용해도 됩니다. 반면 비동기 메서드는 그렇지 않습니다. 반환된 태스크는 어느 스레드에서든 완료될 수 있으므로, await 이후에 엔진 API를 사용한다면 앱 코드가 직접 메인 스레드로 넘겨야 합니다.

HiveBootstrap

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

Unity 애플리케이션 생명 주기와 HiveCore를 연결하는 진입 클래스입니다. 씬을 전환해도 유지되는 숨김 GameObject를 만들고, 일시 중지·재개·종료 이벤트를 HiveCore에 전달합니다.

앱 코드는 메인 스레드에서 Initialize를 한 번만 호출하면 됩니다. Unity용 어댑터 구성은 이 클래스가 대신 처리합니다.

Initialize

SDK를 초기화합니다. 다른 SDK API를 사용하기 전에 정확히 한 번만 호출하세요.

Unity

static void Initialize(CoreConfig config)
static void Initialize(CoreConfig config, Action<IHiveBuilder> assemble)

파라미터	타입	필수 여부	설명
`config`	`CoreConfig`	Required	CoreConfig.CreateBuilder()로 만든 설정입니다.
`assemble`	`Action<IHiveBuilder>`	Required	사용할 모듈을 등록하는 클로저입니다. 두 번째 오버로드에서만 사용합니다.

첫 번째 오버로드는 모듈을 등록하지 않고 런타임만 초기화합니다. 모듈을 하나라도 사용한다면 두 번째 오버로드를 쓰세요.

발생 예외

ArgumentNullException: config가 null인 경우
InvalidOperationException: SDK를 이미 초기화한 경우. HiveCore.Shutdown()을 먼저 호출하세요.
DllNotFoundException: Windows에서 네이티브 플러그인을 불러오지 못한 경우. 플러그인이 빌드에 포함되지 않았거나, 기기에 Microsoft Visual C++ 2015-2022 재배포 가능 패키지(x64)가 없을 때 발생하며, 예외 메시지에 설치 링크가 담겨 있습니다.

설치 절차와 초기화 옵션은 SDK 초기화를 참조하세요.

HiveCore

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

SDK 런타임의 정적 진입점입니다. 등록된 서비스 조회, 언어 설정, 종료와 생명 주기 전환을 담당합니다.

Unity에서는 초기화를 HiveBootstrap.Initialize가 대신 수행하므로, 앱 코드가 HiveCore에서 직접 사용하는 것은 주로 Resolve<T>()입니다.

메서드 요약

Resolve<T>(): 등록된 서비스 조회, 등록되지 않았으면 예외 발생
TryResolve<T>(): 등록된 서비스 조회, 등록되지 않았으면 false 반환
SetLanguage(): 이후 요청에 실어 보낼 언어 지정
AddLogSink(): 런타임에 로그 수신 대상 추가
Suspend(): 앱의 백그라운드 전환 알림
Resume(): 앱의 포그라운드 복귀 알림
Shutdown(): SDK 종료와 자원 해제

Unity에서는 Suspend, Resume, Shutdown을 HiveBootstrap이 생명 주기 이벤트에 맞춰 자동으로 호출합니다.

메서드

Resolve

등록된 서비스를 가져옵니다. 모듈이 반드시 등록되어 있어야 하는 상황에서 사용합니다.

Unity

static T Resolve<T>() where T : class

반환: T, 등록된 서비스 인스턴스

발생 예외

InvalidOperationException: SDK를 초기화하지 않은 경우
RegistrationNotFoundException: T 타입으로 등록된 서비스가 없는 경우

TryResolve

등록된 서비스를 예외 없이 가져옵니다. SDK를 초기화하지 않았거나 서비스가 등록되지 않았으면 false를 반환합니다.

Add-on은 지원 플랫폼에서만 등록됩니다. Unity 에디터나 지원하지 않는 플랫폼에서는 등록되지 않으므로, Add-on은 Resolve<T>() 대신 이 메서드로 확인한 뒤 사용하세요.

Unity

static bool TryResolve<T>(out T? service) where T : class

파라미터	타입	필수 여부	설명
`service`	`out T?`	Required	`true`를 반환하면 등록된 서비스가 담깁니다. 그렇지 않으면 `null`입니다.

반환: bool, 서비스를 가져왔으면 true

호출 예시

Unity

if (HiveCore.TryResolve<IAppleSignInPlugin>(out var apple))
{
    // 지원 플랫폼에서만 실행되는 코드
}

SetLanguage

이후 요청의 Accept-Language 헤더에 실어 보낼 언어를 지정합니다. 재초기화 없이 다음 요청부터 적용되며, 이미 전송 중인 요청에는 영향을 주지 않습니다.

앱이 OS 언어와 별개로 자체 언어 설정을 두는 경우에 사용합니다. 호출하지 않으면 초기화 시점에 읽은 OS 언어를 사용합니다.

어느 스레드에서 호출해도 안전합니다.

Unity

static void SetLanguage(string? language)

파라미터	타입	필수 여부	설명
`language`	`string?`	Required	BCP 47 언어 태그입니다. 예: `ja-JP`. `null`을 지정하면 초기화 시점에 읽은 OS 언어로 되돌립니다.

발생 예외

ArgumentException: language가 빈 문자열이거나 공백이거나, BCP 47 형식이 아닌 경우
InvalidOperationException: SDK를 초기화하지 않은 경우

AddLogSink

로그 수신 대상을 런타임에 추가합니다. 앱이 자체 로그 수집 도구로 SDK 로그를 보내려 할 때 사용합니다.

로그는 PII 마스킹과 최소 레벨 필터를 거친 뒤 전달됩니다. 자세한 내용은 로그 수집 연결을 참조하세요.

Unity

static void AddLogSink(ILogSink sink)

파라미터	타입	필수 여부	설명
`sink`	ILogSink	Required	등록할 수신 대상입니다. `null`을 지정할 수 없습니다.

발생 예외

ArgumentNullException: sink가 null인 경우
InvalidOperationException: SDK를 초기화하지 않은 경우

Suspend

앱이 백그라운드로 전환됐음을 SDK에 알립니다. SDK를 초기화하지 않았으면 아무 동작도 하지 않습니다.

Unity에서는 HiveBootstrap이 자동으로 호출하므로 앱 코드가 직접 호출할 필요가 없습니다.

Unity

static void Suspend()

Resume

앱이 포그라운드로 복귀했음을 SDK에 알립니다. SDK를 초기화하지 않았으면 아무 동작도 하지 않습니다.

Unity에서는 HiveBootstrap이 자동으로 호출하므로 앱 코드가 직접 호출할 필요가 없습니다.

Unity

static void Resume()

Shutdown

SDK를 종료하고 초기화의 역순으로 자원을 해제합니다. 여러 번 호출해도 안전하며, 두 번째 호출부터는 아무 동작도 하지 않습니다.

종료는 OnSessionExpired를 발생시키지 않습니다. 저장된 인증 정보의 유효성에 대해 아무 판단도 내리지 않으므로, 이벤트 구독자는 앱을 정상 종료하는 것을 로그아웃으로 오해하면 안 됩니다. 저장해 둔 인증 정보는 다음 실행에서 그대로 복원할 수 있습니다.

Unity

static void Shutdown()

프로퍼티

IsInitialized

SDK 초기화 여부입니다. Initialize가 성공한 뒤 true가 되고, Shutdown 이후 또는 초기화 전에는 false입니다.

Unity

static bool IsInitialized { get; }

IHiveBuilder

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

HiveBootstrap.Initialize의 등록 클로저가 파라미터로 받는 타입입니다. 각 모듈 패키지가 제공하는 확장 메서드로 사용할 모듈을 등록합니다. 등록 메서드는 자기 자신을 반환하므로 이어서 호출할 수 있습니다.

클로저가 끝나면 등록이 확정되며, 이후에는 모듈을 추가할 수 없습니다. 사용할 모듈은 모두 이 한 번의 초기화 호출에서 등록하세요.

모듈 등록 메서드

모듈	등록 메서드	패키지
`auth`	`AddAuth()`, `AddToken()`	`com.com2usplatform.hiveaxyl.auth`
`auth.addon.apple`	`AddAppleSignIn()`	`com.com2usplatform.hiveaxyl.auth.addon.apple`
`auth.addon.credentialmanager`	`AddCredentialManager()`	`com.com2usplatform.hiveaxyl.auth.addon.credentialmanager`
`auth.addon.gpg`	`AddGooglePlayGames()`	`com.com2usplatform.hiveaxyl.auth.addon.gpg`
`auth.addon.steam`	`AddSteamAuth()`	`com.com2usplatform.hiveaxyl.auth.addon.steam`
`auth.addon.webauth`	`AddWebAuth()`	`com.com2usplatform.hiveaxyl.auth.addon.webauth`
`payments`	`AddPayments()`	`com.com2usplatform.hiveaxyl.payments`
`payments.addon.apple`	`AddStoreKit()`	`com.com2usplatform.hiveaxyl.payments.addon.apple`
`payments.addon.google`	`AddPlayBilling()`	`com.com2usplatform.hiveaxyl.payments.addon.google`
`payments.addon.steam`	`AddSteamMicrotransactions()`	`com.com2usplatform.hiveaxyl.payments.addon.steam`
`push`	`AddPush()`	`com.com2usplatform.hiveaxyl.push`
`push.addon.apns`	`AddAPNS()`	`com.com2usplatform.hiveaxyl.push.addon.apns`
`push.addon.applenotification`	`AddAppleNotification()`	`com.com2usplatform.hiveaxyl.push.addon.applenotification`
`push.addon.fcm`	`AddFCM()`	`com.com2usplatform.hiveaxyl.push.addon.fcm`
`mailbox`	`AddMailbox()`	`com.com2usplatform.hiveaxyl.mailbox`
`serviceaccess`	`AddServiceAccess()`	`com.com2usplatform.hiveaxyl.serviceaccess`
`storage`	`AddSecureStorage()`	`com.com2usplatform.hiveaxyl.storage`
`coupon`	`AddCoupon()`	`com.com2usplatform.hiveaxyl.coupon`
`analytics`	`AddAnalytics()`	`com.com2usplatform.hiveaxyl.analytics`
`tcb`	`AddTcb()`	`com.com2usplatform.hiveaxyl.tcb`

연결 서버

서버 API 모듈이 연결할 서버는 앱이 모듈을 등록할 때 정합니다. 서버 주소를 직접 지정하려면 AddXxx(string baseUrl) 오버로드를 사용하세요. 등록 메서드를 인자 없이 호출하면 모듈별로 아래 운영 서버에 연결합니다.

https://core-api.hiveaxyl.com: AddAuth(), AddToken(), AddServiceAccess()
https://commerce-api.hiveaxyl.com: AddPayments(), AddCoupon()
https://app-api.hiveaxyl.com: AddMailbox(), AddPush(), AddTcb()
https://data-api.hiveaxyl.com: AddAnalytics()

샌드박스 서버에 연결하는 오버로드는 결제 모듈의 AddPayments(sandbox: true)뿐이며, 이 오버로드는 결제 모듈의 연결 서버만 바꿉니다. 사용 방법은 Payments 모듈의 등록과 획득을 참조하세요.