> ## 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 設定

> 將 PlayFab Unified SDK 新增至 Windows 專案、初始化 Core，並使用 XBOX 或 Steam 驗證玩家以取得 PFEntityHandle。

本指南說明如何將 PlayFab Unified SDK 整合至您的 Windows 專案、初始化 SDK，以及驗證玩家。這是進行 PlayFab API 呼叫的基礎。

## 必要條件

開始之前，請完成[快速入門設定](/zh-TW/services/playfab/sdks/unified-sdk/quickstart-setup)中的設定步驟，以設定您的開發環境和專案。

## 您將完成的工作

完成本快速入門之後，您將會：

* 在您的 Windows 專案中設定 PlayFab Unified SDK
* 使用您的遊戲識別碼初始化 SDK
* 使用 XBOX 或 Steam 驗證玩家
* 取得用於進行 API 呼叫的實體控制代碼
* 正確地清除資源

## 本快速入門內容

1. [初始化 SDK](#step-1-initialize-the-sdk)
2. [驗證玩家](#step-2-authenticate-a-player)
3. [清除資源](#step-3-clean-up-resources)

<a id="step-1-initialize-the-sdk" />

## 步驟 1：初始化 SDK

### 包含必要的標頭

首先，在您的專案中包含必要的 PlayFab 和 XBOX Game Runtime 標頭：

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

### 初始化 XBOX Gaming Runtime Services

PlayFab Unified 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 遊戲識別碼：

```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>
  您可以在 [Game Manager 儀表板](https://developer.playfab.com)中遊戲的設定下找到您的遊戲識別碼。
</Tip>

<a id="step-2-authenticate-a-player" />

## 步驟 2：驗證玩家

PlayFab 要求在進行 API 呼叫之前先驗證玩家。SDK 會根據您的平台和需求提供數種驗證方法。

### 選擇您的驗證方法

#### 選項 A：使用 XBOX 登入 (建議用於 Windows/XBOX)

使用 `PFAuthenticationLoginWithXUserAsync` 以 XBOX 使用者帳戶登入。這是 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 的遊戲，請使用 `PFAuthenticationLoginWithSteamAsync` 搭配 Steam 驗證票證。

```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>

<a id="step-3-clean-up-resources" />

## 步驟 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 服務](/zh-TW/services/playfab/sdks/unified-sdk/quickstart-services)** - 了解如何呼叫 PlayFab API 來管理玩家資料和使用遊戲服務

### 核心概念

* [非同步作業](/zh-TW/services/playfab/sdks/unified-sdk/async-model) - 了解 PlayFab 的非同步程式設計模型
* [記憶體管理](/zh-TW/services/playfab/sdks/unified-sdk/memory-management) - 管理 SDK 記憶體的最佳做法
* [追蹤和診斷](/zh-TW/services/playfab/sdks/unified-sdk/debug-trace) - 偵錯和監視您的整合

### 進階驗證

* **多平台驗證** - 支援多個驗證提供者
* **自訂識別碼驗證** - 使用您自己的驗證系統
* **帳戶連結** - 將多種驗證方法連結至一個帳戶

### 疑難排解

**常見問題和解決方案：**

| 問題 | 解決方案 |
| - | - |
| 連結錯誤 | 確定所有必要的 `.lib` 檔案都已新增至 Additional Dependencies |
| 執行階段 DLL 錯誤 | 將必要的 `.dll` 檔案複製到您的輸出目錄 |
| 驗證失敗 | 確認您的遊戲識別碼並檢查網路連線 |
| API 呼叫失敗 | 啟用追蹤以查看詳細的錯誤資訊 |

## 參考文件

* [PlayFab Unified SDK API 參考](/zh-TW/services/playfab/api-references/c/pfauthentication/pfauthentication_members)
* [PlayFab Services API 參考](/zh-TW/services/playfab/api-references)
* [XBOX Game Development Kit 文件](https://docs.microsoft.com/gaming/gdk/)


## Related topics

- [快速入門 (Windows) - Party 和 Multiplayer](/zh-TW/services/playfab/sdks/unified-sdk/quickstart-windows-party.md)
- [快速入門 (Windows) - 呼叫 PlayFab 服務](/zh-TW/services/playfab/sdks/unified-sdk/quickstart-services.md)
- [PlayFab Unified SDK 快速入門設定](/zh-TW/services/playfab/sdks/unified-sdk/quickstart-setup.md)
- [SDK Generator 快速入門](/zh-TW/services/playfab/sdks/sdkgenerator/quickstart.md)
- [適用於 Windows 的 C++ 快速入門](/zh-TW/services/playfab/sdks/playfab-cpp/quickstart-windows.md)