Início rápido (Windows) - Configuração do SDK Core - XBOX Game Development Documentation

Este guia mostra como integrar o SDK unificado do PlayFab ao seu projeto do Windows, inicializar o SDK e autenticar um jogador. Essa é a base para fazer chamadas à API do PlayFab.

Pré-requisitos

Antes de começar, conclua as etapas de configuração em Configuração do início rápido para configurar seu ambiente de desenvolvimento e seu projeto.

O que você vai realizar

Ao final deste início rápido, você terá:

Configurado o SDK unificado do PlayFab no seu projeto do Windows
Inicializado o SDK com o ID do seu título
Autenticado um jogador usando o XBOX ou o Steam
Obtido um identificador de entidade para fazer chamadas à API
Limpado os recursos corretamente

Etapa 1: Inicializar o SDK

Incluir os cabeçalhos necessários

Comece incluindo os cabeçalhos necessários do PlayFab e do XBOX Game Runtime no seu projeto:

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

Inicializar o XBOX Gaming Runtime Services

O SDK unificado do PlayFab exige o XBOX Game Runtime. Inicialize-o primeiro:

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;

Inicializar o PlayFab Core

Inicialize o SDK do PlayFab e crie um identificador de configuração de serviço. Substitua ABCDEF pelo ID real do seu título do PlayFab:

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

Você pode encontrar o ID do seu título no painel do Game Manager, nas configurações do seu jogo.

Etapa 2: Autenticar um jogador

O PlayFab exige a autenticação do jogador antes de fazer chamadas à API. O SDK fornece vários métodos de autenticação, dependendo da sua plataforma e dos seus requisitos.

Escolha seu método de autenticação

Opção A: Logon com o XBOX (recomendado para Windows/XBOX)

Use PFAuthenticationLoginWithXUserAsync para fazer logon com uma conta de usuário do XBOX. Esse é o método recomendado para aplicativos do Windows e do XBOX.

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

Opção B: Logon com o Steam

Para jogos integrados ao Steam, use PFAuthenticationLoginWithSteamAsync com um tíquete de autenticação do Steam.

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

O PFEntityHandle retornado pelo logon é necessário para todas as chamadas à API do PlayFab subsequentes. Mantenha esse identificador disponível durante todo o tempo de vida do aplicativo.

Etapa 3: Limpar os recursos

Quando o aplicativo for encerrado, limpe corretamente todos os recursos para evitar vazamentos de memória e garantir um encerramento normal:

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

Sempre limpe os recursos na ordem inversa da inicialização para garantir um encerramento adequado.

Próximas etapas

Agora que você inicializou o SDK e autenticou um jogador, está pronto para começar a chamar os serviços do PlayFab:

Faça sua primeira chamada à API

Chamando o PlayFab Services - Saiba como chamar as APIs do PlayFab para gerenciar os dados do jogador e usar os serviços do jogo

Conceitos principais

Operações assíncronas - Entendendo o modelo de programação assíncrona do PlayFab
Gerenciamento de memória - Práticas recomendadas para gerenciar a memória do SDK
Rastreamento e diagnóstico - Depuração e monitoramento da sua integração

Autenticação avançada

Autenticação multiplataforma - Ofereça suporte a vários provedores de autenticação
Autenticação com ID personalizado - Use seu próprio sistema de autenticação
Vinculação de contas - Vincule vários métodos de autenticação a uma única conta

Solução de problemas

Problemas comuns e soluções:

Problema	Solução
Erros de vinculação	Verifique se todos os arquivos `.lib` necessários foram adicionados em Dependências Adicionais
Erros de DLL em tempo de execução	Copie os arquivos `.dll` necessários para o diretório de saída
Falhas de autenticação	Verifique o ID do título e a conectividade de rede
Falhas em chamadas à API	Habilite o rastreamento para ver informações de erro detalhadas

XBOX Services

PlayFab

Início rápido (Windows) - Configuração do SDK Core

Pré-requisitos

O que você vai realizar

Neste início rápido

Etapa 1: Inicializar o SDK

Incluir os cabeçalhos necessários

Inicializar o XBOX Gaming Runtime Services

Inicializar o PlayFab Core

Etapa 2: Autenticar um jogador

Escolha seu método de autenticação

Opção A: Logon com o XBOX (recomendado para Windows/XBOX)

Opção B: Logon com o Steam

Etapa 3: Limpar os recursos

Próximas etapas

Faça sua primeira chamada à API

Conceitos principais

Autenticação avançada

Solução de problemas

Documentação de referência

​Pré-requisitos

​O que você vai realizar

​Neste início rápido

​Etapa 1: Inicializar o SDK

​Incluir os cabeçalhos necessários

​Inicializar o XBOX Gaming Runtime Services

​Inicializar o PlayFab Core

​Etapa 2: Autenticar um jogador

​Escolha seu método de autenticação

​Opção A: Logon com o XBOX (recomendado para Windows/XBOX)

​Opção B: Logon com o Steam

​Etapa 3: Limpar os recursos

​Próximas etapas

​Faça sua primeira chamada à API

​Conceitos principais

​Autenticação avançada

​Solução de problemas

​Documentação de referência

Pré-requisitos

O que você vai realizar

Neste início rápido

Etapa 1: Inicializar o SDK

Incluir os cabeçalhos necessários

Inicializar o XBOX Gaming Runtime Services

Inicializar o PlayFab Core

Etapa 2: Autenticar um jogador

Escolha seu método de autenticação

Opção A: Logon com o XBOX (recomendado para Windows/XBOX)

Opção B: Logon com o Steam

Etapa 3: Limpar os recursos

Próximas etapas

Faça sua primeira chamada à API

Conceitos principais

Autenticação avançada

Solução de problemas

Documentação de referência