Documentation

Did you find this helpful?

Linux/C++ Getting Started Guide

This guide will help you make your first API call in C++. A native C++ project can be used a few ways:

  • Stand-alone console Admin tools for maintaining your game
    • The C++ Sdk works great for a stand-alone C++ program
  • Integration into an existing C++ based game engine
    • The C++ Sdk should not be used if we provide a more specific SDK
    • Many C++ based engines also integrate Lua:

If you have any issues, let us know on the Forums.

Linux/C++ Project Setup

  • OS: This guide is written for Linux, using Ubuntu 18.04 LTS
  • Install Requirements (sudo apt install ____ on Ubuntu)
    • g++
    • gdb
    • make
    • cmake
    • libjsoncpp-dev
    • libcurl4-openssl-dev
    • git-all
  • Clone XPlatCppSdk into your project folder
  • Create main.cpp and write Hello World in it:

// main.cpp: entry point for the console application

#include <iostream> 

int main()
{
    std::cout << "Hello World" << std::endl;
    return 0;
}

  • If you're using an IDE, make sure to:
    • Add the following folders to your sources:
      • XPlatCppSdk/cppsdk/source/playfab
    • Add the following folders to your include directories:
      • XPlatCppSdk/cppsdk
      • XPlatCppSdk/cppsdk/include
    • Link the following libraries
      • jsoncpp
      • curl
      • pthread
  • Otherwise, create CMakeLists.txt and fill it with the following:

cmake_minimum_required(VERSION 3.10)
set(CMAKE_CXX_STANDARD 14)

project(PlayFab_Test)

file(GLOB PF_SOURCE XPlatCppSdk/cppsdk/source/playfab/*.cpp)
add_executable(PlayFab_Test ${PF_SOURCE} main.cpp)

include_directories(XPlatCppSdk/cppsdk)
include_directories(XPlatCppSdk/cppsdk/include)
target_link_libraries(PlayFab_Test -ljsoncpp -lcurl -lpthread)

  • Build and run the project inside your IDE, or open Terminal and run:
    • cmake .
    • make
    • ./PlayFab_Test
  • Your project should compile and successfully run Hello World!

Set up your first API call

This guide will provide the minimum steps to make your first PlayFab API call, without any GUI or on-screen feedback. Confirmation will be done with a console print statement.

  • Replace the contents of main.cpp with the following:

// main.cpp: entry point for the console application

#include "playfab/PlayFabClientDataModels.h"
#include "playfab/PlayFabClientApi.h"
#include "playfab/PlayFabSettings.h"
#include <unistd.h>

using namespace PlayFab;
using namespace ClientModels;

bool finished = false;

void OnLoginSuccess(const LoginResult& result, void* customData)
{
    printf("Congratulations, you made your first successful API call!\n");
    finished = true;
}

void OnLoginFail(const PlayFabError& error, void* customData)
{
    printf("Something went wrong with your first API call.\n");
    printf("Here's some debug information:\n");
    printf(error.GenerateReport().c_str());
    printf("\n");
    finished = true;
}

int main()
{
    PlayFabSettings::titleId = "144";

    LoginWithCustomIDRequest request;
    request.CreateAccount = true;
    request.CustomId = "GettingStartedGuide";

    PlayFabClientAPI::LoginWithCustomID(request, OnLoginSuccess, OnLoginFail);

    while (PlayFabClientAPI::Update() != 0)
        sleep(1);

    printf("Press enter to exit\n");
    getchar();
    return 0;
}

Finish and Execute

  • Build and run the project inside your IDE, or open Terminal and run:
    • ./PlayFab_Test
  • When it loads, you should see the following text:
    • "Congratulations, you made your first successful API call!"
  • At this point, you can start making other API calls, and building your game
  • For a list of all available client API calls, see our documentation:
  • Happy coding!

Deconstruct the code

This optional last section describes each part of main.cpp in detail.

  • Includes
    • The PlayFab includes get you access to the the Client APIs. In this example, unistd.h is only used for sleep()
  • using namespaces
    • PlayFab and PlayFab::ClientModels. The first is for API methods and general PlayFab usage, and the latter is for the objects sent to and received by Client API calls
  • OnLoginSuccess, OnLoginFailure are callback functions asynchronously invoked by PlayFabClientAPI.LoginWithCustomID
  • main()
    • PlayFabSettings::titleId = "144";
      • Every PlayFab developer creates a title in Game Manager. When you publish your game, you must code that titleId into your game. This lets the client know how to access the correct data within PlayFab. For most users, just consider it a mandatory step that makes PlayFab work
    • LoginWithCustomIDRequest request; (and field initialization)
      • Most PlayFab API methods require input parameters, and those input parameters are packed into a request object
      • Every API method requires a unique request object, with a mix of optional and mandatory parameters
        • For LoginWithCustomIDRequest, there is a mandatory parameter of CustomId, which uniquely identifies a player and CreateAccount, which allows the creation of a new account with this call.
      • For login, most developers will want to use a more appropriate login method
    • PlayFabClientAPI::LoginWithCustomID(request, OnLoginSuccess, OnLoginFail);
      • Triggers the threaded API call. When complete, OnLoginSuccess or OnLoginFail will be invoked appropriately
    • while (PlayFabClientAPI::Update() != 0) sleep(1);
      • Update returns the number of API calls that are in-progress
      • Update also executes the actual calls to OnLoginSuccess or OnLoginFail, once the threaded API calls are complete
        • This allows your callbacks to execute in a thread-safe manner, when your program is inherently single-threaded
        • True multi-threaded options are also available, but not demonstrated here
    • Inside of OnLoginSuccess:
      • The result object of many API success callbacks will contain the requested information
      • LoginResult contains some basic information about the player, but for most users, login is simply a mandatory step before calling other APIs
    • Inside of OnLoginFailure:
      • API calls can fail for many reasons, and you should always attempt to handle failure
      • Why API calls fail (In order of likelihood)
        • PlayFabSettings.TitleId is not set. If you forget to set titleId to your title, then nothing will work
        • Request parameters. If you have not provided the correct or required information for a particular API call, then it will fail. See error.errorMessage, error.errorDetails, or error.GenerateErrorReport() for more info
        • Device connectivity issue. Cell-phones lose/regain connectivity constantly, and so any API call at any time can fail randomly, and then work immediately after. Going into a tunnel can disconnect you completely
        • PlayFab server issue. As with all software, there can be issues. See our release notes for updates
        • The internet is not 100% reliable. Sometimes the message is corrupted or fails to reach the PlayFab server.
      • If you are having difficulty debugging an issue, and the information within the error callback is not sufficient, please visit us on our forums



Did you find this helpful?