콘텐츠로 이동

Core 세션

로그인 세션을 메모리에 보관하는 서비스입니다. 액세스 토큰, 리프레시 토큰, Player ID, 만료 시각을 담고, 세션이 바뀌거나 끝날 때 이벤트를 발생시킵니다.

세션은 메모리에만 존재합니다. 앱을 다시 실행하면 사라지므로, 다음 실행에서 자동 로그인을 제공하려면 앱이 직접 토큰을 저장해야 합니다.

ISessionManager

interface — 네임스페이스 Hive.Axyl.Core

  • 패키지: com.com2usplatform.hiveaxyl.core
  • 등록: Core 기본 서비스로 자동 등록

어느 스레드에서 호출해도 안전합니다.

획득

Core 기본 서비스이므로 별도 등록 없이 가져올 수 있습니다.

using Hive.Axyl.Core;

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

메서드 요약

메서드

SetSession

세션을 새로 등록합니다. 기존 세션이 있으면 대체합니다. 로그인에 성공했거나, 앱 시작 시 저장해 둔 토큰으로 세션을 복원할 때 호출합니다.

토큰 자동 갱신에 성공했을 때는 SDK가 내부적으로 호출합니다.

호출 후 OnSessionRefreshed가 발생합니다.

void SetSession(string accessToken, string refreshToken, long playerId, long expiresAtSec)
파라미터 타입 필수 여부 설명
accessToken string Required 액세스 토큰입니다. null일 수 없습니다.
refreshToken string Required 리프레시 토큰입니다. null일 수 없습니다.
playerId long Required Player ID입니다.
expiresAtSec long Required 액세스 토큰 만료 시각입니다. Unix 타임스탬프 초(UTC)입니다.

발생 예외

  • ArgumentNullException: accessToken 또는 refreshToken이 null인 경우

호출 예시

session.SetSession(accessToken, refreshToken, playerId, expiresAtSec);

토큰 발급 이후의 세션 등록 절차는 세션 등록을 참조하세요.

ClearSession

현재 세션을 지우고 모든 값을 기본값으로 되돌립니다. 앱 사용자가 로그아웃할 때 호출합니다. 이 호출은 "세션이 끝났다"는 앱의 확정 판단으로 취급됩니다.

리프레시 토큰 자체가 무효라는 서버의 확정 응답으로 자동 갱신이 거절된 경우에도 SDK가 내부적으로 호출합니다. 반면 네트워크 실패, 서버 오류, 취소처럼 확정 판단이 없는 갱신 실패는 이 메서드를 거치지 않습니다. SDK 종료도 마찬가지로 조용히 세션을 초기화합니다.

세션을 지운 뒤 OnSessionExpired가 발생합니다. 활성 세션이 없으면 아무 동작도 하지 않고 이벤트도 발생시키지 않습니다.

void ClearSession()

GetSnapshot

현재 세션 상태의 스냅샷을 가져옵니다.

SessionSnapshot GetSnapshot()

이벤트

두 이벤트 모두 엔진 메인 스레드에서 호출되므로 핸들러 안에서 엔진 API를 사용해도 됩니다.

구독자 목록은 이벤트를 발생시키는 시점에 확정됩니다. 따라서 구독을 해제한 직후에 핸들러가 한 번 더 호출될 수 있습니다.

OnSessionExpired

저장된 인증 정보를 더 이상 쓸 수 없다고 확정된 경우에만 발생하며, 저장해 둔 인증 정보를 삭제하라는 신호입니다. 삭제해도 되는 경우와 보존해야 하는 경우의 기준은 저장된 인증 정보 보존을 참조하세요.

event Action OnSessionExpired

상황별 발생 여부는 아래와 같습니다.

  • 발생하는 경우
    • 앱이 활성 세션에 대해 ClearSession()을 호출한 경우. 보통 로그아웃이 여기에 해당합니다.
    • 리프레시 토큰 자체가 무효라는 서버의 확정 응답으로 자동 갱신이 거절되어 토큰을 폐기한 경우
  • 발생하지 않는 경우
    • 활성 세션이 없는 상태에서 ClearSession()을 호출한 경우
    • SDK를 종료한 경우
    • 네트워크 실패, 서버 오류, 취소처럼 토큰의 유효성을 확정하지 못한 갱신 실패. 연속 세 번 실패해 세션이 끝나는 경우에도 발생하지 않습니다.
    • 액세스 토큰이 단순히 만료된 경우. SDK가 먼저 자동 갱신을 시도합니다.
이벤트 없이 세션이 끝날 수 있습니다

확정 판단이 없는 갱신 실패는 세션을 그대로 둡니다. 다만 이런 실패가 연속으로 세 번 쌓이면 메모리의 세션이 조용히 끝납니다. 취소로 끝난 시도는 이 횟수에 포함되지 않습니다.

이 경우 OnSessionExpired가 발생하지 않으므로, 이벤트 없이 IsLoggedIn이 false가 될 수 있습니다. 저장해 둔 인증 정보는 여전히 유효하므로 삭제하면 안 됩니다.

이때는 재시도가 아니라 세션을 다시 등록해야 합니다. IsLoggedIn을 다시 확인한 뒤 로그인 또는 세션 복원 흐름으로 SetSession()을 호출하면 자동 갱신이 다시 동작합니다.

OnSessionRefreshed

세션이 새로 등록되거나 토큰이 교체될 때마다 발생합니다. 로그인·세션 복원 직후, 그리고 만료된 액세스 토큰을 SDK가 자동으로 갱신한 직후가 여기에 해당합니다. 전달되는 스냅샷에는 새로 저장된 값이 담깁니다.

event Action<SessionSnapshot> OnSessionRefreshed
파라미터 타입 설명
— SessionSnapshot 새로 저장된 세션 값입니다.
이 이벤트에서 토큰을 저장하세요

갱신 요청은 한 번만 쓸 수 있는 것으로 취급합니다. 갱신이 일어나면 이전에 저장해 둔 리프레시 토큰은 더 이상 쓰지 못할 수 있으므로, 이 이벤트에서 새 값으로 갱신해 저장하세요.

구독 예시

using Hive.Axyl.Core;

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

session.OnSessionRefreshed += snapshot =>
{
    // 새 토큰을 앱 저장소에 덮어씁니다.
};

session.OnSessionExpired += () =>
{
    // 저장해 둔 토큰을 삭제하고 로그인 화면으로 이동합니다.
};

프로퍼티

프로퍼티 타입 설명
AccessToken string? 현재 액세스 토큰입니다. 활성 세션이 없으면 null입니다.
RefreshToken string? 현재 리프레시 토큰입니다. 활성 세션이 없으면 null입니다.
PlayerId long Player ID입니다. 로그인 상태가 아니면 0입니다.
IsLoggedIn bool 활성 세션이 있으면 true입니다. AccessToken이 null이 아닌 상태와 같습니다.

데이터 타입

SessionSnapshot

struct — 네임스페이스 Hive.Axyl.Core

특정 시점의 세션 상태를 담은 값입니다. GetSnapshot()의 반환값이자 OnSessionRefreshed에 전달되는 값이며, 생성 후 변경할 수 없습니다.

ToString()은 토큰을 가려서 출력하므로 로그에 그대로 남겨도 토큰이 노출되지 않습니다.

프로퍼티 타입 필수 여부 설명
AccessToken string? Optional 액세스 토큰입니다. 활성 세션이 없으면 null입니다.
RefreshToken string? Optional 리프레시 토큰입니다. 활성 세션이 없으면 null입니다.
PlayerId long Required Player ID입니다. 로그인 상태가 아니면 0입니다.
ExpiresAtSec long Required 액세스 토큰 만료 시각입니다. Unix 타임스탬프 초(UTC)이며, 활성 세션이 없으면 0입니다.