Call PgosSDK APIs

PgosSDK provides two types of API: C++ API and Blueprint API. You can call only one type, or mix both types, depending on your needs. Some APIs need to be called before others, that is, you need to call CreatePGOS, InitConfig, LoginPGOS first, which will prepare the working environment for other API calls. Click Programming Quick Start for details.

The FakeAccount interface APIs can be called before LoginPGOS, the FakeAccount interface is used for FAS login.

After completing this tutorial, you will learn:

How to call PgosSDK C++ API.
How to call PgosSDK Blueprint API.

1. Call PgosSDK C++ API

The PgosSDKCpp module in PgosSDK plugin provides PGOS C++ APIs.

1.1 Get Service Interfaces

All service interfaces can be found in PgosSDKCpp.h:

class IPgosSDKCpp : public IModuleInterface
{
public:
    /** Get PgosSDKCpp singleton instance */
    static IPgosSDKCpp& Get();

    /** Create and Destroy PGOS in the main thread */
    virtual void CreatePGOS() = 0;   // Create PGOS service, must be called first before using PGOS service.
    virtual void DestroyPGOS() = 0;  // Destroy PGOS service, should be called during process shutdown if possible.

    /** Server API */
    virtual PgosServerPtr GetServerAPI() const = 0;  // Server global interface
    virtual PgosServerBattlePtr GetServerBattleAPI() const = 0;  // Battle interface
    virtual PgosServerEconomyPtr GetServerEconomyAPI() const = 0;  // Economy interface
    virtual PgosServerHostingPtr GetServerHostingAPI() const = 0;  // Hosting interface
    ...

    /** Client API */
    virtual PgosClientPtr GetClientAPI() const = 0;  // Client global interface
    virtual PgosClientEconomyPtr GetClientEconomyAPI() const = 0;  // Economy interface
    virtual PgosClientFakeAccountPtr GetClientFakeAccountAPI() const = 0;  // FakeAccount interface
    virtual PgosClientPlayerAuthPtr GetClientPlayerAuthAPI() const = 0;  // PlayerAuth interface
    ...
}    

To obtain the corresponding service instance, just call the corresponding Get*API() function. For example, the following code will obtain the service instance of FakeAccount:

auto spFAS = IPgosSDKCpp::Get().GetClientFakeAccountAPI();

After getting the service instance, you can call all its service APIs, which can be found in the file "Core/Pgos{ServiceName}API.h".

1.2 Make API Call

There are synchronous and asynchronous APIs in PgosSDK, generally speaking, APIs with callback parameters are asynchronous, and APIs without callback parameters are synchronous. Asynchronous API callbacks are executed in Game Thread, and we provide two APIs for a function, which provide different callback forms: Delegate callback and TFunction callback, you can choose the callback method you like. As an example, the following are two API declarations for the FAS login function:

DECLARE_DELEGATE_TwoParams(FPgosClientOnLogin, const FPgosResult& /* Result */, const FClientFasLoginInfo* /* Data */)
/**
 * Log in with the specified account.
 * The FAS account does not need to be registered in advance, it can be any string without line breaks ('\r', '\n') and is managed by the game.
 * 
 * @param Account FAS account, if the account is empty, then will use a local historical account.
 * @param ResultDelegate The result delegate after the API execution ends, and it will be called in the GAME THREAD.
 */
void Login(
    const FString& Account,
    FPgosClientOnLogin ResultDelegate) const;

/**
 * Log in with the specified account.
 * The FAS account does not need to be registered in advance, it can be any string without line breaks ('\r', '\n') and is managed by the game.
 * 
 * @param Account FAS account, if the account is empty, then will use a local historical account.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void Login(
    const FString& Account,
    TFunction<void(const FPgosResult& Ret, const FClientFasLoginInfo* Data)> ResultCallback) const;

The following is the sample code of the FAS Login API call:

#include "PgosSDKCpp.h"

// using the TFunction callback.
void SomeUObjectClass::CallWithLambda()
{
    auto spFAS = IPgosSDKCpp::Get().GetClientFakeAccountAPI();
    if (spFAS)
    {
        FString MyAccount = TEXT("SomeAccountString");
        spFAS->Login(MyAccount, [](const FPgosResult& Ret, const FClientFasLoginInfo* LoginInfo) {
            UE_LOG(LogTemp, Log, TEXT("On FAS login callback."));
        });
    }
}

// using the Delegate callback.
void SomeUObjectClass::CallWithDelegate()
{
    auto spFAS = IPgosSDKCpp::Get().GetClientFakeAccountAPI();
    if (spFAS)
    {
        FString MyAccount = TEXT("SomeAccountString");
        FPgosClientOnLogin CallbackDelegate;
        CallbackDelegate.BindUObject(this,&SomeUObjectClass::OnFASLoginCallback);
        spFAS->Login(MyAccount, CallbackDelegate);
    }
}

void SomeUObjectClass::OnFASLoginCallback(const FPgosResult& Result, const FClientFasLoginInfo* Data)
{
    UE_LOG(LogTemp, Log, TEXT("On FAS login callback."));
}

For callback implementations of type TFunction, if the data of the UObject will be accessed in the callback, for lifetime security, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to the UObject. Taking the above FAS Login TFunction API call as an example, the code can be organized as follows:

#include "PgosSDKCpp.h"

// using the  TFunction callback.
void SomeUObjectClass::CallWithLambda()
{
    auto spFAS = IPgosSDKCpp::Get().GetClientFakeAccountAPI();
    if (spFAS)
    {
        FString MyAccount = TEXT("SomeAccountString");
        auto CallbackFunction = IPgosSDKCpp::CreateWeakCallback<FClientFasLoginInfo>
            (this, [](const FPgosResult& Ret, const FClientFasLoginInfo* LoginInfo) {
                UE_LOG(LogTemp, Log, TEXT("On FAS login callback."));
            });
        spFAS->Login(MyAccount, CallbackFunction);
    }
}

1.3 Monitor Events

PgosSDK will trigger certain events when certain things happen, such as when the player session status changes, when a player joins/leaves the Party, and so on. These events are executed in Game Thread. Developers can monitor these events and take appropriate actions (such as updating the UI). Take the OnPlayerSessionChanged event of the PlayerAuth service as an example, you can refer to the following code to monitor the PgosSDK event:

#include "PgosSDKCpp.h"

void SomeUObjectClass::MonitorPlayerSessionEvt()
{
    auto Auth = IPgosSDKCpp::Get().GetClientPlayerAuthAPI();
    if (Auth) {
        Auth->OnPlayerSessionChanged().AddUObject(this, &SomeUObjectClass::OnPlayerSessionChanged);
    }
}

void SomeUObjectClass::OnPlayerSessionChanged(const FClientPlayerSessionChangedEvt& event) {
    UE_LOG(LogTemp, Log, TEXT("pgos player session has changed."));
}

❗Note: To avoid missing events, it is recommended to monitor them before they are triggered.

2. Call PgosSDK Blueprint API

All of the BlueprintCallable functions are placed below the "PGOS" category:

You can easily find the function you need according to what you want to implement, or you can just search it from the search bar if you already know the name. Most of the APIs in PgosSDK are asynchronous actions and are used in similar ways. You can create your Blueprint by following the steps below:

2.1 Make API Calls

In the Executable Actions dialog, search the name of a specific API or find it inside the PGOS category, and select it to add it to your Blueprint.
Fill in the content of input pins if needed.
Select the On Success (or On Failure) pin and drag it to an empty location. In the Executable Actions dialog, search for what you want to do next, for example, Print String, then select it to add it to your Blueprint.
Select the output pin of Error and drag it to an empty location. In the popup dialog, select Break PgosResult, and you can check for error details in the next action of the On Failure pin.
There may be another pin which is the data response of the asynchronous API. Use it in the next action of the On Success pin.

2.2 Monitor Events

If you need to monitor events:

Search for Get Pgos Client Event Dispatcher in the Executable Actions dialog and select it to add it to your Blueprint.
Select the output pin of Return Value and drag it to an empty location. In the popup dialog, search the keyword Bind, and you will see events to bind or unbind. Just select what you need to add it to your Blueprint.

When you are finished, your Blueprint should look similar to the following:

❗ Note
Both of asynchronous API callbacks and triggered events are executed in Game Thread, so it is not recommended to do any time-consuming actions in them.

1. Call PgosSDK C++ API​

1.1 Get Service Interfaces​

1.2 Make API Call​

1.3 Monitor Events​

2. Call PgosSDK Blueprint API​

2.1 Make API Calls​

2.2 Monitor Events​