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

쿠폰 기능을 사용하려면 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.coupon: 앱 사용자가 입력한 쿠폰 코드를 사용 처리하고 쿠폰에 설정한 아이템을 담은 지급 우편을 발송하는 기능

쿠폰을 사용하는 주체는 앱 사용자입니다. 따라서 쿠폰은 사용자 로그인 세션이 있어야 동작하며, 로그인 세션을 준비하려면 인증 모듈이 필요합니다. 쿠폰에 설정한 아이템은 지급 우편에 담겨 쿠폰을 사용한 사용자의 앱 내 우편함으로 전달됩니다. 사용자가 앱에서 지급 우편을 열어 보고 아이템을 받으려면 앱에 우편함 기능이 있어야 하므로 우편함 모듈도 필요합니다.

1.3. 모듈 설치

모듈은 SDK 설치와 같은 방법으로 설치합니다. Hive Axyl SDK는 Scoped Registry로만 설치하므로, SDK를 설치할 때 등록한 Hive Axyl Scoped Registry는 그대로 두고 쿠폰 기능에 필요한 모듈만 dependencies에 추가합니다.

Packages/manifest.json의 dependencies에는 com.com2usplatform.hiveaxyl.core와 함께 로그인 세션 준비용 com.com2usplatform.hiveaxyl.auth, 지급 우편의 조회와 읽음 처리에 쓰는 com.com2usplatform.hiveaxyl.mailbox, 쿠폰 기능 모듈인 com.com2usplatform.hiveaxyl.coupon이 있어야 합니다. 직접 코드로 구현하기나 우편함 모듈 설치에서 이미 설치한 모듈이 있다면 기존 항목은 지우지 말고 아직 없는 모듈만 추가하세요.

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.mailbox": "1.0.0",
    "com.com2usplatform.hiveaxyl.coupon": "1.0.0"
  }
}

1.4. 설치 확인

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

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Auth;
using Hive.Axyl.Mailbox;
using Hive.Axyl.Coupon;

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

2. SDK 초기화

Initialize

Hive Axyl SDK 초기화는 앱이 쿠폰 기능을 사용하기 전에 한 번 거치는 준비 단계입니다. 앱을 시작할 때 초기화 메서드를 호출하면서 쿠폰 모듈과 인증, 우편함 모듈을 함께 등록합니다.

앱 정보 생성에서 만든 App ID를 확인하세요.
App ID로 CoreConfig.CreateBuilder를 실행해 CoreConfig 객체를 만드세요.
HiveBootstrap.Initialize로 초기화하고 builder에 AddAuth(), AddToken(), AddMailbox(), AddCoupon()을 등록하세요.

초기화 메서드는 앱 실행 중 한 번만 호출합니다. 4단계. SDK 초기화나 우편함 모듈 설치에서 이미 초기화 코드를 작성했다면 새로 호출하지 말고, 기존 Initialize 호출의 builder에 아직 등록하지 않은 모듈만 추가하세요.

호출 파라미터

필드명	타입	필수 여부	설명
`config`	`CoreConfig`	Required	App ID를 담은 `CoreConfig` 객체입니다. `CoreConfig.CreateBuilder`로 생성합니다.
`assemble`	`Action<IHiveBuilder>`	Required	사용할 기능 모듈을 등록하는 빌더 콜백입니다. 쿠폰 기능을 사용하려면 `builder.AddAuth()`, `builder.AddToken()`, `builder.AddMailbox()`, `builder.AddCoupon()`을 포함합니다.

호출 예시

아래는 Initialize의 두 번째 인자인 assemble 콜백에서 쿠폰 기능에 필요한 모듈을 등록하는 예시입니다. 쿠폰은 로그인한 사용자 세션을 기준으로 동작하므로 AddCoupon()을 등록하는 Initialize 호출에서 AddAuth()와 AddToken()도 함께 등록합니다. 두 메서드는 모두 com.com2usplatform.hiveaxyl.auth 모듈이 제공하며, 로그인과 토큰 발급으로 로그인 세션을 준비하는 데 필요합니다. 지급 우편 조회와 읽음 처리에 필요한 AddMailbox()도 같은 호출에서 등록합니다.

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Auth;         // AddAuth, AddToken 확장
using Hive.Axyl.Mailbox;      // AddMailbox 확장
using Hive.Axyl.Coupon;       // AddCoupon 확장

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

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddAuth();      // 계정·인증 (IAuthService)
    builder.AddToken();     // 토큰 발급 (ITokenService)
    builder.AddMailbox();   // 우편함 (IMailboxService)
    builder.AddCoupon();    // 쿠폰 (ICouponService)
});

등록한 모듈은 이후 아래와 같이 가져와 사용합니다.

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

응답 데이터

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

응답 예시

Unity

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

응답 상태

초기화와 모듈 등록이 끝났는지는 HiveCore.Resolve<T>() 호출 결과로 확인합니다. HiveCore.Resolve<IAuthService>(), HiveCore.Resolve<ITokenService>(), HiveCore.Resolve<IMailboxService>(), HiveCore.Resolve<ICouponService>()가 모두 예외 없이 인스턴스를 반환하면 완료된 것입니다. 등록하지 않은 모듈을 Resolve<T>()로 가져올 때 발생하는 예외와 오류 처리의 공통 원칙은 공통 오류 처리를 참조하세요.

아래 경우에는 초기화할 때 예외가 발생합니다. 이 예외는 메서드 호출 결과로 받는 Failure와 달리 초기화를 즉시 실패시킵니다.

ArgumentNullException: config에 null을 넘긴 경우
InvalidOperationException: 이미 초기화를 완료한 상태에서 초기화 메서드를 다시 호출한 경우
DllNotFoundException: Windows에서 SDK가 사용하는 네이티브 플러그인을 불러오지 못한 경우. 원인과 대응 방법은 Windows 실행 선행 조건 참조

쿠폰은 사용자 로그인 세션이 있어야 동작합니다. 쿠폰을 사용하는 주체가 앱 사용자이고, 쿠폰에 설정한 아이템을 담은 지급 우편도 그 사용자의 우편함으로 발송되기 때문입니다. 로그인 세션을 먼저 활성화한 다음 쿠폰 사용 메서드를 호출하세요.

다음 단계

쿠폰 지급 구현 순서

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

1. 쿠폰 모듈 설치

1.1. 공통 모듈 선택

1.2. 쿠폰 기능을 위한 모듈 선택

1.3. 모듈 설치

1.4. 설치 확인

2. SDK 초기화

호출 파라미터

호출 예시

응답 데이터

응답 예시

응답 상태

3. 로그인 세션 활성화

다음 단계