> ## 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.

# SDK 초기화

> 프로덕션 HyperX 프로젝트에 Unity/.NET SDK를 연결합니다.

HyperX SDK는 게임 시작 초기에 한 번 초기화합니다. 초기화가 끝난 뒤 유저, 데이터, LiveOps, 소셜 기능을 호출할 수 있습니다.

## 기본 초기화

```cs theme={null}
await HyperX.Core.Init("PROJECT_CODE");
```

`PROJECT_CODE`는 Console에서 만든 프로젝트의 고유 코드입니다. 코드가 틀리거나 프로젝트가 비활성화되어 있으면 초기화가 실패합니다.

## 권장 Unity 부트스트랩

```cs theme={null}
using System;
using UnityEngine;
using HyperX;

public class HyperXBootstrap : MonoBehaviour
{
    async void Start()
    {
        try
        {
            await Core.Init(new HyperXInitOptions
            {
                ProjectCode = "PROJECT_CODE",
                Environment = HyperXEnvironment.Production,
                Timeout = TimeSpan.FromSeconds(10)
            });

            Debug.Log("HyperX ready");
        }
        catch (HyperXInitializationException ex)
        {
            Debug.LogError($"HyperX init failed: {ex.ErrorCode}");
        }
    }
}
```

프로덕션 게임에서는 `HyperXEnvironment.Production`을 사용합니다. 별도 호스트나 내부 테스트 환경 값은 일반 게임 클라이언트에 설정하지 않습니다.

## 초기화 실패 처리

초기화 단계의 오류는 `HyperXInitializationException`으로 전달됩니다.

| ErrorCode                       | 의미                              | 확인할 것                            |
| ------------------------------- | ------------------------------- | -------------------------------- |
| `PROJECT_CODE_REQUIRED`         | 프로젝트 코드가 비어 있습니다.               | 빌드 설정 또는 상수 값을 확인합니다.            |
| `PROJECT_NOT_FOUND`             | HyperX가 프로젝트를 찾지 못했습니다.         | Console의 프로젝트 코드가 맞는지 확인합니다.     |
| `INITIALIZATION_TIMEOUT`        | 프로젝트 확인 요청이 제한 시간 안에 끝나지 않았습니다. | 네트워크 상태를 확인하고 재시도합니다.            |
| `INITIALIZATION_REQUEST_FAILED` | 네트워크 요청이 실패했습니다.                | 인터넷 연결, 방화벽, 플랫폼 네트워크 권한을 확인합니다. |

초기화 이후 API 호출에서 발생하는 서버 오류는 [에러 처리](/guide/dotnet/error-handling)의 `HyperXServerException`으로 처리합니다.

## 초기화 후 플레이어 세션 만들기

게임 플레이 중 로그인 유저가 필요한 API를 자주 호출한다면 `PlayerSession` 흐름을 권장합니다.

```cs theme={null}
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();
await player.PutUserData("save_state", new { chapter = 3 });
await player.RefreshIfNeeded();
```

기존 `Core.Users.StartGuest`, `Core.Users.LoginCustom`, `Core.Users.LoginSocial` API는 계속 사용할 수 있습니다. 다만 `PlayerSession`을 사용하면 access token을 모든 API 호출에 반복해서 전달하지 않아도 되고, `RefreshIfNeeded`로 토큰 갱신 시점도 한 곳에서 다룰 수 있습니다.

## 요청 식별자

SDK는 모든 요청에 SDK 버전, 런타임, 추적 ID, 요청 ID를 함께 보냅니다. 지원 문의나 운영 로그 확인이 필요할 때 이 값을 사용합니다.

```cs theme={null}
await HyperX.Core.Init(new HyperXInitOptions
{
    ProjectCode = "PROJECT_CODE",
    TraceId = "game-boot",
    RequestId = Guid.NewGuid().ToString("N")
});
```

직접 지정하지 않으면 SDK가 요청마다 값을 생성합니다.