Inicio rápido: Linux

Introducción al SDK de PlayFab Services para Linux. Siga estos pasos para incluir las bibliotecas en su proyecto y probar el código de ejemplo de las funciones básicas de PlayFab. Este inicio rápido le ayuda a realizar su primera llamada a la API de PlayFab con Linux. Antes de continuar, asegúrese de haber completado los pasos de Inicio rápido: Game Manager, que garantizan que tiene una cuenta de PlayFab y que está familiarizado con Game Manager de PlayFab.

Requisitos

Una cuenta de desarrollador de PlayFab.
Ubuntu 22.04 o posterior, o Subsistema de Windows para Linux con la distribución Ubuntu 22.04 o posterior. Consulte Cómo instalar Linux en Windows con WSL. Otras distribuciones de Linux deberían funcionar, pero no se han verificado.

Configuración del proyecto

Descargue el SDK de PlayFab para Linux en su proyecto desde la página de versiones del SDK de PlayFab.

Integración del SDK de C de PlayFab en su propio proyecto

Adición de archivos binarios al juego

Deberá integrar en su proyecto los archivos de objetos compartidos (.so). Puede compilar los archivos binarios usted mismo o descargarlos desde la página de versiones. Los pasos siguientes están escritos partiendo del supuesto de que ha creado un proyecto nuevo.

Adición de los archivos .so

Estos archivos se integran en su proyecto mediante CMake.

Descomprima la versión del SDK de PlayFab para Linux y coloque su contenido en el directorio que desee.
Con target_include_directories u otra función equivalente, agregue esta lista de encabezados de la versión del SDK de PlayFab:

Por ejemplo:

target_include_directories(
    [YOUR PROJECT NAME]
    "[LOCATION OF PLAYFAB LINUX SDK]/include"
)

Con target_link_libraries u otra función equivalente, vincule las ubicaciones de los archivos .so a su proyecto.

Por ejemplo:

set(PLAYFAB_SERVICES_PATH "[LOCATION OF PLAYFAB LINUX SDK]/bin/PlayFabServices.Linux.so")
set(PLAYFAB_CORE_PATH "[LOCATION OF PLAYFAB LINUX SDK]/bin/PlayFabCore.Linux.so")
set(LIBHTTPCLIENT_PATH "[LOCATION OF PLAYFAB LINUX SDK]/bin/libHttpClient.Linux.so")

target_link_librariesc(
    [YOUR PROJECT NAME]
    ${PLAYFAB_SERVICES_PATH}
    ${PLAYFAB_CORE_PATH}
    ${LIBHTTPCLIENT_PATH}
)

El proyecto ya está totalmente configurado para usar el SDK de PlayFab Services para Linux. Siga los pasos siguientes para hacer funcionar algunas llamadas de ejemplo.

Inicialización e inicio de sesión

Encabezados

Incluya PFServices.h para obtener acceso a toda la funcionalidad de PlayFab incluida:

#include <playfab/services/PFServices.h>

Inicialización

La inicialización de PlayFab requiere dos llamadas de función: PFServicesInitialize y PFServiceConfigCreateHandle. El resultado de esta inicialización es un PFServiceConfigHandle. Proporcione este identificador a una llamada de inicio de sesión posterior para dirigir la llamada al título correcto en el back-end de 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);

Inicio de sesión

TBD Una vez que tenga un PFServiceConfigHandle, puede usarlo para realizar una llamada de inicio de sesión de jugador. En el SDK, use un método PFAuthenticationLoginWith*Async como PFAuthenticationLoginWithCustomIDAsync. Esta función le permite iniciar la sesión de un jugador en PlayFab mediante un identificador personalizado. Después de realizar una llamada de inicio de sesión, puede comprobar el estado de la llamada con XAsyncGetStatus. El estado comienza como E_PENDING y cambia a S_OK una vez que la llamada se completa correctamente. Si la llamada produce un error por algún motivo, el estado refleja ese error. El control de errores en todas las llamadas de PlayFab Services funciona de esta manera. Junto con un resultado S_OK, recibe un PFEntityHandle. Use este identificador para realizar llamadas posteriores a PlayFab como el jugador que inició sesión. Incluye todo el material necesario para autenticarse en el servicio de PlayFab como ese jugador.

    PFAuthenticationLoginWithCustomIDRequest request{};
    request.createAccount = true;
    request.customId = "player1";

    XAsyncBlock async{};
    HRESULT hr = PFAuthenticationLoginWithCustomIDAsync(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 = PFAuthenticationLoginWithCustomIDGetResultSize(&async, &bufferSize);
    loginResultBuffer.resize(bufferSize);

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

Llamadas al servicio

Después de que el jugador inicie sesión, ya puede realizar llamadas al back-end de PlayFab. Este es un ejemplo de una llamada para obtener los archivos almacenados en PlayFab para el jugador actual.

Obtención de EntityKey

Algo que puede resultar útil para algunas llamadas a PlayFab es conocer la PFEntityKey del jugador. Una vez que tenga un PFEntityToken, puede recuperar una PFEntityKey con 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);

Llamada a GetFiles

Todas las llamadas de PlayFab siguen un patrón similar: preparar el objeto de solicitud, realizar la llamada (mediante el PFEntityHandle del inicio de sesión), crear un objeto para recibir la respuesta y, después, llamar a una función GetResult para rellenar el contenedor recién creado.

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

Limpieza

Cuando el juego esté listo para cerrarse o necesite limpiar PlayFab por algún otro motivo, asegúrese de cerrar todos los identificadores abiertos y llamar a 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

Patrón de API asincrónica

El SDK de PlayFab Services sigue el modelo de programación asincrónica implementado en el GDK. Este modelo de programación implica el uso de tareas y colas de tareas proporcionadas por la biblioteca XAsync. Este modelo es coherente con otras funciones y extensiones del GDK (como la API de XBOX Services). Aunque presenta cierta complejidad, también aporta un alto grado de control sobre las operaciones asincrónicas. En este ejemplo se muestra cómo realizar una llamada asincrónica 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
    }

Control de errores

Las operaciones XAsync completadas devuelven códigos de estado HTTP. Un código de estado de error se manifiesta como un HRESULT de error, como HTTP_E_STATUS_NOT_FOUND, al llamar a XAsyncGetStatus() o a una de las API PF*Get(). Para ver los mensajes de error detallados que devuelve el servicio, consulte la sección siguiente sobre depuración. Estos mensajes de error detallados pueden ser útiles durante el desarrollo para comprender mejor cómo reacciona el servicio de PlayFab a las solicitudes del cliente.

Depuración

La manera más fácil de ver los resultados y depurar las llamadas en el SDK de PlayFab Services es habilitar el seguimiento de depuración. Habilitar el seguimiento de depuración le permite ver los resultados en la ventana de salida del depurador y conectar los resultados a los registros propios de su juego.

Referencia

Documentación de referencia de la API

​Inicio rápido: Linux

​Requisitos

​Configuración del proyecto

​Integración del SDK de C de PlayFab en su propio proyecto

​Adición de archivos binarios al juego

​Adición de los archivos .so

​Inicialización e inicio de sesión

​Encabezados

​Inicialización

​Inicio de sesión

​Llamadas al servicio

​Obtención de EntityKey

​Llamada a GetFiles

​Limpieza

​Patrón de API asincrónica

​Control de errores

​Depuración

​Referencia