콘텐츠로 이동

4단계. SDK 초기화

Hive Axyl SDK 초기화는 앱이 Hive Axyl SDK 기능을 사용하기 전에 거치는 준비 단계입니다. 앱을 시작할 때 초기화를 호출해 인증, 결제, 푸시 등 Hive Axyl 기능을 사용할 준비를 합니다. 초기화는 앱 실행 중 한 번만 수행하므로 중복 호출하지 않습니다.

초기화

Method

Initialize

초기화를 실행해 앱 전역에서 공통으로 사용하는 Hive Axyl SDK 런타임을 준비합니다. 앱을 시작할 때 한 번만 호출합니다.

  1. 앱 정보 생성에서 만든 App ID를 확인합니다.
  2. App ID로 CoreConfig.CreateBuilder를 실행해 CoreConfig 객체를 생성합니다.
  3. HiveBootstrap.Initialize로 초기화를 실행합니다. assemble 콜백을 사용해 인증 모듈(AddAuth), 토큰 모듈(AddToken), 보안 저장소 모듈(AddSecureStorage)을 등록해야 합니다.

호출 파라미터

필드명 타입 필수 여부 설명
config CoreConfig Required App ID를 담은 CoreConfig 객체입니다. CoreConfig.CreateBuilder로 생성합니다.
assemble Action<IHiveBuilder> Required 사용할 기능 모듈을 등록하는 빌더 콜백입니다.

호출 예시

시작하기에서는 로그인, 로그아웃, 계정 삭제만 안내하므로 이를 위해 필요한 인증, 토큰, 보안 저장소 모듈만 등록해 초기화를 실행합니다.

using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Auth;   // AddAuth, AddToken 확장
using Hive.Axyl.Storage;   // AddSecureStorage 확장

// 앱 시작 시 한 번만 호출합니다 (예: 첫 씬의 MonoBehaviour.Start).
var config = CoreConfig.CreateBuilder("{appId}").Build();

HiveBootstrap.Initialize(config, builder =>
{
    // 사용할 모듈을 등록합니다.
    builder
        .AddAuth()    // 계정·인증 (IAuthService)
        .AddToken()   // 토큰 발급 (ITokenService)
        .AddSecureStorage();  // 기기 보안 저장소 (ISecureStorage)
});

사용할 기능 모듈을 Initialize의 두 번째 인자인 assemble 콜백에서 함께 등록합니다. 위 예시의 builder는 이 콜백이 넘겨주는 빌더 객체입니다. 시작하기에서는 로그인을 구현하므로, 인증 모듈(AddAuth)과 토큰 모듈(AddToken)을 등록해야 합니다. AddToken은 로그인 결과로 받은 authorizationCode를 입력값으로 사용해 실제 토큰을 발급할 때 필요하므로 인증 모듈과 항상 함께 등록합니다. 여기에 더해 로그아웃과 계정 삭제에서 기기에 저장한 토큰을 정리하기 위해 보안 저장소 모듈(AddSecureStorage)도 등록합니다.

등록한 모듈은 이후 HiveCore.Resolve<IAuthService>(), HiveCore.Resolve<ITokenService>()로 가져와 사용합니다. 보안 저장소는 등록되지 않는 환경이 있으므로 HiveCore.TryResolve<ISecureStorage>(out var storage)로 가져옵니다.

보안 저장소 모듈 등록

AddSecureStorage는 모듈 설치에서 설치한 com.com2usplatform.hiveaxyl.storage 모듈을 등록합니다. 로그아웃과 계정 삭제에서 기기에 저장한 토큰을 지울 때 HiveCore.TryResolve<ISecureStorage>(out var storage)로 이 모듈을 가져와 사용하므로, 초기화 시점에 함께 등록해 둡니다.

AddSecureStorage는 기기 보안 저장소가 있는 플랫폼에서만 ISecureStorage를 등록합니다. Android, iOS, macOS, Windows 플레이어 빌드가 여기에 해당합니다. Unity 에디터에서는 등록하지 않으므로 HiveCore.Resolve<ISecureStorage>()가 RegistrationNotFoundException을 발생시킵니다. 에디터에서 함께 실행하는 코드라면 아래처럼 HiveCore.TryResolve<T>()로 등록 여부를 먼저 확인합니다.

using Hive.Axyl.Core;
using Hive.Axyl.Storage;

if (HiveCore.TryResolve<ISecureStorage>(out var storage))
{
    // 보안 저장소를 사용할 수 있는 플랫폼입니다.
}

여러 기능 모듈 함께 등록

초기화는 앱 실행 중 단 한 번만 호출합니다. 인증, 결제, 우편함, 서비스 접근 제어, 애널리틱스 기능을 함께 사용하는 앱은 해당 모듈을 함께 등록해 초기화합니다.

using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Auth;   // 인증 (AddAuth, AddToken 확장)
using Hive.Axyl.Storage;      // 기기 보안 저장소
using Hive.Axyl.Payments;     // 결제
using Hive.Axyl.Mailbox;      // 우편함
using Hive.Axyl.ServiceAccess; // 서비스 접근 제어
using Hive.Axyl.Analytics;     // 애널리틱스

// 앱 시작 시 한 번만 호출합니다 (예: 첫 씬의 MonoBehaviour.Start).
var config = CoreConfig.CreateBuilder("{appId}").Build();

HiveBootstrap.Initialize(config, builder =>
{
    // 사용할 모듈을 등록합니다.
    builder
        .AddAuth()    // 계정·인증 (IAuthService)
        .AddToken()   // 토큰 발급 (ITokenService)
        .AddSecureStorage()  // 기기 보안 저장소 (ISecureStorage)
        .AddPayments()  // 결제 (IPaymentsService)
        .AddMailbox()   // 우편함 (IMailboxService)
        .AddServiceAccess() // 서비스 접근 제어 (IServiceAccessService)
        .AddAnalytics();    // 애널리틱스 (IAnalyticsService)
});

응답 데이터

성공 시 별도 반환 데이터가 없습니다.

응답 예시

// 성공 시 예외 없이 다음 줄로 진행됩니다.
IAuthService auth = HiveCore.Resolve<IAuthService>();
ITokenService token = HiveCore.Resolve<ITokenService>();

// 보안 저장소는 플랫폼에 따라 등록되지 않으므로 TryResolve로 확인합니다.
bool hasStorage = HiveCore.TryResolve<ISecureStorage>(out var storage);

응답 상태

코드에서 HiveCore.Resolve<IAuthService>(), HiveCore.Resolve<ITokenService>()를 호출해 예외 없이 모듈 객체를 반환받으면 초기화와 모듈 등록이 완료된 것입니다. 반환되는 모듈 객체는 IAuthService, ITokenService 인스턴스입니다. 보안 저장소는 Unity 에디터에서 의도적으로 등록되지 않으므로 Resolve 대신 TryResolve로 확인합니다.

HiveBootstrap.Initialize 호출은 다음 조건에서 예외를 발생시킵니다.

  • config에 null을 넘기면 ArgumentNullException이 발생
  • 이미 초기화를 완료한 상태에서 초기화 메서드를 다시 호출하면 InvalidOperationException이 발생
  • Windows에서 네이티브 플러그인을 로드하지 못하면 DllNotFoundException이 발생. Windows 실행 선행 조건에 따라 Microsoft Visual C++ 2015-2022 재배포 가능 패키지(x64)를 설치했는지 확인하세요. 예외 메시지에 설치 파일 링크가 함께 담깁니다.

위 예외는 메서드 호출 결과의 Failure와 달리 초기 설정을 즉시 실패시키는 경우입니다. Resolve<T>()의 등록 누락 예외를 포함한 공통 원칙은 공통 오류 처리를 참조하세요.

다음 단계

로그인할 계정을 생성하려면 계정 생성을 참조하세요.