모듈 설치, 초기화, 로그인

우편함을 사용하려면 Hive Axyl SDK에 우편함 모듈을 설치하고 초기화해야 합니다. 아직 Hive Axyl SDK를 설치하지 않았다면 먼저 Hive Axyl SDK를 설치하세요.

1. 우편함 모듈 설치

우편함 모듈은 공통 모듈, 인증 모듈과 함께 설치합니다. 앱을 다시 시작해도 로그인 상태를 유지하려면 저장소 모듈도 함께 설치합니다.

1.1. 공통 모듈 선택

공통 모듈은 Hive Axyl을 사용하기 위한 최소 기능이므로 반드시 선택합니다.

com.com2usplatform.hiveaxyl.core: SDK 초기화와 다른 모듈이 공통으로 사용하는 기본 기능

1.2. 우편함 기능을 위한 모듈 선택

우편함 기능에는 인증 모듈과 우편함 모듈이 추가로 필요합니다. 저장소 모듈은 로그인 상태 유지를 직접 구현할 때 선택합니다.

모듈	필요 여부	설명
`com.com2usplatform.hiveaxyl.auth`	필수	계정 생성, 로그인, 토큰 발급 등 로그인 세션 준비에 필요합니다.
`com.com2usplatform.hiveaxyl.mailbox`	필수	로그인한 사용자 세션을 기준으로 우편 발송, 발신 우편 조회, 수신 우편 조회, 우편 회수와 삭제 등 우편함 기능을 제공합니다.
`com.com2usplatform.hiveaxyl.storage`	선택	로그인 토큰처럼 노출되면 안 되는 값을 사용자 기기에 암호화해 저장하고 다시 불러오는 보안 저장소를 제공합니다.

우편을 발송, 수신, 회수, 삭제하는 주체는 앱 사용자입니다. 따라서 우편함은 사용자 로그인 세션이 있어야 동작하며, 이를 위해 우편함과 인증 모듈이 함께 필요합니다.

Hive Axyl SDK는 로그인 세션을 앱이 실행되는 동안 메모리에만 유지합니다. 그래서 앱을 다시 시작하면 사용자가 다시 로그인해야 합니다. 이를 피하려면 앱이 로그인 토큰을 기기에 저장해 두었다가 다음 실행에서 불러와야 하고, 이때 사용할 안전한 저장 공간을 저장소 모듈이 제공합니다. 저장하고 불러오는 코드는 앱이 직접 작성합니다.

1.3. 모듈 설치

모듈 설치 방법은 SDK 설치 방법과 동일합니다. Hive Axyl SDK는 Scoped Registry로만 설치하므로, SDK를 설치할 때 등록한 Hive Axyl Scoped Registry에 우편함에 필요한 모듈을 추가로 선언합니다.

Packages/manifest.json의 dependencies에 com.com2usplatform.hiveaxyl.core와 더불어 로그인 세션 준비용 com.com2usplatform.hiveaxyl.auth, 우편함 기능 모듈인 com.com2usplatform.hiveaxyl.mailbox를 함께 추가합니다. 로그인 상태 유지를 구현한다면 com.com2usplatform.hiveaxyl.storage도 추가합니다.

manifest.json

{
  "scopedRegistries": [
    {
      "name": "Hive Axyl",
      "url": "https://package.openupm.com",
      "scopes": [
        "com.com2usplatform.hiveaxyl"
      ]
    }
  ],
  "dependencies": {
    "com.com2usplatform.hiveaxyl.core": "1.0.0",
    "com.com2usplatform.hiveaxyl.auth": "1.0.0",
    "com.com2usplatform.hiveaxyl.storage": "1.0.0",
    "com.com2usplatform.hiveaxyl.mailbox": "1.0.0"
  }
}

1.4. 설치 확인

설치한 SDK와 인증, 우편함 모듈의 네임스페이스가 정상 인식되는지 아래 코드로 확인합니다.

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Auth;
using Hive.Axyl.Mailbox;
using Hive.Axyl.Storage;   // 저장소 모듈을 설치했을 때만 필요

Unity Package Manager에서 설치한 모듈이 Installed 상태로 표시되면 설치 단계가 완료됩니다.

2. SDK 초기화

Initialize

Hive Axyl SDK 초기화는 앱이 우편함 기능을 사용하기 전에 한 번 거치는 준비 단계입니다. 앱을 시작할 때 초기화를 호출해 프로젝트 식별 정보와 런타임 구성을 메모리에 올리고, 인증과 우편함 기능을 사용할 준비를 합니다.

우편함 모듈은 앱 전역 초기화의 builder에서 함께 등록합니다. 앱을 시작할 때 한 번만 호출합니다.

앱 정보 생성에서 만든 App ID를 확인하세요.
App ID로 CoreConfig.CreateBuilder를 실행해 CoreConfig 객체를 만드세요.
HiveBootstrap.Initialize로 초기화하고 builder에 AddAuth(), AddToken(), AddMailbox()를 등록하세요. 저장소 모듈을 설치했다면 AddSecureStorage()도 함께 등록하세요.

우편함 기능은 로그인한 사용자 세션을 기준으로 동작합니다. 따라서 AddMailbox()를 등록할 때 인증 모듈의 AddAuth()와 AddToken()도 같은 Initialize 호출에서 함께 등록합니다. AddAuth()와 AddToken()은 모두 com.com2usplatform.hiveaxyl.auth 모듈이 제공하므로 별도 모듈을 설치할 필요가 없습니다. 저장소 모듈을 설치했다면 AddSecureStorage()도 같은 호출에서 등록합니다.

보안 저장소를 사용할 수 있는 환경

AddSecureStorage()는 Android, iOS, macOS, Windows 빌드에서만 보안 저장소를 등록합니다. Unity 에디터에서 실행할 때와 그 밖의 빌드에서는 등록하지 않습니다. 기기마다 보안 저장 방식이 다르고, Hive Axyl SDK는 위 네 가지 운영체제의 저장 방식만 지원하기 때문입니다.

등록되지 않은 환경에서 HiveCore.Resolve<ISecureStorage>()를 호출하면 요청한 기능이 등록되어 있지 않다는 뜻의 RegistrationNotFoundException이 발생합니다. 자세한 내용은 공통 오류 처리를 참조하세요. 에디터에서도 앱을 실행한다면 예외 대신 등록 여부를 true 또는 false로 돌려주는 HiveCore.TryResolve<ISecureStorage>(out var storage)로 먼저 확인하세요.

보안 저장소를 쓸 수 없어도 우편함 메서드는 그대로 동작합니다. 로그인 세션은 앱이 실행되는 동안 메모리에 유지되기 때문입니다. 대신 로그인 상태를 기기에 저장해 둘 수 없으므로, 그 환경에서는 앱을 다시 시작할 때마다 사용자가 다시 로그인해야 합니다.

호출 파라미터

필드명	타입	필수 여부	설명
`config`	`CoreConfig`	Required	App ID를 담은 객체입니다. `CoreConfig.CreateBuilder`로 생성합니다.
`assemble`	빌더 콜백	Required	사용할 기능 모듈을 등록하는 빌더 콜백입니다. 우편함 기능을 사용하려면 `builder.AddAuth()`, `builder.AddToken()`, `builder.AddMailbox()`를 포함합니다. 저장소 모듈을 설치했다면 `builder.AddSecureStorage()`도 포함합니다.

호출 예시

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Auth;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Storage;      // AddSecureStorage 확장
using Hive.Axyl.Mailbox;      // AddMailbox 확장

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

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddAuth();            // 계정·인증 (IAuthService)
    builder.AddToken();           // 토큰 발급 (ITokenService)
    builder.AddMailbox();         // 우편함 (IMailboxService)
    builder.AddSecureStorage();   // 보안 저장소 (ISecureStorage). 로그인 상태 유지를 구현할 때만 등록
});

사용할 기능 모듈을 Initialize의 두 번째 인자(builder)에서 함께 등록합니다.

AddToken()은 로그인 결과로 받은 authorizationCode를 입력값으로 사용해 실제 토큰을 발급할 때 필요하므로 인증 모듈과 항상 함께 등록합니다.

등록한 모듈은 이후 아래와 같이 호출해서 사용합니다.

HiveCore.Resolve<IAuthService>()
HiveCore.Resolve<ITokenService>()
HiveCore.Resolve<IMailboxService>()

보안 저장소는 등록되지 않는 환경이 있으므로 HiveCore.Resolve<ISecureStorage>() 대신 HiveCore.TryResolve<ISecureStorage>(out var storage)로 가져옵니다. true를 반환하면 storage에 보안 저장소가 담깁니다.

응답 데이터

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

응답 예시

Unity

IAuthService auth = HiveCore.Resolve<IAuthService>();
ITokenService token = HiveCore.Resolve<ITokenService>();
IMailboxService mailbox = HiveCore.Resolve<IMailboxService>();

응답 상태

초기화와 모듈 등록의 완료 여부는 HiveCore.Resolve<T>() 호출 결과로 확인합니다. HiveCore.Resolve<IAuthService>(), HiveCore.Resolve<ITokenService>(), HiveCore.Resolve<IMailboxService>()가 모두 인스턴스를 반환하면 완료된 것입니다. 보안 저장소를 등록했다면 HiveCore.TryResolve<ISecureStorage>(out var storage)가 true를 반환하는지로 확인합니다. 보안 저장소를 사용할 수 있는 환경이 아니면 false를 반환합니다.

초기화에 실패하면 다음 예외가 발생합니다.

config에 null을 전달하면 ArgumentNullException이 발생
이미 초기화를 완료한 상태에서 초기화 메서드를 다시 호출하면 InvalidOperationException이 발생

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

Windows 빌드 사전 조건

Windows 빌드에서는 SDK가 C# 코드에서 호출하는 OS 전용 바이너리(네이티브 플러그인)를 함께 불러옵니다. 이 파일을 불러오지 못하면 초기화할 때 DllNotFoundException이 발생합니다. 원인은 두 가지입니다.

네이티브 플러그인 파일이 빌드 결과물에 포함되지 않은 경우
앱을 실행하는 PC에 Microsoft Visual C++ 2015-2022 재배포 가능 패키지(x64)가 설치되지 않은 경우. 이 패키지는 네이티브 플러그인이 동작하는 데 필요한 Microsoft 런타임 라이브러리 모음으로, Windows가 기본 제공하지 않고 Unity도 빌드 결과물에 함께 넣지 않습니다.

따라서 Windows로 출시할 때는 앱 설치 프로그램에 이 재배포 가능 패키지를 포함하거나 최초 실행할 때 사용자에게 설치를 안내하세요. 다운로드 링크는 예외 메시지에도 포함되어 있습니다.

3. 로그인 세션 활성화

우편함은 사용자 로그인 세션이 있어야 동작합니다. 우편을 주고받고 회수하거나 삭제하는 주체가 앱 사용자이기 때문입니다. 로그인 세션을 먼저 활성화한 다음 우편함 메서드를 호출하세요.

다음 단계

우편 발송

더 알아보기

우편함 사용 예시