게스트 로그인 구현하기

레시피 코드로 게스트 로그인을 구현하려면 아래 절차를 순서대로 완료하세요.

시작하기 전에 공통 사전 준비를 마치세요.

각 단계에서 무엇을 설정하고 무엇을 호출하는지는 아래와 같습니다.

순서	구분	하는 일
1	Hive 콘솔	Client ID 확인과 게스트 로그인 활성화
2	Hive Axyl SDK	인증 모듈과 보안 저장소 모듈 설치
3	Hive Axyl SDK	SDK 초기화와 모듈 등록
4	레시피 코드	레시피 폴더 복사
5	앱 코드	`ClientId`와 `DeviceKey` 준비
6	앱 코드	게스트 자격 증명 저장소 준비
7	레시피 코드	게스트 로그인 호출
8	앱 코드	로그인 결과 처리
9	앱 코드	동작 확인

게스트 자격 증명은 결과 상태를 확인하기 전에 저장하세요

계정을 만든 뒤 세션을 준비하는 도중에 실패해도 레시피는 게스트 자격 증명을 반환합니다. 성공 분기 안에서만 저장하면 이미 만들어진 계정에 다시 접근할 수 없습니다.

Hive 콘솔 Hive 콘솔에서 설정하거나 확인합니다.

Hive 콘솔에서 로그인에 사용할 Client ID를 확인하고 게스트 로그인을 활성화하세요. 로그인 수단이 비활성 상태이면 레시피 호출이 거절됩니다.

설정 항목	필수 여부	확인할 곳
Client ID 확인	필수	보안 키 획득
게스트 로그인 활성화	필수	콘솔에서 로그인 활성화 상태 확인

Client Secret은 앱 클라이언트에 넣지 마세요

레시피는 Client ID만 사용합니다. Client Secret이 앱 클라이언트에서 유출되면 악의적인 사용자가 API를 무단으로 호출할 수 있습니다.

계정 생성에 추가 보안을 적용한 앱은 이 레시피를 그대로 사용할 수 없습니다. GuestLoginRecipe는 사전 승인 값인 GrantKey를 입력받지 않기 때문입니다. 이 경우에는 게스트 계정 생성과 게스트 로그인에서 Hive Axyl SDK 메서드를 직접 호출해 구현하세요.

Hive Axyl SDK Hive Axyl SDK를 앱에서 호출합니다.

상세 절차: 모듈 설치

인증 모듈과 보안 저장소 모듈을 Unity 프로젝트에 설치하세요. 보안 저장소 모듈은 DeviceKey와 게스트 자격 증명을 기기에 암호화해 보관할 때 사용합니다.

패키지	필요 여부	역할
`com.com2usplatform.hiveaxyl.core`	필수	SDK 초기화와 로그인 세션 관리
`com.com2usplatform.hiveaxyl.auth`	필수	게스트 계정 생성, 게스트 로그인, 토큰 발급
`com.com2usplatform.hiveaxyl.storage`	권장	`DeviceKey`와 게스트 자격 증명의 암호화 저장

앱에서 이미 안전한 저장소를 사용한다면 com.com2usplatform.hiveaxyl.storage를 설치하지 않아도 됩니다. 이 경우에도 DeviceKey와 게스트 자격 증명을 앱 재시작 뒤에 다시 읽을 수 있어야 합니다.

Hive Axyl SDK Hive Axyl SDK를 앱에서 호출합니다.

상세 절차: SDK 초기화, 보안 저장소 모듈 등록

앱 시작 지점에서 SDK를 한 번 초기화하고 인증, 토큰, 보안 저장소 모듈을 등록하세요. 레시피는 SDK를 초기화하지 않으므로, 초기화하지 않은 상태에서 호출하면 FailedPrecondition 오류로 실패합니다.

아래는 게스트 로그인에 필요한 모듈을 등록해 초기화하는 예제 코드입니다.

Unity

using Hive.Axyl.Auth;
using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;
using Hive.Axyl.Storage;

var config = CoreConfig.CreateBuilder("{appId}").Build();

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

{appId}에는 Hive 콘솔에서 만든 App ID를 입력하세요.

AddAuth()와 AddToken()을 등록하지 않으면 레시피가 FailedPrecondition 오류로 실패합니다. 앱에서 다른 안전한 저장소를 사용한다면 AddSecureStorage()는 등록하지 않아도 됩니다.

레시피 코드 레시피 코드를 프로젝트에 복사합니다.

레시피는 패키지가 아니라 프로젝트에 복사해서 사용하는 소스 코드입니다. axyl-samples-unity 저장소에서 아래 항목을 Unity 프로젝트의 Assets/Recipes/ 아래로 복사하세요.

복사할 항목과 역할은 아래와 같습니다.

Recipes.asmdef: 레시피 공통 어셈블리 정의
AssemblyInfo.cs: 내부 헬퍼를 다른 레시피 어셈블리에 공개하는 설정
Helper/: 여러 레시피가 함께 사용하는 공통 코드
GuestLogin/: GuestLoginRecipe, GuestCredential, 결과 유형

앱 코드에서 레시피를 호출하려면 앱 쪽 어셈블리 정의의 references에 아래 어셈블리를 추가하세요. 원본 Recipes.asmdef의 autoReferenced 값이 false이므로 앱 어셈블리가 자동으로 참조하지 않습니다.

MyApp.asmdef

{
  "name": "MyApp",
  "references": [
    "Hive.Axyl.Core",
    "Hive.Axyl.Auth",
    "Hive.Axyl.Storage",
    "Hive.Axyl.Samples.Recipes"
  ]
}

MyApp은 앱에서 사용하는 어셈블리 이름으로 바꾸고, 기존 설정과 참조는 유지하세요. Unity 어셈블리는 참조를 전이하지 않으므로 앱 코드가 직접 사용하는 어셈블리를 모두 여기에 적어야 합니다. Hive.Axyl.Core에는 CoreConfig와 HiveError가, Hive.Axyl.Auth에는 AddAuth()와 AddToken()이, Hive.Axyl.Storage에는 AddSecureStorage()가 들어 있습니다. AddSecureStorage()를 등록하지 않는다면 Hive.Axyl.Storage는 적지 않아도 됩니다.

GuestLogin/만 복사하면 컴파일되지 않습니다

GuestLoginRecipe는 Helper/의 PKCE 생성 코드와 세션 준비 코드를 사용합니다. Helper/, Recipes.asmdef, AssemblyInfo.cs를 함께 복사하세요.

앱 코드 앱에서 직접 구현합니다.

상세 절차: DeviceKey

GuestLoginRecipe의 생성자는 ClientId와 DeviceKey를 받습니다. ClientId는 1단계에서 확인한 값으로, Hive 콘솔이 프로젝트마다 발급합니다. DeviceKey는 Hive Axyl 인증 서버가 로그인 세션을 기기 단위로 구분하는 값이며, 앱이 직접 만들어 보관합니다.

레시피는 DeviceKey를 만들거나 저장하지 않으므로, 아래 조건에 맞게 만들고 관리하세요.

기기마다 다른 값. UUID 같은 난수 권장
최초 실행 때 한 번 만들어 저장하고, 이후 모든 로그인에서 재사용하는 값
22자 이상 64자 이하의 길이
공백과 제어 문자를 제외한 ASCII 문자로만 이루어진 값

저장소를 읽지 못했다고 새 DeviceKey로 덮어쓰지 마세요

값이 사라진 것이 아니라 읽기에만 실패했을 수 있습니다. 먼저 저장소 접근 문제를 해결하거나 다시 읽기를 시도하세요.

앱 코드 앱에서 직접 구현합니다.

상세 절차: GuestPlayerId, GuestToken, DeviceKey, 저장된 인증 정보 보존

게스트 자격 증명인 GuestCredential은 PlayerId와 GuestToken으로 구성됩니다. 이 두 값을 함께 보관해야 앱을 다시 시작한 뒤에도 같은 게스트 계정으로 로그인합니다.

GuestCredential.PlayerId와 GuestCredential.GuestToken은 Hive Axyl SDK가 GuestPlayerId와 GuestToken으로 부르는 값과 같습니다. 레시피가 두 값을 하나의 형식으로 묶어 반환할 뿐입니다.

레시피는 게스트 자격 증명을 저장하거나 삭제하지 않습니다. 아래 세 동작을 제공하는 저장소 컴포넌트를 앱에서 만드세요.

동작	반환값	설명
불러오기	`GuestCredential` 또는 `null`	저장된 자격 증명을 읽습니다. 값이 없으면 `null`을 반환합니다.
저장	없음	전달받은 `GuestCredential`로 기존 값을 교체합니다.
삭제	없음	저장된 자격 증명을 지웁니다. 사용자가 이 계정에 Google이나 Apple 같은 외부 인증 제공자를 처음 연동하면 Hive Axyl 인증 서버가 게스트 토큰을 무효로 만들므로, 그 시점에 지웁니다.

삭제 시점과 판단 기준은 외부 인증 제공자 연동 활용 가이드를 참조하세요.

세 동작 모두 저장소 접근을 기다리므로 비동기 메서드로 만들고, CancellationToken을 함께 받으세요. 아래 예제 코드는 이 저장소를 guestCredentialStore라는 이름으로 부릅니다.

저장소가 정상으로 동작하지 않을 때는 상황을 구분해 처리하세요.

저장소 접근 거부 또는 일시적 실패: 저장된 값을 삭제하지 않고 재시도 흐름 제공
저장 데이터 손상 확정: 저장소를 초기화한 뒤 로그인 수단 선택 화면 제공

저장소 접근 거부와 데이터 손상은 다르게 처리하세요. 접근이 거부된 경우에는 기존 데이터가 남아 있을 수 있으므로 저장소를 초기화하면 안 됩니다.

레시피 코드 레시피 코드를 앱에서 호출합니다.

저장된 자격 증명을 불러와 LoginAsGuestAsync()에 전달하세요. 값이 null이면 레시피가 새 게스트 계정을 만들고, 값이 있으면 같은 계정을 복원합니다. Credential이 반환되면 Status를 확인하기 전에 저장하세요.

사용자가 화면을 닫거나 로그인을 취소할 때 기다리기를 멈출 수 있도록 CancellationTokenSource를 함께 준비하세요.

Credential을 저장하는 호출에는 로그인 취소 토큰 대신 CancellationToken.None을 전달하세요. 계정이 만들어진 뒤 사용자가 로그인을 취소해도 레시피는 그 계정의 Credential을 반환합니다. 이때 저장 호출에 로그인 취소 토큰을 전달하면, 취소 토큰을 확인하는 저장소는 값을 쓰지 않고 저장을 끝냅니다. 그러면 서버에는 계정이 있지만 기기에는 자격 증명이 남지 않습니다. 앱을 다시 시작하면 그 계정으로 로그인할 수 없습니다.

아래는 자격 증명을 불러와 로그인하고, 반환된 자격 증명을 로그인 취소와 관계없이 저장하는 예제 코드입니다.

Unity

using System.Threading;
using Hive.Axyl.Samples.Recipes;

var recipe = new GuestLoginRecipe(clientId, deviceKey);

var cancellation = new CancellationTokenSource();
CancellationToken token = cancellation.Token;

GuestCredential storedCredential = await guestCredentialStore.LoadAsync(token);

LoginAsGuestOutcome outcome = await recipe.LoginAsGuestAsync(storedCredential, token);

if (outcome.Credential != null)
{
    // 계정은 이미 만들어졌습니다. 결과 상태와 관계없이 먼저 저장합니다.
    // 로그인이 취소되어도 저장은 중단되지 않도록 로그인 취소 토큰을 전달하지 않습니다.
    await guestCredentialStore.SaveAsync(outcome.Credential, CancellationToken.None);
}

저장에 실패하면 outcome.Credential을 메모리에 보관한 채 저장을 다시 시도하세요. 저장에 성공하기 전에 이 값을 버리면 새로 만든 게스트 계정에 다시 접근할 수 없습니다.

화면을 닫거나 사용자가 취소를 선택할 때 cancellation.Cancel()을 호출하고, 호출이 끝나면 cancellation.Dispose()로 정리하세요.

레시피가 내부에서 수행하는 작업은 아래와 같습니다.

구분	호출	확인할 곳
레시피 코드	PKCE 값 한 쌍을 만들어 로그인 호출과 토큰 발급 호출에 나눠 전달	호출 파라미터 준비
Hive Axyl SDK	`CreateGuestAsync()`로 새 게스트 계정 생성	게스트 계정 생성
Hive Axyl SDK	`LoginGuestAsync()`로 저장된 게스트 계정 복원	게스트 로그인
Hive Axyl SDK	`IssueTokenAsync()`로 인가 코드를 액세스 토큰과 리프레시 토큰으로 교환	액세스 토큰과 리프레시 토큰 발급
Hive Axyl SDK	`SetSession()`으로 로그인 세션 활성화	세션 활성화

CreateGuestAsync()와 LoginGuestAsync() 중 하나만 호출합니다. 두 호출 모두 인가 코드를 돌려주고, 레시피는 그 인가 코드로 토큰 발급과 세션 활성화까지 이어서 처리합니다. Success가 반환되면 세션까지 준비된 상태이므로 토큰 발급이나 세션 활성화 코드를 따로 호출하지 마세요.

위 표의 상세 절차는 Hive Axyl SDK 메서드를 직접 호출할 때를 기준으로 쓰여 있습니다. PKCE 값을 만드는 작업처럼 레시피가 대신하는 단계는 앱에서 다시 구현하지 마세요. 각 호출이 무엇을 주고받는지 확인할 때만 참조하세요.

앱 코드 앱에서 직접 구현합니다.

상세 절차: HiveError 정보

LoginAsGuestOutcome은 Status로 로그인 결과를 알려 줍니다. FailedStep은 진단용 값이므로 앱의 정상 흐름을 분기하는 기준으로 사용하지 마세요.

`Status`	확인할 값	앱 처리
`Success`	`IsNewAccount`, `IsBlocked`	새 계정인지 확인하고, 이용 제한 상태가 아니면 로그인 후 화면으로 이동합니다.
`BusinessOutcome`	`BusinessOutcome`, `UnknownOutcomeCode`	거절 사유에 맞게 분기하고, 모르는 값은 실패로 처리해 기록합니다.
`Failure`	`Error.Code`, `Error.TraceId`	기술 문제를 기록하고, 자격 증명을 보관한 채 재시도 흐름을 제공합니다.

IsBlocked는 저장된 자격 증명으로 기존 계정을 복원했을 때만 값이 채워집니다. 새 게스트 계정을 만든 직후에는 항상 false입니다.

CancellationToken으로 로그인을 취소하면 Status는 Failure가 되고 Error.Code는 HiveErrorCode.Cancelled가 됩니다. 취소되기 전에 계정이 만들어졌다면 Credential이 함께 반환되므로, 취소 결과에서도 자격 증명을 저장하세요. 이 저장에는 7단계 예제 코드처럼 로그인 취소 토큰을 전달하지 마세요.

거절 사유가 InvalidGuestToken이면 사용자가 이 계정에 외부 인증 제공자를 연동해 게스트 토큰이 무효가 된 상태일 수 있습니다. 이때는 연동한 로그인 수단으로 기존 계정에 접근하도록 안내하세요. 연동 시점에 저장된 자격 증명을 미리 지워 두면 이 상황을 겪지 않으므로, 처리 방법은 외부 인증 제공자 연동 활용 가이드를 참조하세요.

거절 사유가 TemporarilyUnavailable이면 일시적으로 토큰을 발급하지 못한 상태입니다. 반환된 Credential을 저장한 뒤 새 계정을 만들지 말고, 그 값으로 같은 계정에 다시 로그인하세요.

저장된 자격 증명으로 실패했을 때 새 계정을 만들지 마세요

일시적인 기술 문제라면 같은 자격 증명으로 다시 시도해야 합니다. 새 계정을 자동으로 만들면 기존 계정의 진행 상태와 분리됩니다.

UnknownOutcomeCode와 RawJson은 사용자에게 표시하지 마세요. 앱 오류 기록이 필요한 경우에만 사용하고, 모르는 결과를 이미 아는 결과로 추정하지 마세요.

앱 코드 앱에서 동작을 확인합니다.

실제 기기에서 새 게스트 계정 생성과 기존 계정 복원을 확인하세요. Unity 에디터에서는 기기 보안 저장소가 없어 ISecureStorage가 등록되지 않으므로 저장과 재시작 흐름을 그대로 검증할 수 없습니다.

저장된 게스트 자격 증명이 없는 상태에서 로그인을 실행하세요.
Success와 IsNewAccount == true를 확인하고 GuestCredential이 저장되었는지 확인하세요.
앱을 완전히 종료한 뒤 다시 실행하세요.
저장한 자격 증명을 전달해 로그인하고 IsNewAccount == false를 확인하세요.

게스트 계정은 기기에 저장한 자격 증명으로만 복원되므로, 앱을 지우거나 기기를 바꾸면 사용자가 계정을 잃습니다. 사용자가 다른 기기에서도 같은 계정에 로그인하도록 외부 인증 제공자 연동 활용 가이드를 참조하세요.

로그인한 사용자가 앱을 다시 실행할 때 로그인 화면을 건너뛰도록 하려면 자동 로그인을 참조하세요.

로그인한 계정에서 빠져나와 다른 계정으로 로그인하도록 하려면 로그아웃 활용 가이드를 참조하세요.

게스트 로그인 구현하기

전체 흐름

1. Hive 콘솔 설정

2. SDK 모듈 설치

3. SDK 초기화

4. 레시피 코드 설치

5. ClientId와 DeviceKey 준비

6. 게스트 자격 증명 저장소 준비

7. 게스트 로그인 호출

8. 로그인 결과 처리

9. 동작 확인

다음 단계