세션 활성화하기

토큰 발급하기 단계에서 발급한 액세스 토큰과 리프레시 토큰을 세션에 등록하면 로그인이 완료됩니다.

세션 활성화에는 AccessToken, RefreshToken, PlayerId, ExpiresAtSec를 사용합니다.

1. 세션 활성화 메서드 호출 파라미터 준비

세션 활성화에 필요한 파라미터를 준비합니다.

AccessToken, RefreshToken, PlayerId

• 토큰 발급하기 응답의 Data.AccessToken, Data.RefreshToken
• 유저네임 로그인 응답의 Data.PlayerId

ExpiresAtSec

액세스 토큰의 만료 시각을 Unix 초 단위로 전달합니다. 토큰 발급하기 응답의 Data.ExpiresIn은 발급 시점으로부터 남은 시간(초)이므로, 현재 시각에 더해 만료 시각을 계산합니다. issued는 토큰 발급 단계에서 받은 TokenIssueTokenResult.Success 객체입니다.

Unity

using System;

// 토큰 발급 응답의 ExpiresIn(남은 시간, 초)을 만료 시각(Unix 초)으로 바꿉니다.
long expiresAtSec = DateTimeOffset.UtcNow.ToUnixTimeSeconds() + issued.Data.ExpiresIn;

2. 세션 활성화

SetSession

ISessionManager.SetSession()을 호출해 토큰 발급으로 받은 액세스 토큰과 리프레시 토큰을 세션에 등록합니다.

호출 파라미터

필드명	타입	필수 여부	설명
accessToken	string	Required	인증 메서드 호출에 사용하는 액세스 토큰
refreshToken	string	Required	토큰 갱신에 사용하는 리프레시 토큰
playerId	long	Required	로그인한 Player ID
expiresAtSec	long	Required	액세스 토큰 만료 시각(Unix 초)

호출 예시

세션 매니저에 토큰을 등록합니다. SetSession()은 결과 객체를 반환하지 않습니다.

Unity

using Hive.Axyl.Core;

ISessionManager session = HiveCore.Resolve<ISessionManager>();

session.SetSession(
    issued.Data.AccessToken,
    issued.Data.RefreshToken ?? string.Empty,
    playerId,
    expiresAtSec);

응답 데이터

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

응답 예시

Unity

// SetSession은 반환값이 없습니다(void).
session.SetSession(issued.Data.AccessToken, issued.Data.RefreshToken ?? string.Empty, playerId, expiresAtSec);

응답 상태

SetSession()은 결과 객체를 반환하지 않습니다. 세션 등록 후에는 인증이 필요한 메서드 호출 시 여기에서 등록한 토큰이 사용됩니다.

전체 흐름 예시

토큰 발급은 IssueTokenAsync()로, 세션 등록은 ISessionManager로 수행합니다. 유저네임 로그인, 토큰 발급, 세션 등록을 하나로 묶은 StartSessionAsync() 같은 메서드로 구현할 수 있습니다. 코드와 토큰을 분리하는 것은 토큰 노출 위험을 줄이기 위한 보안 절차입니다.

IssueTokenAsync()가 반환하는 요청 수행 불가 공통 실패(Failure)의 결과 모델과 처리 원칙은 공통 오류 처리를 참조하세요.

Note

세션을 확립한 뒤 토큰 만료 시 자동 갱신을 켜 두면 편리합니다. 자세한 내용은 자동 로그인의 AuthTokenRefresh.Enable을 참조하세요.

StartSessionAsync 구현 예시

Unity

using System;
using System.Threading.Tasks;
using Hive.Axyl.Auth;
using Hive.Axyl.Core;

// authorizationCode를 사용해 토큰을 발급하고 세션을 확립합니다.
static async Task StartSessionAsync(string authorizationCode, string codeVerifier, long playerId)
{
    ITokenService   token   = HiveCore.Resolve<ITokenService>();
    ISessionManager session = HiveCore.Resolve<ISessionManager>();

    var issueResult = await token.IssueTokenAsync(new AuthorizationCodeTokenRequest {
        GrantType    = "authorization_code",
        ClientId     = "{clientId}",
        AuthorizationCode = authorizationCode,
        CodeVerifier = codeVerifier,   // 로그인 호출에 보낸 codeChallenge와 짝
    });
    if (issueResult is not TokenIssueTokenResult.Success issued)
    {
        // 토큰 발급 실패 처리 (InvalidGrant, InvalidGrantCodeChallenge 등)
        return;
    }

    // SDK는 로그인 시 세션을 자동 설정하지 않습니다. 직접 확립합니다.
    session.SetSession(
        issued.Data.AccessToken,
        issued.Data.RefreshToken ?? string.Empty,   // SetSession은 null을 허용하지 않습니다
        playerId,
        DateTimeOffset.UtcNow.ToUnixTimeSeconds() + issued.Data.ExpiresIn);
}

StartSessionAsync를 사용한 유저네임 로그인 통합 예시

CreatePkce()와 Sha256Hex()는 유저네임 로그인에서 정의한 헬퍼입니다. inputUsername·rawPassword는 사용자가 로그인 화면에 입력한 값입니다. deviceKey는 유저네임 계정 생성에서 확보해 앱이 관리하는 값입니다.

Unity

using Hive.Axyl.Auth;
using Hive.Axyl.Core;
using UnityEngine;

IAuthService auth = HiveCore.Resolve<IAuthService>();

var (codeVerifier, codeChallenge) = CreatePkce();

// 비밀번호는 로그인 시점의 사용자 입력을 SHA256 해시 후 전달합니다.
var result = await auth.LoginUsernameAsync(new UsernameLoginRequest {
    Username            = inputUsername,
    Password            = Sha256Hex(rawPassword),
    ClientId            = "{clientId}",
    CodeChallenge       = codeChallenge,
    CodeChallengeMethod = CodeChallengeMethod.S256,
    DeviceKey           = deviceKey,
});

switch (result)
{
    case AuthLoginUsernameResult.Success success:
        // 로그인 성공 → 토큰 발급 후 세션 시작
        await StartSessionAsync(success.Data.AuthorizationCode, codeVerifier, success.Data.PlayerId);
        break;

    case AuthLoginUsernameResult.UsernameVerifyFailed:
        // 유저네임 또는 비밀번호가 일치하지 않음 → 재입력 안내
        break;

    // 공통 실패 처리 (네트워크·서버 오류)
    case AuthLoginUsernameResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // 안전망: 처리하지 않은 결과 및 알 수 없는 신규 결과(UnknownOutcome)
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

더 알아보기

• 로그아웃
• 계정 삭제