Início rápido: macOS

Comece a usar o SDK do PlayFab Services para macOS. Siga estas etapas para incluir as bibliotecas no seu projeto e experimentar o código de exemplo da funcionalidade básica do PlayFab. Este início rápido ajuda você a fazer sua primeira chamada à API do PlayFab usando o SDK para macOS. Antes de continuar, verifique se você concluiu as etapas de Início rápido: Game Manager, que garantem que você tenha uma conta do PlayFab e esteja familiarizado com o PlayFab Game Manager.

Requisitos

Uma conta de desenvolvedor do PlayFab.
IDE XCode instalado.

Configuração do projeto

Baixe o SDK do PlayFab para macOS para o seu projeto na página de releases do SDK do PlayFab.

Integrar o SDK do PlayFab para C ao seu projeto

Adicionar os binários ao seu jogo

Depois de obter seus binários por download ou compilando a partir do código-fonte, você poderá integrá-los facilmente ao seu jogo/aplicativo. Você precisa adicionar os seguintes binários ao seu jogo:

HttpClient_macOS.xcframework
PlayFabCore_macOS.xcframework
PlayFabServices_macOS.xcframework

Siga estas instruções para adicioná-los:

No XCode, navegue até o destino desejado e selecione-o.
Na seção General, role para baixo e, na seção “Frameworks, Libraries, and Embedded Content”, selecione o sinal ”+”.
Pesquise seus binários PlayFabServices / PlayFabCore / HttpClient e selecione as pastas xcframework. (Você também pode selecionar uma biblioteca específica navegando dentro das pastas xcframework, mas é recomendável importar o pacote xcframework, pois ele funciona tanto para builds de dispositivo quanto de simulador.)
Depois que os binários forem importados com êxito, HttpClient_macOS, PlayFabCore_macOS e PlayFabServices_macOS serão listados em Frameworks, Libraries, and Embedded Content.

Adicionar os caminhos de pesquisa de cabeçalhos

Depois que os binários forem adicionados, você precisará garantir que os caminhos de pesquisa de cabeçalhos também estejam configurados corretamente.

Navegue até o seu projeto.
Selecione “Build Settings” e pesquise “Header Search Paths”.
Atualize o valor da propriedade para incluir os cabeçalhos do SDK. Adicione uma referência aos cabeçalhos encontrados na pasta include. Exemplo:
PlayFabCSdk-macOS/include

Siga as próximas etapas para fazer algumas chamadas de exemplo do PlayFab funcionarem:

Cabeçalhos

Inclua PFServices.h para ter acesso a toda a funcionalidade do PlayFab incluída.

#include <playfab/services/PFServices.h>

Inicialização

A inicialização do PlayFab requer duas chamadas de função: PFServicesInitialize e PFServiceConfigCreateHandle. O resultado dessa inicialização é um PFServiceConfigHandle. Você fornece esse identificador a uma chamada de login subsequente, direcionando a chamada para o título correto no back-end do PlayFab.

    HRESULT hr = PFServicesInitialize(nullptr); // Add your own error handling when FAILED(hr) == true

    PFServiceConfigHandle serviceConfigHandle{ nullptr };

    hr = PFServiceConfigCreateHandle(
            "https://ABCDEF.playfabapi.com",    // PlayFab API endpoint - obtained in the Game Manager
            "ABCDEF",                           // PlayFab Title id - obtained in the Game Manager
            &serviceConfigHandle);

Depois de ter um PFServiceConfigHandle, você pode usá-lo para fazer uma chamada de login de jogador. No SDK, use um método PFAuthenticationLoginWith*Async, como PFAuthenticationLoginWithAppleAsync. Essa função permite fazer login de um jogador no PlayFab usando o token de identidade de um usuário da Apple. (consulte a documentação da Apple sobre Authenticating users with Sign in with Apple). Depois de fazer uma chamada de login, você pode verificar o status da chamada com XAsyncGetStatus. O status começa como E_PENDING e muda para S_OK depois que a chamada é concluída com êxito. Se a chamada falhar por algum motivo, o status refletirá essa falha. O tratamento de erros em todas as chamadas do PlayFab Services funciona dessa forma. Junto com um resultado S_OK, você recebe um PFEntityHandle. Use esse identificador para fazer as chamadas subsequentes do PlayFab como o jogador conectado. Ele inclui todo o material necessário para se autenticar no serviço PlayFab como esse jogador.

PFAuthenticationLoginWithAppleRequest request{};
request.createAccount = true;
request.identityToken = identityToken; // A user identity token obtained from Apple

XAsyncBlock async{};
hr = PFAuthenticationLoginWithAppleAsync(serviceConfigHandle, &request, &async); // Add your own error handling when FAILED(hr) == true
hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage

std::vector<char> loginResultBuffer;
PFAuthenticationLoginResult const* loginResult;
size_t bufferSize;
hr = PFAuthenticationLoginWithAppleGetResultSize(&async, &bufferSize);
loginResultBuffer.resize(bufferSize);

PFEntityHandle entityHandle{ nullptr };
hr = PFAuthenticationLoginWithAppleGetResult(&async, &entityHandle, loginResultBuffer.size(), loginResultBuffer.data(), &loginResult, nullptr);

Chamadas de serviço

Depois de fazer login do jogador, você pode fazer chamadas ao back-end do PlayFab. Veja um exemplo de chamada para obter os arquivos armazenados no PlayFab para o jogador atual.

Obtendo a EntityKey

Algo que pode ser útil em algumas chamadas ao PlayFab é conhecer a PFEntityKey do jogador. Depois de ter um PFEntityToken, você pode recuperar uma PFEntityKey com PFEntityGetEntityKey.

    PFEntityKey const* pEntityKey{};
    std::vector<char> entityKeyBuffer;
    size_t size{};
    HRESULT hr = PFEntityGetEntityKeySize(entityHandle, &size); // Add your own error handling when FAILED(hr) == true

    entityKeyBuffer.resize(size);
    hr = PFEntityGetEntityKey(entityHandle, entityKeyBuffer.size(), entityKeyBuffer.data(), &pEntityKey, nullptr);

Chamando GetFiles

Todas as chamadas do PlayFab seguem um padrão semelhante: preparar o objeto de solicitação, fazer a chamada (usando o PFEntityHandle do login), criar um objeto para receber a resposta e, em seguida, chamar uma função GetResult para preencher o contêiner recém-criado.

    XAsyncBlock async{};
    PFDataGetFilesRequest requestFiles{};
    requestFiles.entity = pEntityKey;

    HRESULT hr = PFDataGetFilesAsync(entityHandle, &requestFiles, &async); // Add your own error handling when FAILED(hr) == true
    hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage

    size_t resultSize;
    hr = PFDataGetFilesGetResultSize(&async, &resultSize);

    std::vector<char> getFilesResultBuffer(resultSize);
    PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
    hr = PFDataGetFilesGetResult(&async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);

Limpeza

Quando seu jogo estiver pronto para ser desligado ou você precisar limpar o PlayFab por algum outro motivo, feche todos os identificadores abertos e chame PFServicesUninitializeAsync.

    PFEntityCloseHandle(entityHandle);
    entityHandle = nullptr;

    PFServiceConfigCloseHandle(serviceConfigHandle);
    serviceConfigHandle = nullptr;

    XAsyncBlock async{};
    HRESULT hr = PFServicesUninitializeAsync(&async); // Add your own error handling when FAILED(hr) == true
    hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage

Padrão de API assíncrona

O SDK do PlayFab Services segue o modelo de programação assíncrona implementado no GDK. Esse modelo de programação envolve o uso de tarefas e filas de tarefas fornecidas pela biblioteca XAsync. Esse modelo é consistente com outras funções e extensões do GDK (como a API do XBOX Services). Embora introduza alguma complexidade, ele também oferece um alto grau de controle sobre as operações assíncronas. Este exemplo mostra como fazer uma chamada assíncrona a PFDataGetFilesAsync.

    auto async = std::make_unique<XAsyncBlock>();
    async->callback = [](XAsyncBlock* async)
    {
        std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // take ownership of XAsyncBlock

        size_t resultSize;
        HRESULT hr = PFDataGetFilesGetResultSize(async, &resultSize);
        if (SUCCEEDED(hr))
        {
            std::vector<char> getFilesResultBuffer(resultSize);
            PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
            PFDataGetFilesGetResult(async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);
        }
    };

    PFDataGetFilesRequest requestFiles{};
    requestFiles.entity = m_pEntityKey;
    HRESULT hr = PFDataGetFilesAsync(m_entityHandle, &requestFiles, async.get());
    if (SUCCEEDED(hr))
    {
        async.release(); // at this point, the callback will be called so release the unique ptr
    }

Tratamento de erros

As operações XAsync concluídas retornam códigos de status HTTP. Um código de status de erro se manifesta como um HRESULT de falha, como HTTP_E_STATUS_NOT_FOUND, ao chamar XAsyncGetStatus() ou uma das APIs PF*Get(). Para ver as mensagens de erro detalhadas retornadas pelo serviço, consulte a próxima seção sobre depuração. Essas mensagens de erro detalhadas podem ser úteis durante o desenvolvimento para entender melhor como o serviço PlayFab reage às solicitações do cliente.

Depuração

A maneira mais fácil de ver os resultados e depurar qualquer chamada no SDK do PlayFab Services é habilitar o rastreamento de depuração. Habilitar o rastreamento de depuração permite tanto ver os resultados na janela de saída do depurador quanto conectar os resultados aos logs do próprio jogo.

Confira também

Documentação de referência da API

​Início rápido: macOS

​Requisitos

​Configuração do projeto

​Integrar o SDK do PlayFab para C ao seu projeto

​Adicionar os binários ao seu jogo

​Adicionar os caminhos de pesquisa de cabeçalhos

​Inicialização e login

​Cabeçalhos

​Inicialização

​Fazendo login

​Chamadas de serviço

​Obtendo a EntityKey

​Chamando GetFiles

​Limpeza

​Padrão de API assíncrona

​Tratamento de erros

​Depuração

​Confira também