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

# 빠른 시작 (Windows) - Core SDK 설정

> Windows 프로젝트에 PlayFab 통합 SDK를 추가하고, Core를 초기화하며, XBOX 또는 Steam으로 플레이어를 인증하여 PFEntityHandle을 얻는 방법.

이 가이드에서는 Windows 프로젝트에 PlayFab 통합 SDK를 통합하고, SDK를 초기화하며, 플레이어를 인증하는 방법을 안내합니다. 이는 PlayFab API 호출의 기초가 됩니다.

## 필수 조건

시작하기 전에 [빠른 시작 설정](/services/playfab/sdks/unified-sdk/quickstart-setup)의 설정 단계를 완료하여 개발 환경과 프로젝트를 구성하세요.

## 달성하게 될 내용

이 빠른 시작이 끝나면 다음을 완료하게 됩니다:

* Windows 프로젝트에 PlayFab 통합 SDK 설정
* 타이틀 ID로 SDK 초기화
* XBOX 또는 Steam을 사용하여 플레이어 인증
* API 호출을 위한 엔티티 핸들 획득
* 리소스 적절히 정리

## 이 빠른 시작 내에서

1. [SDK 초기화](#step-1-initialize-the-sdk)
2. [플레이어 인증](#step-2-authenticate-a-player)
3. [리소스 정리](#step-3-clean-up-resources)

## 1단계: SDK 초기화

### 필수 헤더 포함

먼저 프로젝트에 필요한 PlayFab 및 XBOX Game Runtime 헤더를 포함합니다:

```cpp theme={null}
#include <playfab/core/PFCore.h>
#include <XGameRuntimeInit.h>
```

### XBOX Gaming Runtime Services 초기화

PlayFab 통합 SDK에는 XBOX Game Runtime이 필요합니다. 먼저 이를 초기화하세요:

```cpp theme={null}
HRESULT hr = XGameRuntimeInitialize();
if (FAILED(hr))
{
    std::wcerr << L"Failed to initialize Xbox Game Runtime: 0x" << std::hex << hr << std::endl;
    return hr;
}
std::wcout << L"Xbox Game Runtime initialized successfully." << std::endl;
```

### PlayFab Core 초기화

PlayFab SDK를 초기화하고 서비스 구성 핸들을 생성합니다. `ABCDEF`를 실제 PlayFab 타이틀 ID로 바꾸세요:

```cpp theme={null}
// Initialize PlayFab
HRESULT hr = PFInitialize(nullptr);
if (FAILED(hr))
{
    std::wcerr << L"Failed to initialize PlayFab: 0x" << std::hex << hr << std::endl;
    return hr;
}

// Create service configuration handle
PFServiceConfigHandle serviceConfigHandle{ nullptr };
hr = PFServiceConfigCreateHandle(
    "https://ABCDEF.playfabapi.com", // Replace ABCDEF with your Title ID
    "ABCDEF",                        // Replace ABCDEF with your Title ID
    &serviceConfigHandle);
if (FAILED(hr))
{
    std::wcerr << L"Failed to create service config handle: 0x" << std::hex << hr << std::endl;
    return hr;
}
std::wcout << L"PlayFab initialized successfully." << std::endl;
```

<Tip>
  타이틀 ID는 [Game Manager 대시보드](https://developer.playfab.com)에서 게임 설정 아래에서 찾을 수 있습니다.
</Tip>

## 2단계: 플레이어 인증

PlayFab은 API 호출 전에 플레이어 인증을 요구합니다. SDK는 플랫폼과 요구 사항에 따라 여러 인증 방법을 제공합니다.

### 인증 방법 선택

#### 옵션 A: XBOX로 로그인 (Windows/XBOX 권장)

XBOX 사용자 계정으로 로그인하려면 `PFAuthenticationLoginWithXUserAsync`를 사용하세요. Windows 및 XBOX 애플리케이션에 권장되는 방법입니다.

```cpp theme={null}
// Assume you have obtained an XUserHandle (userHandle) through XUser APIs
// For details on obtaining XUserHandle, see the Xbox Game Development Kit documentation

PFAuthenticationLoginWithXUserRequest request{};
request.createAccount = true;  // Create account if it doesn't exist
request.user = userHandle;     // XUserHandle obtained from Xbox user APIs

XAsyncBlock async{};
HRESULT hr = PFAuthenticationLoginWithXUserAsync(serviceConfigHandle, &request, &async);
if (FAILED(hr))
{
    std::wcerr << L"Failed to start Xbox login: 0x" << std::hex << hr << std::endl;
    return hr;
}

// Wait for login to complete
hr = XAsyncGetStatus(&async, true); // Blocking wait
if (FAILED(hr))
{
    std::wcerr << L"Xbox login failed: 0x" << std::hex << hr << std::endl;
    return hr;
}

// Get the result
std::vector<char> loginResultBuffer;
PFAuthenticationLoginResult const* loginResult;
size_t bufferSize;
hr = PFAuthenticationLoginWithXUserGetResultSize(&async, &bufferSize);
if (SUCCEEDED(hr))
{
    loginResultBuffer.resize(bufferSize);
    PFEntityHandle entityHandle{ nullptr };
    hr = PFAuthenticationLoginWithXUserGetResult(&async, &entityHandle, 
        loginResultBuffer.size(), loginResultBuffer.data(), &loginResult, nullptr);
    
    if (SUCCEEDED(hr))
    {
        std::wcout << L"Successfully logged in with Xbox. Player ID: " 
                   << loginResult->playFabId << std::endl;
        // entityHandle is now ready for making API calls
    }
}
```

#### 옵션 B: Steam으로 로그인

Steam 통합 게임의 경우, Steam 인증 티켓과 함께 `PFAuthenticationLoginWithSteamAsync`를 사용하세요.

```cpp theme={null}
// Assume you have obtained a Steam ticket through Steam APIs
PFAuthenticationLoginWithSteamRequest request{};
request.createAccount = true;         // Create account if it doesn't exist
request.steamTicket = steamTicket;    // Steam authentication ticket

XAsyncBlock async{};
HRESULT hr = PFAuthenticationLoginWithSteamAsync(serviceConfigHandle, &request, &async);
if (FAILED(hr))
{
    std::wcerr << L"Failed to start Steam login: 0x" << std::hex << hr << std::endl;
    return hr;
}

// Wait for login to complete
hr = XAsyncGetStatus(&async, true);
if (FAILED(hr))
{
    std::wcerr << L"Steam login failed: 0x" << std::hex << hr << std::endl;
    return hr;
}

// Get the result
std::vector<char> loginResultBuffer;
PFAuthenticationLoginResult const* loginResult;
size_t bufferSize;
hr = PFAuthenticationLoginWithSteamGetResultSize(&async, &bufferSize);
if (SUCCEEDED(hr))
{
    loginResultBuffer.resize(bufferSize);
    PFEntityHandle entityHandle{ nullptr };
    hr = PFAuthenticationLoginWithSteamGetResult(&async, &entityHandle, 
        loginResultBuffer.size(), loginResultBuffer.data(), &loginResult, nullptr);
    
    if (SUCCEEDED(hr))
    {
        std::wcout << L"Successfully logged in with Steam. Player ID: " 
                   << loginResult->playFabId << std::endl;
        // entityHandle is now ready for making API calls
    }
}
```

<Note>
  로그인에서 반환된 `PFEntityHandle`은 이후의 모든 PlayFab API 호출에 필요합니다. 이 핸들을 애플리케이션 수명 내내 사용할 수 있도록 유지하세요.
</Note>

## 3단계: 리소스 정리

애플리케이션이 종료될 때, 모든 리소스를 적절히 정리하여 메모리 누수를 방지하고 정상적인 종료를 보장하세요:

```cpp theme={null}
// Clean up in reverse order of initialization

// 1. Close the entity handle
if (entityHandle)
{
    PFEntityCloseHandle(entityHandle);
    entityHandle = nullptr;
    std::wcout << L"Entity handle closed." << std::endl;
}

// 2. Close the service config handle
if (serviceConfigHandle)
{
    PFServiceConfigCloseHandle(serviceConfigHandle);
    serviceConfigHandle = nullptr;
    std::wcout << L"Service config handle closed." << std::endl;
}

// 3. Uninitialize PlayFab
XAsyncBlock async{};
HRESULT hr = PFUninitializeAsync(&async);
if (SUCCEEDED(hr))
{
    hr = XAsyncGetStatus(&async, true); // Wait for completion
    if (SUCCEEDED(hr))
    {
        std::wcout << L"PlayFab uninitialized successfully." << std::endl;
    }
    else
    {
        std::wcerr << L"PlayFab uninitialization failed: 0x" << std::hex << hr << std::endl;
    }
}

std::wcout << L"Cleanup complete." << std::endl;
```

<Info>
  적절한 종료를 보장하기 위해 항상 초기화의 역순으로 리소스를 정리하세요.
</Info>

## 다음 단계

이제 SDK를 초기화하고 플레이어를 인증했으므로, PlayFab 서비스 호출을 시작할 준비가 되었습니다:

### 첫 번째 API 호출 만들기

* **[PlayFab 서비스 호출](/services/playfab/sdks/unified-sdk/quickstart-services)** - 플레이어 데이터를 관리하고 게임 서비스를 사용하기 위해 PlayFab API를 호출하는 방법 알아보기

### 핵심 개념

* [비동기 작업](/services/playfab/sdks/unified-sdk/async-model) - PlayFab의 비동기 프로그래밍 모델 이해
* [메모리 관리](/services/playfab/sdks/unified-sdk/memory-management) - SDK 메모리 관리를 위한 모범 사례
* [추적 및 진단](/services/playfab/sdks/unified-sdk/debug-trace) - 통합 디버깅 및 모니터링

### 고급 인증

* **다중 플랫폼 인증** - 여러 인증 공급자 지원
* **사용자 정의 ID 인증** - 자체 인증 시스템 사용
* **계정 연결** - 여러 인증 방법을 하나의 계정에 연결

### 문제 해결

**일반적인 문제 및 해결 방법:**

| 문제         | 해결 방법                                                   |
| ---------- | ------------------------------------------------------- |
| 링크 오류      | 필요한 모든 `.lib` 파일이 Additional Dependencies에 추가되었는지 확인하세요 |
| 런타임 DLL 오류 | 필요한 `.dll` 파일을 출력 디렉터리로 복사하세요                           |
| 인증 실패      | 타이틀 ID를 확인하고 네트워크 연결을 확인하세요                             |
| API 호출 실패  | 자세한 오류 정보를 확인하기 위해 추적을 활성화하세요                           |

## 참조 문서

* [PlayFab 통합 SDK API 참조](/services/playfab/api-references/c/pfauthentication/pfauthentication_members)
* [PlayFab Services API 참조](/services/playfab/api-references)
* [XBOX Game Development Kit 문서](https://docs.microsoft.com/gaming/gdk/)


## Related topics

- [PlayFab 통합 SDK 빠른 시작 설정](/ko/services/playfab/sdks/unified-sdk/quickstart-setup.md)
- [빠른 시작 (Windows) - Party 및 Multiplayer](/ko/services/playfab/sdks/unified-sdk/quickstart-windows-party.md)
- [빠른 시작 (Windows) - PlayFab 서비스 호출](/ko/services/playfab/sdks/unified-sdk/quickstart-services.md)
- [Windows용 C++ 빠른 시작](/ko/services/playfab/sdks/playfab-cpp/quickstart-windows.md)
- [NodeJS 빠른 시작](/ko/services/playfab/sdks/nodejs/quickstart.md)