유저 라이프사이클

유저 라이프사이클은 게임 클라이언트가 플레이어를 HyperX 프로젝트 안의 유저로 연결하는 흐름입니다.

어떤 로그인 방식을 써야 하나요?

방식	적합한 경우
게스트	계정 생성 없이 바로 플레이를 시작해야 할 때
커스텀 계정	게임이 자체 ID/비밀번호 체계를 사용할 때
소셜 로그인	Google, Apple, Facebook 계정으로 복구 가능한 로그인을 제공할 때

게스트 유저 시작

using UnityEngine;

public class HyperXGuestLogin : MonoBehaviour
{
    async void Start()
    {
        await HyperX.Core.Init("PROJECT_CODE");

        var player = await HyperX.Core.Users.StartGuestSession(
            authenticationToken: SystemInfo.deviceUniqueIdentifier,
            country: "KR",
            language: "ko"
        );

        var me = await player.Me();
        Debug.Log($"User: {me.Id}, name: {me.Name}");
    }
}

StartGuestSession은 같은 게스트 토큰으로 이미 만든 유저가 있으면 새로 만들지 않고 로그인한 뒤 PlayerSession을 반환합니다. 출시 게임에서는 게스트 토큰을 복구 정책에 맞게 안정적으로 관리하세요. 기기 변경 후 복구가 필요하다면 소셜 로그인 또는 커스텀 계정 연결을 함께 제공하는 것이 좋습니다. 고급 마이그레이션이나 호환 어댑터처럼 access token을 직접 관리해야 하는 경우에는 기존 토큰 기반 API도 그대로 사용할 수 있습니다.

var rawSession = await HyperX.Core.Users.StartGuest("guest-device-or-save-id");
var player = HyperX.Core.Users.UseSession(rawSession);

커스텀 계정

await HyperX.Core.Users.RegisterCustom(
    username: "ari",
    password: "strong-password",
    country: "KR",
    language: "ko"
);

var player = await HyperX.Core.Users.LoginCustomSession("ari", "strong-password");

사용자 이름은 프로젝트 안에서 고유해야 합니다. 중복 이름, 잘못된 비밀번호, 정책에 맞지 않는 값은 HyperXServerException으로 실패합니다.

소셜 로그인

Google, Apple, Facebook 로그인은 각 플랫폼 SDK에서 받은 짧은 수명의 토큰을 HyperX에 전달합니다. HyperX는 Console에 등록된 provider 자격증명으로 토큰을 검증한 뒤 유저를 로그인하거나 새로 만듭니다.

var player = await HyperX.Core.Users.LoginSocialSession(
    provider: HyperX.SocialProvider.Google,
    identityToken: googleIdToken,
    country: "KR",
    language: "ko",
    appIdentifier: "com.example.game"
);

기존 HyperX 유저에 소셜 계정을 연결할 수도 있습니다.

await player.LinkSocialIdentity(
    provider: HyperX.SocialProvider.Apple,
    identityToken: appleIdToken
);

Provider 앱 설정과 Console 자격증명 등록 방법은 Provider 연동을 참고하세요.

세션 갱신

로그인 응답에는 API 호출용 AccessToken과 세션 재개용 RefreshToken이 포함됩니다.

await player.RefreshIfNeeded();
var me = await player.Me();

게임 클라이언트는 refresh token을 안전한 저장소에 보관하고, access token이 만료되면 Refresh 또는 RefreshIfNeeded로 새 토큰을 받습니다. refresh token도 만료되면 다시 로그인해야 합니다.

현재 유저 확인

var me = await player.Me();
Debug.Log($"{me.Id} / {me.Name}");

Console의 Users 화면에서도 같은 유저를 확인할 수 있습니다. 유저 ID, 가입 방식, 국가/언어, 대표 캐릭터, 최근 로그인 시각, 차단 상태를 볼 수 있습니다.

이름과 캐릭터

var name = await player.CheckName("Ari");

if (name.Available)
{
    await player.UpdateName("Ari");
}

var character = await player.CreateCharacter(name: "Ari");

await player.UpdateRepresentativeCharacter(character.Id);

대표 캐릭터는 프로필과 기본 캐릭터 데이터 편의 호출의 기준입니다. 대표 캐릭터가 아닌 캐릭터의 데이터는 캐릭터 ID를 명시해 저장하고 조회할 수 있습니다.

로그아웃

await player.Logout();

모든 기기 세션을 종료해야 하면 다음을 사용합니다.

await player.LogoutAll();

계정 탈퇴와 복구

플레이어가 계정 삭제를 요청하면 계정 상태가 deletion_requested로 바뀌고 삭제 예정 시각이 기록됩니다. 운영자는 Console의 Users 화면에서 요청 상태를 확인하고, 정책에 따라 삭제를 확정하거나 취소할 수 있습니다.

var lifecycle = await player.RequestDeletion(reason: "player requested");

Debug.Log(lifecycle.AccountStatus);
Debug.Log(lifecycle.DeletionScheduledAt);

삭제 요청을 취소하려면 복구 토큰이 필요합니다. 복구 토큰은 게임의 인증/고객지원 흐름에 맞춰 전달하세요.

var recovery = await HyperX.Core.Users.RequestRecovery(
    username: "ari"
);

await HyperX.Core.Users.ConfirmRecovery(recovery.RecoveryToken);

이미 로그인한 세션에서 토큰을 받은 경우 다음처럼 취소할 수 있습니다.

await player.CancelDeletion(recovery.RecoveryToken);

삭제가 확정된 계정은 일반 로그인과 세션 갱신이 거부됩니다. 구매, 환불, 감사 로그처럼 보존이 필요한 데이터는 프로젝트 보존 정책에 따라 남을 수 있습니다.

​어떤 로그인 방식을 써야 하나요?

​게스트 유저 시작

​커스텀 계정

​소셜 로그인

​세션 갱신

​현재 유저 확인

​이름과 캐릭터

​로그아웃

​계정 탈퇴와 복구