게스트 로그인
게스트 계정으로 로그인합니다.
게스트 계정으로 로그인할 때는 GuestPlayerId, GuestToken, DeviceKey, ClientId, PKCE를 사용합니다.
1. 호출 파라미터 준비
게스트 로그인에 필요한 파라미터를 준비합니다.
GuestPlayerId, GuestToken, DeviceKey
게스트 계정 생성 시 입력값 또는 응답값인 GuestPlayerId, GuestToken, DeviceKey를 사용합니다. DeviceKey는 로그인 요청에서도 같은 길이·문자 검증을 거치므로, DeviceKey의 조건을 만족하는 값을 그대로 넣으세요.
Note
com.com2usplatform.hiveaxyl.storage 모듈을 사용하면 위 값을 사용자 기기에 저장해 두었다가 불러와 사용할 수 있습니다. 자동 로그인을 참조하세요.
ClientId
Hive 콘솔이 프로젝트 단위로 발급하는 Client ID입니다. 같은 프로젝트에 속한 모든 App ID가 같은 값을 사용합니다. 값은 보안 키 획득에서 확인하세요.
PKCE: codeChallenge와 codeVerifier
PKCE(codeVerifier·codeChallenge)는 발급되는 인가 코드가 중간에 탈취되어도 악용되지 않도록 보호하는 일회성 값 한 쌍입니다. 앱에서 직접 생성해야 합니다.
using System;
using System.Security.Cryptography;
using System.Text;
// PKCE(RFC 7636): codeVerifier 생성 + codeChallenge = BASE64URL(SHA256(codeVerifier))
static (string verifier, string challenge) CreatePkce()
{
var bytes = new byte[32];
using (var rng = RandomNumberGenerator.Create()) rng.GetBytes(bytes);
string verifier = Base64Url(bytes);
using var sha = SHA256.Create();
string challenge = Base64Url(sha.ComputeHash(Encoding.ASCII.GetBytes(verifier)));
return (verifier, challenge);
}
static string Base64Url(byte[] b) =>
Convert.ToBase64String(b).TrimEnd('=').Replace('+', '-').Replace('/', '_');
2. 게스트 로그인
LoginGuestAsync
LoginGuestAsync()를 호출해 게스트 계정으로 로그인합니다.
호출 파라미터
| 필드명 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| request | GuestLoginRequest | Required | 게스트 로그인 요청 |
| context | ApiCallContext | Optional | 호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다. |
GuestLoginRequest
| 필드명 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
GuestPlayerId | long | Required | 계정 생성 때 받은 Player ID |
GuestToken | string | Required | 계정 생성 때 받은 게스트 토큰 |
ClientId | string | Required | 프로젝트 단위로 발급되는 콘솔 보안 키의 Client ID |
CodeChallenge | string | Required | PKCE 코드 챌린지 |
CodeChallengeMethod | CodeChallengeMethod | Required | PKCE 방식. S256 |
DeviceKey | string | Required | 로그인 세션을 기기 단위로 구분하는 기기 식별 값. 22자 이상 64자 이하 |
호출 예시
요청 수행이 불가능한 공통 실패(Failure)의 결과 모델과 처리 원칙은 공통 오류 처리를 참조하세요.
using Hive.Axyl.Auth;
using Hive.Axyl.Core;
IAuthService auth = HiveCore.Resolve<IAuthService>();
var (codeVerifier, codeChallenge) = CreatePkce();
// AuthLoginGuestResult 객체를 반환
var result = await auth.LoginGuestAsync(new GuestLoginRequest {
GuestPlayerId = guestPlayerId,
GuestToken = guestToken,
ClientId = "{clientId}",
CodeChallenge = codeChallenge,
CodeChallengeMethod = CodeChallengeMethod.S256,
DeviceKey = deviceKey,
});
Note
실제 서비스에서 사용자가 로그인 수단을 선택하는 UI는 앱 클라이언트에서 직접 구현해야 합니다.
응답 데이터
성공 시 AuthLoginGuestResult.Success의 Data(LoginResponseData)에 로그인 결과가 담깁니다.
| 필드명 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
Data.PlayerId | long | Required | Player ID |
Data.AuthorizationCode | string | Required | 액세스 토큰과 리프레시 토큰 발급에 사용하는 인가 코드(토큰 발급에서 사용) |
Data.ProviderList | IReadOnlyList<ProviderInfo> | Required | 이 계정에 연동된 인증 제공자 목록 |
Data.IsBlock | bool | Required | 이용 제한 여부 |
Data.CreatedAt | DateTimeOffset | Required | 계정 생성 시각(UTC) |
응답 예시
응답 상태
AuthLoginGuestResult의 응답 케이스는 switch 구문으로 처리하는 것을 권장합니다. 분기 코드 예시는 세션 활성화하기의 통합 예시를 참조하세요.
| 응답 케이스 | 설명 | 앱 클라이언트 대응 |
|---|---|---|
Success | 로그인 성공. Data.AuthorizationCode를 사용해 토큰을 발급한 뒤 세션을 시작합니다. | 토큰 발급 후 세션 시작 |
InvalidGuestToken | 입력한 게스트 토큰이 유효하지 않은 경우. 계정에 다른 로그인 수단을 처음 연동하면 게스트 토큰이 무효가 됩니다. | 연동한 로그인 수단으로 로그인하도록 안내. 연동한 적이 없으면 게스트 계정 재생성 안내 |
InvalidClientId | Client ID가 올바르지 않은 경우 | 콘솔 보안 키 확인 |
IpBlocked | 접속 IP가 차단된 경우 | 정책 안내 |
AppNotFound | 앱 정보를 찾을 수 없는 경우 | 콘솔의 앱 등록 상태 확인 |
TerminateService | 서비스가 종료된 앱인 경우 | 서비스 운영 상태 확인 |
UnknownOutcome | 이 SDK 버전이 알지 못하는 신규 결과 | 로깅 후 보수적으로 처리 |
Failure | 공통 Failure입니다. 필수 파라미터 누락 또는 형식 오류(invalid_parameter), 필수 필드 누락(missing_field), X-App-Id 헤더 누락(missing_app_id)도 이 경우에 해당합니다. 원인은 Failure.Problem.ExternalCode에 담깁니다. 공통 오류 처리를 참조하세요. | 공통 오류 처리 기준에 따라 처리 |