Steam 로그인 Add-on

Windows와 macOS에서 Steamworks SDK의 ISteamUser::GetAuthTicketForWebApi로 Steam 웹 API 인증 티켓을 발급받는 Add-on입니다. 발급받은 티켓을 Auth 모듈의 LoginProviderAsync()에 넘기면 Hive Axyl 인증 서버가 티켓을 Steam에 확인해 Steam 계정으로 로그인합니다.

모듈 정보

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

사전 준비

SDK는 Steam API를 초기화하지 않습니다. 앱이 시작할 때 SteamAPI.Init()을 한 번 호출하고, Steamworks 콜백이 전달되도록 매 프레임 SteamAPI.RunCallbacks()를 호출해야 합니다. 개발 중에 Steam 클라이언트 밖에서 실행한다면 steam_appid.txt 파일도 함께 준비하세요.

Steam API를 초기화하지 않았거나 Steam 클라이언트가 실행 중이 아닐 때 티켓을 요청하면 예외가 발생하지 않고 Code가 FailedPrecondition인 Failure로 끝납니다. 초기화 방법은 Steamworks 초기화를, Steamworks SDK를 사용할 수 있는 상태인지 확인하는 방법은 ISteamworksContext를 참조하세요.

등록과 획득

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

Unity

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

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddAuth()
           .AddToken()
           .AddSteamAuth();
});

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

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

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

패키지 설치와 등록 절차는 모듈 설치 및 초기화를 참조하세요.

메서드 요약

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

GetAuthTicketForWebApiAsync(): Steam 웹 API 인증 티켓 발급
ReleaseTicket(): 발급받은 티켓을 Steam에 반납

메서드

GetAuthTicketForWebApiAsync

Steam 웹 API 인증 티켓을 발급받아 16진수 문자열로 반환합니다. Steam에서 티켓 핸들을 받고 발급 결과 콜백을 기다린 뒤, 티켓 값을 16진수로 인코딩합니다.

여러 번 동시에 호출해도 SDK는 각 호출을 서로 독립적으로 처리합니다. 다만 같은 티켓 요청이 이미 진행 중이면 Steam이 거부해 FailedPrecondition으로 끝날 수 있으므로, 결과를 받은 뒤에 다시 호출하세요.

Unity

Task<SteamServiceGetAuthTicketForWebApiResult> GetAuthTicketForWebApiAsync(GetAuthTicketForWebApiRequest request, CancellationToken ct = default)

요청: GetAuthTicketForWebApiRequest
응답: TicketResponse

결과 케이스 — SteamServiceGetAuthTicketForWebApiResult

결과 케이스	와이어 코드	설명
`Success`	—	티켓을 발급받았습니다. `Data.TicketHex`에 티켓이 담깁니다.
`NotAuthenticated`	`not_authenticated`	Steam 클라이언트에 로그인되어 있지 않습니다. 앱 사용자에게 Steam 로그인을 안내하세요.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. `Problem`의 HiveError로 원인을 확인합니다. Steam API를 초기화하지 않았거나 Steam 클라이언트가 실행 중이 아니면 `Code`는 `FailedPrecondition`입니다. 같은 티켓 요청이 이미 진행 중이라 Steam이 거부한 경우에도 `FailedPrecondition`이며, 이때 `ExternalCode`는 `k_EResultDuplicateRequest`입니다. Steam 서버에 연결하지 못했다면 `Unavailable`, `ct`로 취소했거나 요청 중에 플러그인이 해제됐다면 `Cancelled`입니다.

발생 예외

ArgumentNullException: request가 null인 경우
ObjectDisposedException: HiveCore.Shutdown()이나 Dispose()로 플러그인이 해제된 뒤 호출한 경우

호출 예시

Unity

using Hive.Axyl.Auth.Addon.Steam;
using Hive.Axyl.Core;

var request = new GetAuthTicketForWebApiRequest
{
    Identity = identity,   // 티켓을 검증할 때 사용하는 identity와 같은 값
};

var result = await steam.GetAuthTicketForWebApiAsync(request);

switch (result)
{
    case SteamServiceGetAuthTicketForWebApiResult.Success success:
        string providerToken = success.Data.TicketHex;   // LoginProviderAsync의 ProviderToken
        break;

    case SteamServiceGetAuthTicketForWebApiResult.NotAuthenticated:
        // Steam 클라이언트에 로그인하도록 안내합니다.
        break;

    case SteamServiceGetAuthTicketForWebApiResult.Failure failure:
        HiveError error = failure.Problem;
        break;

    default:
        // 처리하지 않은 결과와 UnknownOutcome
        break;
}

티켓을 발급받으면 TicketHex를 ProviderToken으로 넣어 LoginProviderAsync()를 호출합니다. ProviderUserId에 넣을 Steam ID64는 이 Add-on이 제공하지 않으므로 앱이 Steamworks에서 직접 읽어 옵니다. 구현 절차는 Windows와 macOS에서 Steam 자격 증명 획득을 참조하세요.

ReleaseTicket

발급받은 티켓을 Steam에 반납합니다. Steam은 동시에 보유할 수 있는 티켓 수를 제한하므로, 티켓을 반납하지 않고 계속 발급받으면 이후 발급 요청이 실패할 수 있습니다.

Unity 메인 스레드에서 호출하세요. 알 수 없는 티켓이나 이미 반납한 티켓을 넘기면 아무 동작도 하지 않으며, 플러그인이 해제된 뒤에 호출해도 마찬가지입니다.

Unity

void ReleaseTicket(string ticketHex)

파라미터	타입	필수 여부	설명
`ticketHex`	`string`	Required	GetAuthTicketForWebApiAsync()의 `Success` 결과에서 받은 `TicketHex` 값입니다.

로그인 결과를 받은 뒤에 반납하세요

Hive Axyl 인증 서버는 LoginProviderAsync()를 처리하면서 티켓을 Steam에 확인합니다. 그 전에 티켓을 반납하면 Steam이 티켓을 무효로 판단해 로그인이 실패합니다. 로그인이 성공했든 실패했든 결과를 받은 뒤에 호출하세요.

반납하지 않은 티켓은 플러그인이 해제될 때 한꺼번에 정리됩니다. 이는 종료할 때의 안전장치일 뿐이므로, 로그인할 때마다 이 메서드로 반납하세요.

발생 예외

ArgumentNullException: ticketHex가 null인 경우

구현 절차는 인증 티켓 반납을 참조하세요.

데이터 타입

GetAuthTicketForWebApiRequest

필드	타입	필수 여부	설명
`Identity`	`string`	Required	Steamworks의 `GetAuthTicketForWebApi`에 그대로 전달하는 identity 문자열입니다. 티켓을 검증할 때도 같은 identity 값을 사용해야 합니다. 빈 문자열이면 Steamworks 기본 identity를 사용합니다.

TicketResponse

필드	타입	필수 여부	설명
`TicketHex`	`string`	Required	Steam 웹 API 인증 티켓을 소문자 16진수로 인코딩한 값입니다. `LoginProviderAsync()` 요청의 `ProviderToken`으로 사용하며, 한 번만 사용하기를 권장합니다.