Unreal SDK

The Flock Unreal SDK connects your game to the Flock backend: player auth, save data, economy, remote config, and analytics — configured from Project Settings, with typed Blueprint nodes or C++ generated from your own schemas. Almost every feature works from Blueprint. Each call is a self-contained async node with success and failure pins, and no Target pin to wire — nodes resolve the SDK from the graph they sit in. A few calls are C++ only: reading game patches themselves (Flock Resolve Config Data already returns patched values, so a graph rarely needs them), recording an analytics transaction, and handing the SDK a logger of your own.

Download the Unreal SDK

Get the latest plugin release from GitHub.

Everything below ships today. Multiplayer (parties, sessions, matchmaking and connecting players) has guides of its own, starting with Multiplayer.

Requirements

Unreal Engine 5.4 to 5.8. Every version from 5.5 up is built and run against the full test suite before a release; 5.4 builds and links in a real project, but its test suite has not been run on it yet.
A C++ project. Blueprint-only projects need the C++ toolchain installed to compile the plugin.

Known engine issue on 5.4 and 5.5: a Development package ends with an access violation (0xC0000005) about 60 seconds after it quits. The game has already closed by then, and its log is complete. This is an engine bug, not the SDK’s: Epic fixed it in 5.6, and it happens whether or not any Flock feature ran. Shipping packages leave out the part involved, so they should not be affected, though that has not been measured. If a script judges a packaged run, read the game’s own exit lines in its log rather than the process’s exit code.

Setup

Install the plugin

Download the latest release and extract it into your project’s Plugins/ folder, so you have YourProject/Plugins/FlockUnrealSdk/.Then right-click your .uproject → Generate Visual Studio project files, and rebuild. The plugin is enabled by default — verify under Edit → Plugins → Online Platform → Flock SDK.

Configure

Open Project Settings → Plugins → Flock SDK Settings and fill in the four fields from your game’s page on the dashboard:

Field	Value
API URL	Leave the default (`https://api-flock.qwacks.com`) unless told otherwise
API Key	Identifies your game — treat it like a password
Game Name	Your game’s name from the dashboard
Game Version	Your game version name, e.g. `1.0.0`

Values are saved into your project’s DefaultGame.ini.

Let the version bake

The Game Version ID resolves and bakes itself as soon as those fields are valid, so startup never makes a network call to find it. You can force it any time with Tools → Flock → Resolve Game Version.

Calling Flock from C++

Add "Flock" to your game module’s Build.cs. A Blueprint-only project needs nothing here.

// MyGame.Build.cs
PrivateDependencyModuleNames.Add("Flock");

Your first call

The SDK auto-initializes with your game, so there is nothing to start. Sign a player in, then read something back. The simplest sign-in is by device: no account screen and no password. It takes four things:

This install’s device ID. Leave the device ID empty and the device calls use the SDK’s own: a GUID it makes the first time it is needed and keeps in Saved/Flock/device_id.txt, so the same player comes back on every launch. Read it with ThisDeviceId() on the auth provider, or Flock Get This Device Id in Blueprint.
Sign in once. A sign-in is saved between launches and restored as the SDK starts, so first check whether a player is signed in already, and sign in only when nobody is. A second sign-in ends the analytics session the first one started.
Register, then log in only if needed. Logging in never creates an account, so a first launch must register. A register that creates the account also signs the player in. When the device already has an account, the register succeeds with Already Registered set and signs nobody in: log in then. Never log in after a register that signed the player in.
The sign-in events. On Authenticated says a player is signed in, whichever way it happened. On Auth Expired says a saved sign-in could no longer be renewed, so the player must sign in again.

In Blueprint, build it in the Blueprint that starts your game’s flow, such as your game mode or the level Blueprint, from Event BeginPlay (Flock has started by then):

Sign in once. Call a custom event such as Sign In With This Device, which starts with a Branch on Flock Is Authenticated. True means a saved sign-in was restored: do nothing more.
Register, then log in only if needed. On False, run Flock Register With Device with its Device Id left empty, so it uses this install’s ID. From its On Success, break the Result and branch on Already Registered: True runs Flock Login With Device, its Device Id empty too; False means registering signed the player in.
Run each On Failure through To String (Flock Error) into Print String: the text says what is wrong and how to fix it.

A Sign In With This Device custom event, with no inputs and both Device Id pins left empty so the SDK's kept id is used, branches on Flock Is Authenticated: True prints Already signed in; False runs Flock Register With Device, whose On Success breaks the result and branches on Already Registered: True runs Flock Login With Device, which prints Signed in, and False prints Registered and signed in; each On Failure prints the error through To String (Flock Error) — Sign in once: when nobody is signed in, register the device; when it already has an account, log in with the same ID.

The picture hands the nodes the event’s Device Id input; call the event with it empty to use this install’s ID. In C++, the handlers bound to the events must be UFUNCTION()s:

// MyActor.h: include "FlockEventModels.h" at the top, then in the class declaration
protected:
    virtual void BeginPlay() override;

private:
    void SignInWithThisDevice();
    void ShowGameName();

    UFUNCTION()
    void HandleSignedIn(const FFlockAuthInfo& Info);

    UFUNCTION()
    void HandleSignInExpired();

// MyActor.cpp
#include "FlockSubsystem.h"
#include "FlockEvents.h"
#include "Providers/FlockAuthProvider.h"
#include "Providers/FlockGameProvider.h"

void AMyActor::BeginPlay()
{
    Super::BeginPlay();

    UFlockSubsystem* Sdk = UFlockSubsystem::Get(this);
    if (!Sdk || !Sdk->IsInitialized())
    {
        return;   // The Output Log says why Flock did not start, and how to fix it.
    }

    Sdk->GetEvents()->OnAuthenticated.AddDynamic(this, &AMyActor::HandleSignedIn);
    Sdk->GetEvents()->OnAuthExpired.AddDynamic(this, &AMyActor::HandleSignInExpired);

    if (Sdk->IsAuthenticated())
    {
        ShowGameName();   // Signed in by an earlier launch: Flock restored it as it started.
    }
    else
    {
        SignInWithThisDevice();
    }
}

void AMyActor::SignInWithThisDevice()
{
    UFlockSubsystem* Sdk = UFlockSubsystem::Get(this);
    if (!Sdk || !Sdk->IsInitialized() || Sdk->IsAuthenticated())
    {
        return;   // Not started, or a player is signed in already: a second sign-in ends the first one's session.
    }

    const TWeakObjectPtr<UFlockSubsystem> WeakSdk(Sdk);

    // An empty device ID: this install's own (ThisDeviceId). No display name either.
    // A new device: registering signs the player in, and OnAuthenticated follows.
    // A known device: registering succeeds with bAlreadyRegistered and signs nobody in, so log in.
    Sdk->GetAuthProvider()->RegisterWithDevice(FString(), FString(),
        [WeakSdk](TFlockResult<FFlockRegisterResult> Registered)
        {
            UFlockSubsystem* LiveSdk = WeakSdk.Get();
            FFlockAuthProvider* Auth = LiveSdk ? LiveSdk->GetAuthProvider() : nullptr;
            if (!Auth)
            {
                return;   // The game is closing.
            }
            if (!Registered.bSuccess)
            {
                UE_LOG(LogTemp, Warning, TEXT("%s"), *Registered.Error.ToDisplayText());
                return;
            }
            if (!Registered.Value.bAlreadyRegistered)
            {
                return;   // Signed in.
            }
            Auth->LoginWithDevice(FString(), [](TFlockResult<FFlockPlayerLoginResponse> Login)
            {
                if (!Login.bSuccess)
                {
                    UE_LOG(LogTemp, Warning, TEXT("%s"), *Login.Error.ToDisplayText());
                }
            });
        });
}

void AMyActor::HandleSignedIn(const FFlockAuthInfo& Info)
{
    UE_LOG(LogTemp, Log, TEXT("Signed in as %s"), *Info.PlayerId);
    ShowGameName();
}

void AMyActor::HandleSignInExpired()
{
    SignInWithThisDevice();   // The saved sign-in could not be renewed: sign in again.
}

void AMyActor::ShowGameName()
{
    UFlockSubsystem* Sdk = UFlockSubsystem::Get(this);
    if (!Sdk || !Sdk->IsInitialized())
    {
        return;
    }

    Sdk->GetGameProvider()->GetGame([](TFlockResult<FFlockGameSchema> Game)
    {
        if (Game.bSuccess)
        {
            UE_LOG(LogTemp, Log, TEXT("Playing %s"), *Game.Value.Name);
        }
    });
}

Success looks like Signed in as … then Playing … in the Output Log. A failure logs the call that failed, the server’s reason and a Fix: line: see Error handling. An empty device ID means this install’s own for LoginWithDevice, RegisterWithDevice and LinkDevice and their nodes; any other ID is sent exactly as you pass it. Signing out keeps it. A new one is made when the file is gone (a reinstall on a phone, a deleted or cleaned Saved folder), and with a new ID comes a new player, with none of their progress: to keep players across a reinstall or a new device, offer account linking (an email or a platform account). When the file can be neither read nor written, the SDK logs a warning saying why and how to fix it, and uses an ID for that run only. (FPlatformMisc::GetDeviceId cannot be the ID: it is empty on Windows, Mac and Linux.) Pass an ID of your own only in two cases:

Your game already signs players in with an ID of its own (a GUID kept in a save game or a file, as earlier versions of this page showed): keep passing that same ID. Leaving it empty would sign every existing player in to a new, empty account.
Two copies of the game started from one project folder (Play In Editor beside a standalone game, two game clients on one machine) share Saved/, so they share the kept ID and are one player. Pass another ID in one of them.

Completion lambdas hold a TWeakObjectPtr to the SDK, never the raw UFlockSubsystem* or this. The answer can arrive after the game has started shutting down, and a raw pointer would then point at nothing.

Initialization

Auto Initialize on Load (in Flock SDK Settings, under Initialization) is on by default, so UFlockSubsystem is running before BeginPlay. To defer past a splash screen or EULA, turn it off and call InitializeFromSettings() yourself (in Blueprint, Initialize From Settings on the Flock subsystem):

// After your splash screen or EULA, with Auto Initialize on Load off.
if (UFlockSubsystem* Sdk = UFlockSubsystem::Get(this))
{
    Sdk->InitializeFromSettings();
}

Because init reads a baked version ID, it is synchronous and makes no network call — your game starts the same offline as online.

Authenticate a player

Email, device ID, Google, Apple, Steam, Facebook, and Discord. The SDK exchanges the credential your platform SDK produced for a Flock session, stores the tokens encrypted between launches, restores the session automatically on startup, and refreshes expired access tokens silently. Every method is an async node under Flock | Auth (Flock Login With Email, Flock Register With Device, and so on), or a call on the auth provider in C++. Login and register are separate calls: logging in never creates an account, and a register that creates one also signs the player in. Each method follows the device pattern in Your first call. For example, an email sign-in from your own sign-in screen:

// Email and Password come from your own sign-in screen.
void AMyActor::SignInWithEmail(const FString& Email, const FString& Password)
{
    UFlockSubsystem* Sdk = UFlockSubsystem::Get(this);
    if (!Sdk || !Sdk->IsInitialized() || Sdk->IsAuthenticated())
    {
        return;   // Not started, or a player is signed in already: sign out first to change players.
    }

    Sdk->GetAuthProvider()->LoginWithEmail(Email, Password,
        [](TFlockResult<FFlockPlayerLoginResponse> Result)
        {
            if (Result.bSuccess)
            {
                UE_LOG(LogTemp, Log, TEXT("Signed in as %s"), *Result.Value.PlayerId);
            }
            else
            {
                UE_LOG(LogTemp, Warning, TEXT("%s"), *Result.Error.ToDisplayText());
            }
        });
}

Every method, the register calls and the account flows are on Authentication.

You never pass a player ID. Reads and commands act for the signed-in player; the Player Id pin is tucked into each node’s advanced section for the rarer case of acting on someone else.

Work with your game data

One menu click turns your backend’s templates, configs, and shops into typed nodes. Tools → Flock → Sync Schemas — no C++, no toolchain, no compile step.

The Tools menu showing Resolve Game Version, Sync Schemas and Clean Generated — Tools → Flock → Sync Schemas generates typed assets from your own schemas.

Reading a config becomes one node that carries its own fetch and ID:

A generated Get Gameplay macro node feeding a Break node — Get Gameplay fetches, converts, and hands back a typed struct — break it for real pins.

With a player signed in, a gameplay or feature config reads as Flock resolves it for that player: the newest patch, then the overrides of the player’s segments, then their own. With nobody signed in it reads the game-wide values, so a config read before sign-in should be read again once the player signs in (from On Authenticated). See Remote config. Changing a player’s data is Get → the engine’s Set members in struct → Save:

Get Player Level into Set members into Save Player Level — Get hands out the row ID alongside the struct, because Save needs it.

Tick the members you want to write. Unticked ones keep whatever Get fetched.

The Details panel for a Set members in struct node — Ticking a member exposes its pin — untouched members are left exactly as they were.

Shop purchases and currency grants take a generated dropdown rather than an ID you type:

A Flock Purchase node in a Blueprint graph — Purchase by picking an item — the ID is baked in and cannot be mistyped.

Prefer C++?

Switch Codegen Target to C++ and a sync emits a generated module instead — a USTRUCT per template and config, a UENUM per ID set, and a typed call surface.

The Codegen Target setting in Project Settings — Codegen Target picks what a sync emits. Blueprint is the default.

The sync writes the module to Source/FlockGenerated and registers it in your .uproject. Build and restart the editor, then add the module to your game module’s Build.cs and include its header:

// MyGame.Build.cs
PrivateDependencyModuleNames.AddRange(new string[] { "Flock", "FlockGenerated" });

The names below come from a game with a PlayerLevel template, a GemPack shop item and a Gold currency; yours follow your own schemas.

#include "FlockGeneratedAccessors.h"

void AMyActor::SaveProgressAndBuy()
{
    const TWeakObjectPtr<AMyActor> WeakThis(this);
    FFlockGenerated::GetPlayerLevel(this,
        [WeakThis](TFlockResult<FPlayerLevelTemplate> Result, const FString& RowId)
        {
            if (!Result.bSuccess || !WeakThis.IsValid())
            {
                return;
            }

            FPlayerLevelTemplate Progress = Result.Value;
            Progress.Level.Stage = 5;
            FFlockGenerated::SavePlayerLevel(WeakThis.Get(), RowId, Progress, nullptr);
        });

    FFlockGenerated::Purchase(this, EFlockShopItemId::GemPack,
        [](TFlockResult<FFlockPurchaseResult> Bought)
        {
            if (!Bought.bSuccess)
            {
                UE_LOG(LogTemp, Warning, TEXT("%s"), *Bought.Error.ToDisplayText());
            }
        });
    FFlockGenerated::AddFunds(this, EFlockCurrencyId::Gold, 100,
        [](TFlockResult<FFlockPlayerData> Credited)
        {
            if (!Credited.bSuccess)
            {
                UE_LOG(LogTemp, Warning, TEXT("%s"), *Credited.Error.ToDisplayText());
            }
        });
}

A project uses one target or the other. Generated C++ structs are BlueprintType, so graphs still see your types after switching.

Samples

The plugin ships two samples made of Blueprints only, with no C++ of their own (the shop sample from 1.48.0). Turn on Show Plugin Content in the Content Browser’s settings to see them under the plugin’s Content/Samples. Both need Project Settings → Plugins → Flock SDK Settings filled in first.

Shop (Content/Samples/Shop) — open the FlockShopSample level and play it: log a device in, open the shop, and buy with the wallet or real money (the phone’s store, or a web checkout on Windows, Mac and Linux), use what the player holds, restore purchases. It needs a shop in the Flock dashboard, the tag currency on the player template that holds the wallet, and for real-money items their store product ids. See Shops & inventory and In-App Purchases.
Multiplayer (Content/Samples/Multiplayer) — set Game Instance Class to BP_FlockSampleGameInstance under Project Settings → Maps & Modes, then play the FlockMultiplayerSample level in two standalone games: sign in with a different device name in each (one name would make them one player), then host and join by code, or quick match with a queue your game has in the Flock dashboard. See Multiplayer.

To build on one, copy its folder into your project’s Content and change the copies.

Explore features

Players & auth

Account linking

Player data

Shops & inventory

In-App Purchases

Web Payments

Remote config

Leaderboards

Game notifications

Assets

Analytics & events

Multiplayer

Playtesting with Protokite

Advanced settings

Project Settings also tunes analytics, HTTP retries, the offline cache, and the codegen paths. The defaults are sensible — change them only when you need to. Turning on Enable Debug Logs traces every network call under the LogFlock category, and each line names its caller so you can tell a Blueprint graph from C++:

[Flock SDK] -> GET .../v1/player_data?player_id=01KY... [Blueprint 'bpTest']
[Flock SDK] <- 200 GET .../v1/player_data?player_id=01KY... (34 ms, 2060 bytes) [Blueprint 'bpTest']

Offline caching

Config, game, shop-catalog, and player-template reads are cached to disk, scoped to your game version, and served when the server is unreachable — the server is always tried first, and there are no TTLs. A signed-in player’s config values are kept per player, so offline a read gives that player’s last values, else the game-wide ones, never another player’s. Player data writes queue offline and replay automatically when the connection returns. Currency grants never do: a grant fails rather than being queued, and is never re-sent after an ambiguous failure, so it cannot double-credit.

Error handling

Every call answers with a TFlockResult<T> rather than throwing — Unreal builds with exceptions off. Check bSuccess, then read Value or Error. Inside any completion, where Result is the TFlockResult it received:

if (!Result.bSuccess && Result.Error.ErrorCode == EFlockErrorCode::ShopInsufficientFunds)
{
    // The server declined — not enough funds.
}

Error.ToDisplayText() says what went wrong and how to fix it: the call that failed, the server’s own reason, the coded identifier and the HTTP status, then a Fix: line. The Output Log carries the same text for every failed call.

if (!Result.bSuccess)
{
    UE_LOG(LogTemp, Warning, TEXT("%s"), *Result.Error.ToDisplayText());
}

Output Log

Fetch shop item failed: Shop item with ID 'GoldItem' not found [shop_item.shop_item_not_found, HTTP 404]
Fix: No shop item has that id in this game. A purchase (Purchase, Flock Purchase) and GetItem (Flock Get Shop Item) take the shop item's Id, FFlockShopItem::Id, ...

Error.Message holds what went wrong on its own and Error.Hint the fix on its own; neither is ever empty on a failure. In Blueprint, every async node has an On Failure pin carrying the same Error. To String (Flock Error) turns it into the display text, and Break Flock Error gives its Error Code, an enum to compare without matching strings.

The full API reference, per-feature guides, and codegen details live in the SDK README.

Getting Started

Concepts

Features

Reference

Download the Unreal SDK

Requirements

Setup

Your first call

Initialization

Authenticate a player

Work with your game data

Prefer C++?

Samples

Explore features

Players & auth

Account linking

Player data

Shops & inventory

In-App Purchases

Web Payments

Remote config

Leaderboards

Game notifications

Assets

Analytics & events

Multiplayer

Playtesting with Protokite

Advanced settings

Offline caching

Error handling

Download the Unreal SDK

​Requirements

​Setup

​Your first call

​Initialization

​Authenticate a player

​Work with your game data

​Prefer C++?

​Samples

​Explore features

Players & auth

Account linking

Player data

Shops & inventory

In-App Purchases

Web Payments

Remote config

Leaderboards

Game notifications

Assets

Analytics & events

Multiplayer

Playtesting with Protokite

​Advanced settings

​Offline caching

​Error handling

Requirements

Setup

Your first call

Initialization

Authenticate a player

Work with your game data

Prefer C++?

Samples

Explore features

Advanced settings

Offline caching

Error handling