Steam Microtransactions 결제 Add-on

Windows와 macOS에서 Steamworks SDK의 MicroTxnAuthorizationResponse_t 콜백을 받아 앱에 전달하는 Add-on입니다. 앱 사용자가 Steam 오버레이에서 결제를 승인하거나 취소한 결과를 가공하지 않고 그대로 전달합니다.

Steam 주문 생성과 결제 결과 저장은 Payments 모듈이 담당하고, 영수증 검증은 앱 서버가 Hive Axyl Server API로 요청합니다. 호출 순서는 InitiatePurchaseAsync()를 참조하세요.

모듈 정보

패키지: com.com2usplatform.hiveaxyl.payments.addon.steam
인터페이스: ISteamMicrotransactionsPlugin
네임스페이스: Hive.Axyl.Payments.Addon.Steam
등록 메서드: AddSteamMicrotransactions()
지원 플랫폼: Windows, macOS
최소 사양: macOS 15+, Unity 6000.0+

사전 준비

SDK는 Steam API를 초기화하지 않습니다. 앱이 시작할 때 SteamAPI.Init()을 한 번 호출하고, 승인 콜백이 전달되도록 매 프레임 SteamAPI.RunCallbacks()를 호출해야 합니다.

Steam API를 초기화하기 전에 콜백 수신을 시작하면 예외가 발생하지 않고 FailedPrecondition 코드를 담은 Failure로 끝납니다. Steamworks SDK를 사용할 수 있는 상태인지 확인하는 방법은 ISteamworksContext를 참조하세요.

등록과 획득

HiveBootstrap.Initialize의 등록 단계에서 Payments 모듈과 함께 등록한 뒤 HiveCore.TryResolve<T>()로 가져옵니다.

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Payments;
using Hive.Axyl.Payments.Addon.Steam;

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddPayments()
           .AddSteamMicrotransactions();
});

if (HiveCore.TryResolve<ISteamMicrotransactionsPlugin>(out var steam))
{
    // Windows · macOS 빌드에서만 실행되는 코드
}

Unity 에디터에서는 등록되지 않습니다

이 Add-on은 Windows 또는 macOS로 빌드한 플레이어에서만 등록됩니다. Unity 에디터에서는 플랫폼이 맞아도 등록되지 않으므로, HiveCore.Resolve<T>()를 쓰면 RegistrationNotFoundException이 발생합니다. 반드시 TryResolve<T>()로 확인한 뒤 사용하세요.

패키지 설치와 등록 절차는 Steam 결제 플러그인 설치를 참조하세요.

메서드 요약

모든 메서드는 마지막 파라미터로 CancellationToken ct = default를 받습니다. 호출 규약은 호출 컨텍스트를 참조하세요.

이 Add-on이 제공하는 메서드는 아래와 같습니다.

StartCallbackListenerAsync(): 결제 승인 콜백 수신 시작
StopCallbackListenerAsync(): 결제 승인 콜백 수신 중지

메서드

StartCallbackListenerAsync

Steamworks MicroTxnAuthorizationResponse_t 콜백 수신을 시작합니다. 수신하는 동안 승인 결과가 MicroTxnAuthorizationResponse 이벤트로 전달됩니다.

Unity

Task<SteamMicrotransactionsServiceStartCallbackListenerResult> StartCallbackListenerAsync(CancellationToken ct = default)

응답: StartCallbackListenerResponse

결과 케이스 — SteamMicrotransactionsServiceStartCallbackListenerResult

결과 케이스	와이어 코드	설명
`Success`	—	콜백 수신을 시작했습니다.
`AlreadyStarted`	`already_started`	콜백 수신이 이미 시작되어 있습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. `Problem`의 HiveError로 원인을 확인합니다. Steam API를 초기화하지 않았다면 `Code`는 `FailedPrecondition`, `ExternalCode`는 `STEAMWORKS_NOT_INITIALIZED`입니다.

발생 예외

ObjectDisposedException: 플러그인을 해제한 뒤 호출한 경우

호출 예시

Unity

using Hive.Axyl.Payments.Addon.Steam;

steam.MicroTxnAuthorizationResponse += response =>
{
    if (response.Authorized)
    {
        // 앱 사용자가 결제를 승인했습니다. RecordStorePurchaseAsync로 결제 결과를 저장합니다.
    }
    else
    {
        // 앱 사용자가 결제를 취소했습니다.
    }
};

var result = await steam.StartCallbackListenerAsync();

switch (result)
{
    case SteamMicrotransactionsServiceStartCallbackListenerResult.Success:
    case SteamMicrotransactionsServiceStartCallbackListenerResult.AlreadyStarted:
        // 콜백을 받을 준비가 됐습니다. InitiatePurchaseAsync로 결제를 시작합니다.
        break;

    default:
        // Steam API를 초기화하지 않았다면 Failure로 끝납니다.
        break;
}

구현 절차는 Steam 결제 승인 콜백 수신을 참조하세요.

StopCallbackListenerAsync

콜백 수신을 중지합니다. 수신 중이 아닐 때 호출해도 오류가 아닙니다. 정리 작업이므로 ct가 이미 취소된 상태여도 수신을 중지합니다.

Unity

Task<SteamMicrotransactionsServiceStopCallbackListenerResult> StopCallbackListenerAsync(CancellationToken ct = default)

응답: StopCallbackListenerResponse

결과 케이스 — SteamMicrotransactionsServiceStopCallbackListenerResult

결과 케이스	와이어 코드	설명
`Success`	—	콜백 수신을 중지했습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. `Problem`의 HiveError로 원인을 확인합니다.

발생 예외

ObjectDisposedException: 플러그인을 해제한 뒤 호출한 경우

구현 절차는 Steam 콜백 수신 해제를 참조하세요.

이벤트

MicroTxnAuthorizationResponse

앱 사용자가 Steam 오버레이에서 결제를 승인하거나 취소한 뒤 Steamworks가 MicroTxnAuthorizationResponse_t 콜백을 전달할 때 발생합니다. StartCallbackListenerAsync()로 수신하는 동안에만 발생하며, 엔진 메인 스레드에서 호출되므로 핸들러 안에서 엔진 API를 사용해도 됩니다.

Unity

event Action<SteamMicroTxnResponse> MicroTxnAuthorizationResponse

파라미터	타입	설명
—	SteamMicroTxnResponse	승인 콜백의 원본 데이터입니다.

구현 절차는 MicroTxnAuthorizationResponse 이벤트로 결제 승인 여부 수신을 참조하세요.

데이터 타입

StartCallbackListenerResponse

필드가 없습니다.

SteamMicroTxnResponse

Steamworks MicroTxnAuthorizationResponse_t 콜백의 원본 데이터입니다. 값을 가공하지 않고 전달하므로 의미 해석은 앱이 담당합니다. AppId와 OrderId는 Steamworks 네이티브 구조체와 같은 부호 없는 정수 타입을 사용합니다.

프로퍼티	타입	필수 여부	설명
`AppId`	`uint`	Required	Steam AppID인 `m_unAppID` 값입니다. 공개 정보입니다.
`OrderId`	`ulong`	Required	`m_ulOrderID` 값입니다. 주문을 만들 때 `InitTxn`에 전달된 주문 ID가 승인 콜백으로 돌아온 값이며, Steam이 발급하는 거래 ID인 `transid`와 다릅니다. 민감 정보이므로 SDK 로그에는 마지막 4자리만 표시됩니다.
`Authorized`	`bool`	Required	`m_bAuthorized` 값입니다. 앱 사용자가 Steam 오버레이에서 결제를 승인했으면 `true`, 취소했으면 `false`입니다.

StopCallbackListenerResponse

필드가 없습니다.