{"id":23163112,"url":"https://github.com/playfab/playfabcsdk","last_synced_at":"2025-08-18T03:32:02.772Z","repository":{"id":184055828,"uuid":"647932897","full_name":"PlayFab/PlayFabCSdk","owner":"PlayFab","description":"Cross-Platform C/C++ PlayFab Services SDK","archived":false,"fork":false,"pushed_at":"2024-11-28T05:55:26.000Z","size":4189,"stargazers_count":7,"open_issues_count":0,"forks_count":4,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-05T19:22:28.936Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://learn.microsoft.com/en-us/gaming/playfab/sdks/c/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PlayFab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-31T20:55:04.000Z","updated_at":"2025-03-10T02:25:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"fe3bb5ba-2698-40cb-9404-07a3f1d4cce5","html_url":"https://github.com/PlayFab/PlayFabCSdk","commit_stats":null,"previous_names":["playfab/playfabcsdk"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/PlayFab/PlayFabCSdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PlayFab%2FPlayFabCSdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PlayFab%2FPlayFabCSdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PlayFab%2FPlayFabCSdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PlayFab%2FPlayFabCSdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PlayFab","download_url":"https://codeload.github.com/PlayFab/PlayFabCSdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PlayFab%2FPlayFabCSdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270940360,"owners_count":24671669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-18T00:16:21.904Z","updated_at":"2025-08-18T03:32:00.606Z","avatar_url":"https://github.com/PlayFab.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PlayFabCSdk\nCross-Platform C/C++ PlayFab SDK.\n\nThis SDK currently supports the following platforms:\n- Windows (Win32) x64\n- GDK (Xbox and Windows)\n- Linux (eg. Ubuntu 22.04 or Windows Subsystem for Linux)\n- iOS\n- macOS\n- Android\n- PlayStation 4/5 (private repo)\n- Nintendo Switch (private repo)\n\nFor per-platform getting started guides and a complete list of available APIs, check out the [online documentation](https://learn.microsoft.com/gaming/playfab/sdks/c).\n\nTo gain access to platforms supported through private repos, [Request Access](https://learn.microsoft.com/gaming/playfab/features/multiplayer/networking/request-access-for-sdks-samples).\n\n## Requirements\n\n### Win32 and GDK\n- A [PlayFab developer account](https://developer.playfab.com).\n- [Visual Studio 2022](https://visualstudio.microsoft.com/) installed (to build from source).\n- (For GDK) [Microsoft Game Development Kit](https://learn.microsoft.com/gaming/gdk/) installed.\n\n### iOS / macOS\n- A [PlayFab developer account](https://developer.playfab.com).\n- [XCode](https://developer.apple.com/xcode/) IDE installed (to build from source).\n\n### Android\n- A [PlayFab developer account](https://developer.playfab.com).\n- [Android Studio](https://developer.android.com/studio) IDE installed (to build from source).\n\n## Project setup\n\n### Building with binary release package\n\nDownload the most recent release of the SDK from [PlayFabCSdk releases](https://github.com/PlayFab/PlayFabCSdk/releases). \n\n#### Integrate PlayFab C SDK into your own project - Visual Studio (Win32 and GDK)\n\nEach release package contains the required headers, binaries, and property sheet file (Win32 - PlayFabServicesSDK.Win32.props, GDK - PlayFabServicesSDK.GDK.props) that can be imported to your project to automatically add references.\n\nYou can import the props file manually by editing the .vcxproj files directly or by opening the Property Manager window in Visual Studio, right clicking on the project, and choosing __Add Existing Property Sheet__. After importing the appropriate props file, the headers should be available in your include path and references to the PlayFabServices library and its dependecies will be automatically added.\n\n\u003e __Note for GDK__: It is possible for other GDK extensions such as the Xbox Services API or libHttpClient to be included as references automatically in projects.\nAny duplicate references will need to be removed manually.\nTo do this, you can manage extensions in Visual Studio through __Project -\u003e Properties -\u003e Gaming Desktop -\u003e Gaming Extension Libraries__.\n\n#### Integrate PlayFab C SDK into your own project - XCode\n\n##### Add binaries to your game\n\nAfter getting your binaries by download or building from source you should be able to easily integrate them into your game/app.\n\nFollow these instructions to add them:\n\n1. In XCode, navigate to your desired target and select it.\n2. Scroll down and in the \"**Frameworks, Libraries, and Embedded Content**\" section, click on the \"**+**\" sign.\n3. Search for your **PlayFabServices** / **PlayFabCore** / **HttpClient** binaries. (_If you downloaded the xcframework file you can also select and it will automatically import whatever library is required independently if you're building for devices or simulator._)\n\n##### Add Header search paths\n\nOnce binaries have been added you'll need to ensure that header search paths are also correctly set up.\n\n1. Navigate to your project.\n2. Click on \"**Build Settings**\" and then search for \"**Header Search Paths**\".\n3. Update the property value to include the SDK Headers. Please note that if you are using binaries from the downloaded release package you can simply reference the headers found in the **include** folder. However, if you are using binaries built from source you'll need to include the following paths:\n    ```\n    PlayFab.C/Source/PlayFabServices/Include/Generated/\n    PlayFab.C/Source/PlayFabCore/Include/\n    PlayFab.C/Source/PlayFabCore/Include/Generated\n    libHttpClient/Include\n    ```\n\n#### Integrate PlayFab C SDK into your own project - Android Studio\n\n##### Add Shared Objects and Header files\n\n1. Using __target_include_directories__ or another equivalent function, add the headers under \"Include\" from the PlayFab SDK release:\n```\nTARGET_INCLUDE_DIRECTORIES(\n    ${PROJECT_NAME}\n    \"Include\"\n)\n```\n\nIf you're building from source, add this list of headers from the PlayFab SDK repository:\n\n```\n    \"PlayFab.C/Source/PlayFabServices/Include\"\n    \"PlayFab.C/Source/PlayFabServices/Include/Generated\"\n    \"PlayFab.C/Source/PlayFabCore/Include\"\n    \"PlayFab.C/Source/PlayFabCore/Include/Generated\"\n    \"libHttpClient/Include\"\n```\n\n3. Using __target_link_libraries__ or another equivalent function, link the locations of the .so files to your project.\n\n    For example:\n\n```cmake\nset(PLAYFAB_SERVICES_PATH \"[LOCATION OF YOUR FILE]/libPlayFabServices.Android.so\")\n\nset(PLAYFAB_CORE_PATH \"[LOCATION OF YOUR FILE]/libPlayFabCore.Android.so\")\n\nset(LIBHTTPCLIENT_PATH \"[LOCATION OF YOUR FILE]/libHttpClient.Android.so\")\n\nTARGET_LINK_LIBRARIES(\n    [YOUR PROJECT NAME]\n    ${PLAYFAB_SERVICES_PATH}\n    ${PLAYFAB_CORE_PATH}\n    ${LIBHTTPCLIENT_PATH}\n)\n```\n\n##### Add Android Archive files\n\n1. Create a libs folder within app level Android project directory.\n\n2. Copy the .aar files into the libs folder.\n\n3. In app level build.gradle file, the one in the same directory as the libs folder, add these lines to the dependencies section. The second line is required as a dependency for libHttpClient.\n```gradle\nimplementation fileTree(dir: 'libs', include: ['*.aar'])\nimplementation 'com.squareup.okhttp3:okhttp:4.9.1'\n```\n\n\n### Cloning source\n\nThis SDK depends on some external third-party open source libraries referenced as git submodules in directory `/External`. Please make sure to use `--recurse-submodules` command line parameter when cloning this git repo:\n```\ngit clone --recurse-submodules https://github.com/PlayFab/PlayFabCSdk\n```\nor run the following commands to sync the content of submodules if the repo was cloned earlier without the `--recurse-submodules` parameter:\n\n```\ngit submodule update --init --recursive\n```\n\n### Building from source for Windows and GDK\n\nAfter cloning this repository and its submodules, you can build the libraries by opening the solution file PlayFab.C.vs2022.sln. That solution contains the PlayFabServices project, its dependencies, and a test app. After building, the binaries will be in a subdirectory within \\Out.\n\n#### Import Property Sheet (Windows and GDK)\n\nTo add a reference to the PlayFabServices projects to your own title, import the \\Build\\PlayFabServices.import.props file to your project. You can do this manually by editing the .vcxproj files directly or by opening the Property Manager window in Visual Studio, right clicking on the project, and choosing __Add Existing Property Sheet__. Note that the props file differs from the PlayFabServicesSDK.Win32.props mentioned above - it adds references to the projects instead of the prebuilt binaries.\n\n#### Building (Windows and GDK)\n\nTo add a reference to the PlayFabServices projects to your own title, import the \\Build\\PlayFabServices.import.props file to your project. You can do this manually by editing the .vcxproj files directly or by opening the Property Manager window in Visual Studio, right clicking on the project, and choosing __Add Existing Property Sheet__. Note that the props file differs from the PlayFabServicesSDK.Win32.props mentioned above - it adds references to the projects instead of the prebuilt binaries.\n\n#### PlayFabServicesTestApp\n\nThe included test app __PlayFabServicesTestApp__ project will build as is, but some additional setup is required before it will run. The __\\Test\\testTitleData.json__ file needs to be populated with a valid titleId, developer secret key, and connection string. Additionally, some APIs that are disabled by default need to be enabled via the PlayFab developer portal.\n\nEven without making those changes, the __PlayFabServicesTestApp__ source code serves as a good example of basic PlayFabServices SDK usage.\n\n### Building from source for Linux\n\nAfter cloning this repository and its submodules, you can build the libraries by running\n\n```\n./Build/PlayFabServices.Linux/PlayFabServices_Linux.bash\n```\nFor more detail on script options see [PlayFabServices_Linux](Build/PlayFabServices.Linux/README.md)\n\nOnce built, the shared library can be used by adding this to your project's CMakeLists.txt:\n\n```\nfind_package(PlayFabServicesLinux REQUIRED)\ntarget_link_libraries(${PROJECT_NAME} PUBLIC PlayFabServicesLinux)\n```\n\nwhen running cmake, add this option and adjust the path as needed to tell it where package material can be found:\n\n```\n-D PlayFabServicesLinux_DIR=./Int/CMake/PlayFabServicesLinux\n```\n\nSee `.\\Test\\PlayFabServicesTestApp\\Linux` for example CMake usage.\n\n### Building from source for iOS\n\nAfter cloning this repository and its submodules, you can build the libraries by opening the workspace [PlayFab.C.Apple.xcworkspace](Build/PlayFab.C.Apple/PlayFab.C.Apple.xcworkspace) with XCode, then follow these steps:\n\n1. Select the scheme you want to build.\n- If you want to build PlayFabServices and PlayFabCore frameworks, select **PlayFabServices_iOS**/**PlayFabServices_._macOS** scheme and build. This scheme will generate the frameworks required to use PlayFab SDK:\n    - PlayFabCore_[iOS/macOS].framework\n    - PlayFabServices_[iOS/macOS].framework\n    - HttpClient_[iOS/macOS].framework\n\n- If you want to run the Test App, select the **PlayFabServicesTestApp_._iOS**/**PlayFabServicesTestApp_macOS** scheme, build and run the app.\n\n2. Select the run destination. \n\n- For macOS you should be able to run on your own Mac, however, for iOS, you should select a Simulator running iOS 16.2 (or later) or you can run it on a physical devices attached to your Mac. Be aware that libraries built for simulators won't work on real devices and viceversa, so you need to choose the run destination based on where you want to run your app.\n\n3. Grab the binaries. There are 2 different ways to do it:\n\n    1. Binaries will be placed in XCode default build directory which it's in the DerivedData folder usually located in:\n\n        ``~/Library/Developer/Xcode/DerivedData``\n\n        In there, you can go to the target folder and navigate to the Build/Products folder to get all the binaries.\n\n    2. Another way to get to the binaries if you want to navigate directly to them:\n    \n        1. In the workspace navigation on XCode go to \"**Products**\" and expand it.\n        2. Right-click on the framework generated and click \"**Show on Finder**\".\n\n### Building from source for Android\n\nAfter cloning this repository and its submodules, you can build the libraries from the `PlayFab.C/Build/PlayFabServices.Android.Workspace` directory by running:\n```\n./gradlew assembleFull\n```\n\nThis will build the library in two configurations, debug and release, and two Android ABIs, arm64-v8a and x86_64.\n\nIf you wish to build separately for a single configuration, ABI, or both, the command can be freely mix and matched for this purpose. \n\nSome examples of altering the command:\n\nThis builds for debug arm64-v8a and debug x86_64.\n```\n./gradlew assembleFullDebug\n```\n\nThis builds for release x86_64.\n```\n./gradlew assemblex86_64Release\n```\n\n## Init and Logging in\n\n### Headers\n\nInclude __PFServices.h__ to get access to all included PlayFab functionality:\n\n```cpp\n#include \u003cplayfab/services/PFServices.h\u003e\n```\n\n### Initialization\n\nPlayFab initialization requires two function calls: __PFServicesInitialize__ and __PFServiceConfigCreateHandle__. The result of this initialization is a __PFServiceConfigHandle__. You provide this handle to a subsequent login call, directing the call to the correct title in the PlayFab backend.\n\n```cpp\n    HRESULT hr = PFServicesInitialize(nullptr); // Add your own error handling when FAILED(hr) == true\n\n    PFServiceConfigHandle serviceConfigHandle{ nullptr };\n\n    hr = PFServiceConfigCreateHandle(\n            \"https://ABCDEF.playfabapi.com\",    // PlayFab API endpoint - obtained in the Game Manager\n            \"ABCDEF\",                           // PlayFab Title id - obtained in the Game Manager\n            \u0026serviceConfigHandle);\n```\n\n### Logging in\n\nOnce you have a __PFServiceConfigHandle__, you can use it to make a player login call. In the SDK, use a __PFAuthenticationLoginWith\\*Async__ method like __PFAuthenticationLoginWithCustomIDAsync__. This function allows you to log in a player to PlayFab using a custom string, which is useful during development and testing.\n\nAfter making a login call, you can check the status of the call with __XAsyncGetStatus__. The status starts as __E_PENDING__ and changes to __S_OK__ after the call completes successfully. If the call fails for some reason, the status reflects that failure. Error handling on all PlayFab Services calls works this way.\n\nAlong with an __S_OK__ result, you get back a __PFEntityHandle__. You use this handle to make subsequent PlayFab calls as the logged in player. It includes any material required to authenticate with the PlayFab service as that player.\n\n```cpp\n    PFAuthenticationLoginWithCustomIDRequest request{};\n    request.createAccount = true;\n    request.customId = \"player1\";\n\n    XAsyncBlock async{};\n    HRESULT hr = PFAuthenticationLoginWithCustomIDAsync(serviceConfigHandle, \u0026request, \u0026async); // Add your own error handling when FAILED(hr) == true\n    hr = XAsyncGetStatus(\u0026async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage\n\n    std::vector\u003cchar\u003e loginResultBuffer;\n    PFAuthenticationLoginResult const* loginResult;\n    size_t bufferSize;\n    hr = PFAuthenticationLoginWithCustomIDGetResultSize(\u0026async, \u0026bufferSize);\n    loginResultBuffer.resize(bufferSize);\n\n    PFEntityHandle entityHandle{ nullptr };\n    hr = PFAuthenticationLoginWithCustomIDGetResult(\u0026async, \u0026entityHandle, loginResultBuffer.size(), loginResultBuffer.data(), \u0026loginResult, nullptr);\n```\n\n## Service Calls\n\nAfter logging the player in, you can now make calls to the PlayFab backend. Here's an example of a call to get files stored in PlayFab for the current player.\n\n### Getting the EntityKey\n\nOne thing that can be useful for some calls to PlayFab is knowing the __PFEntityKey__ of the player. Once you have a __PFEntityToken__, you can retrieve a __PFEntityKey__ with __PFEntityGetEntityKey__.\n\n```cpp\n    PFEntityKey const* pEntityKey{};\n    std::vector\u003cchar\u003e entityKeyBuffer;\n    size_t size{};\n    HRESULT hr = PFEntityGetEntityKeySize(entityHandle, \u0026size); // Add your own error handling when FAILED(hr) == true\n\n    entityKeyBuffer.resize(size);\n    hr = PFEntityGetEntityKey(entityHandle, entityKeyBuffer.size(), entityKeyBuffer.data(), \u0026pEntityKey, nullptr);\n```\n\n### Calling GetFiles\n\nAll PlayFab calls follow a similar pattern of preparing the request object, making the call (using the __PFEntityHandle__ from login), creating an object to receive the response, and then calling a __GetResult__ function to fill the newly created container.\n\n```cpp\n    XAsyncBlock async{};\n    PFDataGetFilesRequest requestFiles{};\n    requestFiles.entity = pEntityKey;\n\n    HRESULT hr = PFDataGetFilesAsync(entityHandle, \u0026requestFiles, \u0026async); // Add your own error handling when FAILED(hr) == true\n    hr = XAsyncGetStatus(\u0026async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage\n\n    size_t resultSize;\n    hr = PFDataGetFilesGetResultSize(\u0026async, \u0026resultSize);\n\n    std::vector\u003cchar\u003e getFilesResultBuffer(resultSize);\n    PFDataGetFilesResponse* getFilesResponseResult{ nullptr };\n    hr = PFDataGetFilesGetResult(\u0026async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), \u0026getFilesResponseResult, nullptr);\n```\n\n## Clean up\n\nWhen your game is ready to shut down or you need to clean up PlayFab for some other reason, ensure you close all open handles and call __PFServicesUninitializeAsync__.\n\n```cpp\n    PFEntityCloseHandle(entityHandle);\n    entityHandle = nullptr;\n\n    PFServiceConfigCloseHandle(serviceConfigHandle);\n    serviceConfigHandle = nullptr;\n\n    XAsyncBlock async{};\n    HRESULT hr = PFServicesUninitializeAsync(\u0026async); // Add your own error handling when FAILED(hr) == true\n    hr = XAsyncGetStatus(\u0026async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage\n```\n\n## Async API pattern\n\nThe PlayFab Services SDK follows an [Asynchronous Programming Model](https://learn.microsoft.com/gaming/gdk/_content/gc/system/overviews/async-programming-model). This programming model involves the use of Tasks and Task Queues provided by the [XAsync library](https://learn.microsoft.com/gaming/gdk/_content/gc/system/overviews/async-libraries/async-library-xasync). While it does introduce some complexity, it also brings a high degree of control over asynchronous operations.\n\nThis example shows how to make an asynchronous call to __PFDataGetFilesAsync__.\n\n```cpp\n    auto async = std::make_unique\u003cXAsyncBlock\u003e();\n    async-\u003ecallback = [](XAsyncBlock* async)\n    {\n        std::unique_ptr\u003cXAsyncBlock\u003e asyncBlockPtr{ async }; // take ownership of XAsyncBlock\n\n        size_t resultSize;\n        HRESULT hr = PFDataGetFilesGetResultSize(async, \u0026resultSize);\n        if (SUCCEEDED(hr))\n        {\n            std::vector\u003cchar\u003e getFilesResultBuffer(resultSize);\n            PFDataGetFilesResponse* getFilesResponseResult{ nullptr };\n            PFDataGetFilesGetResult(async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), \u0026getFilesResponseResult, nullptr);\n        }\n    };\n\n    PFDataGetFilesRequest requestFiles{};\n    requestFiles.entity = m_pEntityKey;\n    HRESULT hr = PFDataGetFilesAsync(m_entityHandle, \u0026requestFiles, async.get());\n    if (SUCCEEDED(hr))\n    {\n        async.release(); // at this point, the callback will be called so release the unique ptr\n    }\n\n```\n\n## Error handling\n\nCompleted **XAsync** operations return HTTP status codes. An error status code manifests as a failure **HRESULT** such as **HTTP_E_STATUS_NOT_FOUND** when calling **XAsyncGetStatus()** or one of the **PF*Get()** APIs.\n\nTo see detailed error messages returned by the service see the next section on debugging. These detailed error messages can be useful during development to better understand how the PlayFab service reacts to requests from the client.\n\n## Debugging\n\nThe easiest way to see the results and debug any calls in the PlayFab Services SDK is to enable [Debug Tracing](https://learn.microsoft.com/gaming/playfab/sdks/c/tracing). Enabling debug tracing allows you to both see the results in the debugger output window and hook the results into your game's own logs.\n\n## Reference\n\n[API reference documentation](https://learn.microsoft.com/gaming/playfab/api-references/c/pfauthentication/pfauthentication_members)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplayfab%2Fplayfabcsdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplayfab%2Fplayfabcsdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplayfab%2Fplayfabcsdk/lists"}