Quickstart (Windows) - Core SDK Setup - XBOX Game Development Documentation

This guide shows you how to integrate the PlayFab Unified SDK into your Windows project, initialize the SDK, and authenticate a player. This is the foundation for making PlayFab API calls.

Prerequisites

Before you begin, complete the setup steps in Quickstart Setup to configure your development environment and project.

What you’ll accomplish

By the end of this quickstart, you’ll have:

Set up the PlayFab Unified SDK in your Windows project
Initialized the SDK with your Title ID
Authenticated a player using XBOX or Steam
Obtained an entity handle for making API calls
Properly cleaned up resources

Step 1: Initialize the SDK

Include required headers

Start by including the necessary PlayFab and XBOX Game Runtime headers in your project:

#include <playfab/core/PFCore.h>
#include <XGameRuntimeInit.h>

Initialize XBOX Gaming Runtime Services

The PlayFab Unified SDK requires XBOX Game Runtime. Initialize it first:

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;

Initialize PlayFab Core

Initialize the PlayFab SDK and create a service configuration handle. Replace ABCDEF with your actual PlayFab Title ID:

// 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;

You can find your Title ID in the Game Manager dashboard under your game’s settings.

Step 2: Authenticate a Player

PlayFab requires player authentication before making API calls. The SDK provides several authentication methods depending on your platform and requirements.

Choose your authentication method

Use PFAuthenticationLoginWithXUserAsync to log in with an XBOX user account. This is the recommended method for Windows and XBOX applications.

// 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
    }
}

For Steam-integrated games, use PFAuthenticationLoginWithSteamAsync with a Steam authentication ticket.

// 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
    }
}

The PFEntityHandle returned from login is required for all subsequent PlayFab API calls. Keep this handle available throughout your application’s lifetime.

Step 3: Clean up resources

When your application shuts down, properly clean up all resources to prevent memory leaks and ensure graceful termination:

// 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;

Always clean up resources in the reverse order of initialization to ensure proper shutdown.

Next steps

Now that you’ve initialized the SDK and authenticated a player, you’re ready to start calling PlayFab services:

Make your first API call

Calling PlayFab Services - Learn how to call PlayFab APIs to manage player data and use game services

Core concepts

Asynchronous operations - Understanding PlayFab’s async programming model
Memory management - Best practices for managing SDK memory
Tracing and diagnostics - Debugging and monitoring your integration

Advanced authentication

Multi-platform authentication - Support multiple authentication providers
Custom ID authentication - Use your own authentication system
Account linking - Link multiple authentication methods to one account

Troubleshooting

Common issues and solutions:

Issue	Solution
Linking errors	Ensure all required `.lib` files are added to Additional Dependencies
Runtime DLL errors	Copy required `.dll` files to your output directory
Authentication failures	Verify your Title ID and check network connectivity
API call failures	Enable tracing to see detailed error information

XBOX Services

PlayFab

Quickstart (Windows) - Core SDK Setup

Prerequisites

What you’ll accomplish

In this quickstart

Step 1: Initialize the SDK

Include required headers

Initialize XBOX Gaming Runtime Services

Initialize PlayFab Core

Step 2: Authenticate a Player

Choose your authentication method

Step 3: Clean up resources

Next steps

Make your first API call

Core concepts

Advanced authentication

Troubleshooting

Reference documentation

​Prerequisites

​What you’ll accomplish

​In this quickstart

​Step 1: Initialize the SDK

​Include required headers

​Initialize XBOX Gaming Runtime Services

​Initialize PlayFab Core

​Step 2: Authenticate a Player

​Choose your authentication method

​Option A: Login with XBOX (Recommended for Windows/XBOX)

​Option B: Login with Steam

​Step 3: Clean up resources

​Next steps

​Make your first API call

​Core concepts

​Advanced authentication

​Troubleshooting

​Reference documentation

Prerequisites

What you’ll accomplish

In this quickstart

Step 1: Initialize the SDK

Include required headers

Initialize XBOX Gaming Runtime Services

Initialize PlayFab Core

Step 2: Authenticate a Player

Choose your authentication method

Option A: Login with XBOX (Recommended for Windows/XBOX)

Option B: Login with Steam

Step 3: Clean up resources

Next steps

Make your first API call

Core concepts

Advanced authentication

Troubleshooting

Reference documentation