> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 유저 라이프사이클

> Unity에서 유저를 만들고 로그인, 세션 갱신, 캐릭터 관리를 처리합니다.

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

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

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

## 게스트 유저 시작

```cs theme={null}
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도 그대로 사용할 수 있습니다.

```cs theme={null}
var rawSession = await HyperX.Core.Users.StartGuest("guest-device-or-save-id");
var player = HyperX.Core.Users.UseSession(rawSession);
```

## 커스텀 계정

```cs theme={null}
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 자격증명으로 토큰을 검증한 뒤 유저를 로그인하거나 새로 만듭니다.

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

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

```cs theme={null}
await player.LinkSocialIdentity(
    provider: HyperX.SocialProvider.Apple,
    identityToken: appleIdToken
);
```

Provider 앱 설정과 Console 자격증명 등록 방법은 [Provider 연동](/guide/dotnet/provider-integrations)을 참고하세요.

## 세션 갱신

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

```cs theme={null}
await player.RefreshIfNeeded();
var me = await player.Me();
```

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

## 현재 유저 확인

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

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

## 이름과 캐릭터

```cs theme={null}
var name = await player.CheckName("Ari");

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

```cs theme={null}
var character = await player.CreateCharacter(name: "Ari");

await player.UpdateRepresentativeCharacter(character.Id);
```

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

## 로그아웃

```cs theme={null}
await player.Logout();
```

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

```cs theme={null}
await player.LogoutAll();
```

## 계정 탈퇴와 복구

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

```cs theme={null}
var lifecycle = await player.RequestDeletion(reason: "player requested");

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

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

```cs theme={null}
var recovery = await HyperX.Core.Users.RequestRecovery(
    username: "ari"
);

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

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

```cs theme={null}
await player.CancelDeletion(recovery.RecoveryToken);
```

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