Service providers
A service provider serves one online service of the backend from a class of the game: stats from a web API of the studio while EOS keeps the login and the sessions, cloud files in a storage of the game, matchmaking tickets at FlexMatch. The provider is a Blueprint (or C++) class; the rest of Pulse Online (requests, subsystems, widgets, bridges) does not know that the service is not the one of the backend.
Pulse Online has one adapter per service a provider can serve. Create a Blueprint of the adapter (Add > Pulse > Online or the Create step of the Pulse window, where each adapter has an entry with its name), override the operations you need and name the class in the settings:
| Adapter | Service | Operations |
|---|---|---|
| Online Achievement Provider | IPulseOnlineAchievementService | Query Definitions, Query States, Unlock Achievements, Ingest Stats, Query Stats |
| Online Server Achievement Provider | IPulseOnlineServerAchievementService | the same for any player, written by a trusted server |
| Online Stats Provider | IPulseOnlineStatsService | Query Stats, Update Stats |
| Online Server Stats Provider | IPulseOnlineServerStatsService | Query Stats, Update Stats for any player |
| Online Leaderboard Provider | IPulseOnlineLeaderboardService | Query Leaderboard, Supports Range |
| Online Title Storage Provider | IPulseOnlineTitleStorageService | Enumerate Files, Read File |
| Online User Storage Provider | IPulseOnlineUserStorageService | Get Capabilities, Enumerate Files, Read File, Write File (with condition), Delete File |
| Online Moderation Provider | IPulseOnlineModerationService | Send Report, Query Active Sanctions |
| Online Matchmaking Provider | IPulseOnlineMatchmakingService | Start Ticket, Cancel Ticket; Update Ticket and Finish Ticket answer |
| Online User Content Provider | IPulseOnlineUserContentService | Query Items, Subscribe, Download, Upload, Get Item State, Get Installed Items; Notify Item Changed |
| Online Anti-Cheat Provider | IPulseOnlineAntiCheatService | Check Pre Login, Register Client, Unregister Client, Receive From Client, Begin/End Client Session, Receive From Server; Send To Client, Send To Server, Report Violation |
There are no adapters for the identity (login state and net ids), lobbies and game sessions (data of the backend, travel), friends, presence, avatars, commerce, voice, network and platform; they come from backends and extensions.
How an operation answers
Adapters are providers of PulseFoundation (UPulseProvider, see providers.md of PulseFoundation). Every operation gets a request id; the provider answers it with the Finish function of the operation, at once inside the operation or later from a timer, a web request or a task:
- Operations without data answer with Finish Operation (Result).
- Operations with data have their own Finish function, e.g. Finish Query Stats (Result, Stats).
- An operation the provider does not override answers Not Supported (
Pulse.Result.Failure.Online.NotSupported). - Every request is answered exactly once: a second or late answer is ignored with a warning, a request that waits too long fails with
Pulse.Result.Failure.Timeout(Get Default Timeout, 30 seconds; matchmaking tickets and user content have no timeout), and the requests still open when the backend stops or another provider replaces this one answerPulse.Result.Failure.Cancelled. - An answer given inside the operation reaches the caller inside its call, before the service function returns (also the Not Supported of an operation the provider does not override, and Update Ticket inside Start Ticket). Callers of the services handle that; a C++ provider that never wants to answer inside the call sets
SetDelivery(EPulseProviderDelivery::NextTick)inOnInitialize.
The Result is a Pulse result. The services of Pulse Online work with FPulseOnlineResult; the adapter turns the answer back with Pulse::Online::FromResult: the reasons of the online layer and of PulseFoundation become their error ids again (Conflict stays Pulse.Online.Conflict, Timeout stays Pulse.Online.Timeout), any other reason becomes Pulse.Online.Unknown with the text of the result. Child tags of these reasons count as the reason. An online result in the details (an answer made with ToResult) comes back as it was, unless the provider changed the reason since.
Answer a write of the user storage whose condition does not hold with the reason Pulse.Result.Failure.Online.Conflict, so cloud saves see the conflict (Cloud Storage). Check Write Condition of the user storage adapter applies the rules of IfMissing and IfVersion with their texts, Make Content Hash makes the sha1: hash of the bytes (a version for a storage without its own).
A user storage provider whose Get Capabilities says bVersion must honour IfMissing and IfVersion. Cloud saves write their index with IfVersion on such a service; a provider that answers Not Supported there fails every save.
Choosing a provider
Settings: Project Settings > Pulse > Online > Service Overrides: the name of the service (picked from a list) to the provider class. The backend makes the providers when it starts, after its own services and its extensions, so a provider replaces what they registered. A provider that serves another service than its key is skipped with an error in LogPulseOnline; the Check step of the Pulse window reports the same entry.
Runtime: UPulseOnlineBackendSubsystem::SetServiceOverride(ServiceName, ProviderClass) serves the service by the provider from now on: the running backend makes it at once, and it wins over the settings after every SwitchBackend. A provider the running backend refuses (it serves another service, is abstract or makes no service) is not kept and the function returns false. The service name has a list to pick from in Blueprint. None as class removes the runtime override (the running backend keeps the provider until it starts again). GetServiceOverride(ServiceName) returns the class.
UPulseOnlineBackend::GetServiceProvider(ServiceName) returns the provider that serves a service, and GetServiceSource(ServiceName) where a service comes from (Backend, Extension, Provider, Runtime); the cheat PulseOnlineStatus prints both.
Example: only stats through a service of the game
- Create a Blueprint of Online Stats Provider,
BP_StudioStats. - Override Query Stats: send a web request to the stats API; when it answers, build an array of
FPulseOnlineUserStats(user and stat name to value) and call Finish Query Stats with the request id, a success (Make Pulse Success) and the stats. On an error call it withMake Pulse Failureand a reason. - Override Update Stats: send the changes, then Finish Operation.
- Project Settings > Pulse > Online > Service Overrides:
IPulseOnlineStatsService→BP_StudioStats.
Blueprint: A stats provider in Blueprint
- Blueprint class of
Online Stats Provider→ overrideQuery Stats(Request Id, Local User Id, User Ids, Stat Names). - Send the web request of the game; in its answer build an array of
Pulse Online User Stats(User Id, Stats map). Finish Query Stats(Request Id, Result =Make Pulse Success, Stats). On an error:Make Pulse Failurewith a reason.- Override
Update Statsthe same way and answer withFinish Operation; Project Settings > Pulse > Online > Service Overrides:IPulseOnlineStatsService→ the Blueprint.
The stats subsystem, the leaderboards widget and PulseAchievementOnlineBridge now read and write the stats of the game service; login, sessions and the party stay on EOS.
C++ providers
A C++ provider derives from the adapter of its service and either overrides the _Implementation functions or returns its own native service from MakeService (the service must have the name of the adapter, GetServiceName):
UCLASS()
class UMyStatsProvider : public UPulseOnlineStatsProvider
{
GENERATED_BODY()
public:
virtual TSharedPtr<IPulseOnlineService> MakeService() override
{
return MakeShared<FMyStatsService>(GetBackend());
}
};
The backend owns the provider (GetBackend()), initializes it before MakeService and ends it when it stops or when another service replaces it. Native services of the adapters forward each call as a request; a provider that answers off the game thread posts its answer to the inbox of the provider (GetInbox).
Extensions and DisabledExtensions
Backend extensions (UPulseOnlineBackendExtension, C++) still run before the providers. Disabled Extensions in the settings switches single extensions off, e.g. the Steam extension of PulseOnlineSteam in a build that only uses EOS. See Backends.