콘텐츠로 이동

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

Hive Axyl SDK에 결제 모듈을 설치하고 초기화한 뒤, 결제 기능을 사용할 수 있도록 로그인 세션을 준비하는 방법을 안내합니다. 아직 Hive Axyl SDK를 설치하지 않았다면 먼저 Hive Axyl SDK를 설치하세요.

1. 결제 모듈 설치

아래 순서로 결제 모듈을 Hive Axyl SDK에 설치합니다.

1.1. 공통 모듈 선택

Hive Axyl을 사용하기 위한 최소 기능인 공통 모듈을 선택합니다.

  • com.com2usplatform.hiveaxyl.core: SDK를 시작할 때 호출하는 초기화와 다른 모듈이 공통으로 사용하는 기본 기능

1.2. 결제 기능을 위한 모듈 선택

결제 기능을 사용하기 위해 다음 모듈도 선택합니다.

  • com.com2usplatform.hiveaxyl.auth: 계정 생성, 로그인, 토큰 발급 등 로그인 세션 준비에 필요한 기능
  • com.com2usplatform.hiveaxyl.payments: 상품 목록 조회, 구매 기록, 결제 확정, 지급 결과 기록, 구매 복구 등 결제 흐름에 필요한 기능

인앱 상품 결제를 하는 주체는 앱 사용자입니다. 따라서 결제는 사용자 로그인 세션이 있어야 동작하며, 이를 위해 결제 모듈과 인증 모듈이 함께 필요합니다.

Note

Google, Steam 등 스토어 결제창 연동에는 제공자별 전용 플러그인을 추가로 설치합니다. 자세한 내용은 아래 결제 제공자별 연동 환경 구성을 참조하세요.

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.payments를 함께 추가합니다.

{
  "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.payments": "1.0.0"
  }
}

1.4. 설치 확인

다음 코드는 설치한 SDK와 인증, 결제 모듈의 네임스페이스가 정상 인식되는지 빠르게 확인하는 예시입니다.

using Hive.Axyl.Core;
using Hive.Axyl.Auth;
using Hive.Axyl.Payments;

아래 항목을 모두 만족하면 설치 단계가 완료됩니다.

  • Unity Package Manager에서 설치한 모듈이 Installed 상태로 표시

2. SDK 초기화

Method

Initialize

Hive Axyl SDK 초기화는 앱이 Hive Axyl SDK 기능을 사용하기 전에 한 번 수행하는 준비 단계입니다. 앱을 시작할 때 초기화를 호출해 인증, 결제, 푸시 등 Hive Axyl이 제공하는 기능을 사용할 준비를 합니다.

결제 모듈은 앱 전역 초기화의 builder에서 함께 등록합니다. 앱을 시작할 때 한 번만 호출하며 다음 순서로 진행합니다.

  1. 앱 정보 생성에서 만든 App ID를 확인합니다.
  2. App ID를 가지고 CoreConfig.CreateBuilder를 실행해 CoreConfig 객체를 생성합니다.
  3. HiveBootstrap.Initialize로 초기화를 실행합니다. builder에 AddAuth(), AddToken(), AddPayments()를 등록합니다.
    • 개발 중에는 AddPayments(sandbox: true)로 샌드박스 서버에, 실제 서비스에서는 AddPayments()로 운영 서버에 결제 모듈을 연결

결제 기능은 로그인한 사용자의 세션을 기준으로 동작합니다. 따라서 AddPayments()를 등록할 때 인증 모듈 AddAuth()와 토큰 모듈 AddToken()도 같은 Initialize 호출에서 함께 등록하세요.

sandbox: true는 결제 모듈의 연결 서버만 바꿉니다. 함께 등록한 인증 모듈과 토큰 모듈은 운영 서버에 연결합니다.

호출 파라미터

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

호출 예시

using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Auth;         // AddAuth, AddToken 확장
using Hive.Axyl.Payments;     // AddPayments 확장

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

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddAuth();                   // 계정·인증 (IAuthService)
    builder.AddToken();                  // 토큰 발급 (ITokenService)
    builder.AddPayments(sandbox: true);  // 결제 (IPaymentsService). 개발·테스트 환경. 실제 서비스 빌드는 AddPayments()
});

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

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

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

  • HiveCore.Resolve<IAuthService>()
  • HiveCore.Resolve<ITokenService>()
  • HiveCore.Resolve<IPaymentsService>()

응답 데이터

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

응답 예시

IAuthService auth = HiveCore.Resolve<IAuthService>();
ITokenService token = HiveCore.Resolve<ITokenService>();
IPaymentsService payments = HiveCore.Resolve<IPaymentsService>();

응답 상태

코드에서 HiveCore.Resolve<IAuthService>(), HiveCore.Resolve<ITokenService>(), HiveCore.Resolve<IPaymentsService>()를 호출했을 때 인스턴스를 정상적으로 반환하면 초기화와 모듈 등록을 완료한 것입니다.

초기화에 실패하는 경우 아래와 같이 예외가 발생합니다.

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

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

3. 로그인 세션 활성화

결제를 하는 주체는 앱 사용자입니다. 따라서 결제 기능은 사용자 로그인 세션이 있어야 동작합니다. 로그인 세션을 먼저 활성화한 다음 결제 메서드를 호출하세요.

4. AccountUuid 생성

AccountUuid는 결제한 사용자와 영수증 검증을 요청한 사용자가 같은지 확인하는 기준값입니다. 앱 서버가 보내는 영수증 검증 요청에는 반드시 담아야 하므로, 결제 흐름을 구현하기 전에 생성 방법을 정해 두세요. 서버는 AccountUuid를 생성하지 않으므로, 앱 클라이언트에서 로그인한 사용자의 playerId로 UUIDv5를 생성하세요.

  1. 앱에서 namespace UUID를 하나 정합니다.
  2. 로그인한 사용자의 playerId를 10진수 문자열로 변환합니다. 예를 들어 playerId가 1234567890이면 이름 문자열은 "1234567890"입니다.
  3. namespace UUID와 이름 문자열로 UUIDv5를 생성합니다.

같은 앱에서는 모든 플랫폼과 기기에서 같은 namespace UUID를 사용하세요. 같은 playerId에는 항상 같은 AccountUuid를 사용하고, 결제할 때마다 새 UUID를 만들지 마세요. Hive Axyl SDK 결제 메서드 요청의 AccountUuid는 선택 값이지만, Hive Axyl 서버가 결제한 사용자의 계정을 대조하게 하려면 위 방법으로 만든 값을 넣으세요.

다음 단계